home *** CD-ROM | disk | FTP | other *** search
/ APDL Public Domain 1 / APDL_PD1A.iso / clock_time / sensible / Docs / Sensible
Encoding:
Text File  |  1995-05-09  |  11.3 KB  |  283 lines
  1. File        : Sensible
  2. Date        : 10-May-95
  3. Author      : © A.Thoukydides, 1995
  4. Description : Description of the "Sensible Time" module.
  5.  
  6.  
  7. INTRODUCTION
  8.  
  9. The "Sensible Time" module allows dates to be displayed in most applications
  10. more sensibly than with the system default format. The following table
  11. illustrates the way in which a few dates are displayed by the Filer "Full
  12. info" display with and without this module loaded on the 1st May 1995.
  13.     
  14.     Original display    New display
  15.     
  16.     01 May 1995         Today
  17.     30 Apr 1995         Yesterday
  18.     26 Apr 1995         Wednesday
  19.     25 Apr 1995         Tue, 25 Apr
  20.     01 Dec 1994         01 Dec 1994
  21.  
  22. This module is FreeWare; it may be freely used and copied. However, I retain
  23. full copyright. See the section on "LEGAL MATTERS" for more details.
  24.  
  25.  
  26. USAGE
  27.  
  28. It is possible to use this module just by loading it, e.g. double-clicking on
  29. it. This may be performed at any time, but probably the best way is to load
  30. it automatically in your boot sequence. If you have a Risc PC then simply
  31. place the module in the "$.!Boot.Choices.Boot.PreDesk" directory. Otherwise
  32. add a line "RMEnsure SensibleTime 0.00 RMLoad System:modules.Sensible" to
  33. your !Boot file, and place the module in your !System.Modules directory.
  34.  
  35. No further installation is required to use "Sensible Time". However, you may
  36. wish to read the next section on "CUSTOMISATION" to discover how its behaviour
  37. can be altered.
  38.  
  39.  
  40. CUSTOMISATION
  41.  
  42. It is recommended that you have a look at pages 1-402/1-403 ("Format field
  43. names") and 3-738/3-739 ("Message file format") of the "RISC OS 3
  44. Programmer's Reference Manual" before reading this section.
  45.  
  46. This module uses a messages file accessed as "Sensible:Messages" to configure
  47. its behaviour. The default configuration is contained in the pseudo-file
  48. "Resources:$.Resources.Sensible.Messages", which currently contains:
  49.  
  50.     # Formats that prevent substitution
  51.     STOP1:%we
  52.     STOP2:%w3
  53.     STOP3:%dy-%m3-%yr
  54.  
  55.     # Wildcarded formats to replace
  56.     SRCH1:%dy#%m3#%ce%yr
  57.     SRCH2:%dy#%m3#%yr
  58.     SRCH3:%dy#%mn#%yr
  59.  
  60.     # Replacement format strings *must* be NULL terminated
  61.     TMRW1:Tomorrow<0>
  62.     TODY1:Today<0>
  63.     YSTR1:Yesterday<0>
  64.     WEEK1:%we<0>
  65.     TODY2/YSTR2/WEEK2:%w3<0>
  66.     YEAR1:%w3, %dy %m3<0>
  67.  
  68. Note: "<0>" is actually a single ASCII NULL character (value 0).
  69.  
  70. An alternative configuration may be used by pointing "Sensible$Path" to a
  71. directory containing an alternative messages file on disc.
  72.  
  73. As can be clearly seen from the default file, there are three areas of
  74. configuration:
  75.  
  76.     1) Formats that prevent substitution.
  77.     
  78.         The format string is searched for any occurrence of the text
  79.         associated with tokens beginning "STOP". If any matches are found
  80.         then no substitution is performed on the format string before
  81.         conversion proceeds. This is useful to prevent the day name appearing
  82.         twice in formats that already contain the day once.
  83.         
  84.         The search is not case-sensitive, and supports "#" as a single
  85.         character wild-card. Any number of "STOP<x>" tokens may be supplied
  86.         (including zero), where <x> can be any sequence of characters that
  87.         are valid in a token.
  88.  
  89.     2) Formats to replace
  90.     
  91.         The format string is searched for any occurrence of the text
  92.         associated with tokens beginning "SRCH". Any matches are replaced by
  93.         one of the replacement formats from the next section.
  94.         
  95.         As with the "STOP" tokens any number of "SRCH<x>" tokens may be
  96.         used. The search is also case-insensitive, and "#" is supported as a
  97.         wild-card.
  98.     
  99.     3) Replacement format strings
  100.     
  101.         The final section specifies the replacement format strings which
  102.         should be used for different relative dates. The possible tokens are:
  103.         
  104.             Principal   Auxiliary
  105.             
  106.             "PAST1"     "PAST2"     An earlier year
  107.             "YEAR1"     "YEAR2"     More than five days ago, if the same year
  108.             "WEEK1"     "WEEK2"     Two to five days ago, if the same year
  109.             "YSTR1"     "YSTR2"     Previous day, if the same year
  110.             "TODY1"     "TODY2"     Same day
  111.             "TMRW1"     "TMRW2"     The next day, if the same year
  112.             "FUTR1"     "FUTR2"     A future year, or after the next day
  113.         
  114.         All of these tokens are optional. Auxiliary strings are only used if
  115.         the corresponding principal string exists but generates an error when
  116.         used, e.g. if the field width is too narrow to contain the resulting
  117.         date string. If replacement is unsuccessful the original format
  118.         string is used instead.
  119.         
  120.         All replacement format strings *must* be terminated with NULL
  121.         characters to prevent spurious errors.
  122.         
  123.         Note that a different year takes priority over the other choices of
  124.         substitution; this is deliberate.
  125.  
  126. The tokens may appear in any order within the Messages file. The only time
  127. that ordering is important is when one search string ("SRCH<x>" token) could
  128. contain part of another, in which case the first matching token is used.
  129.  
  130.  
  131. LEGAL MATTERS
  132.  
  133. The "Sensible Time" module and documentation is supplied "as is"; no
  134. warranty, express or implied, of the merchantability of this software or its
  135. fitness for any particular purpose is given. In no circumstances shall the
  136. author, or any provider or distributor of this software, be liable for any
  137. damage, loss of profits, or any indirect or consequential loss arising out of
  138. the use of this software or inability to use this software.
  139.  
  140. This module is FreeWare. Permission is granted for anyone to distribute it
  141. unchanged and in its entirety, providing that no profit is made in the
  142. process. The "Sensible Time" module may not be distributed if modified or
  143. incomplete; neither may it be distributed without this documentation.
  144.  
  145. To use this module, or any part of it, as part of a system or other
  146. application that is for sale (for however much and for whatever reasons) or
  147. released as copyright material then the author's express permission in
  148. writing must be obtained. The author maintains copyright on all the material
  149. supplied and reserves the right to change these conditions at any time
  150. without notice.
  151.  
  152.  
  153. CONTACTING THE AUTHOR
  154.  
  155. I would be interested in hearing of any bugs or other unexpected features in
  156. this module, and will endeavour to correct any such problems in future
  157. releases. Suggestions for improvements are also most welcome. Implementation
  158. depends upon practicability and on how much spare time I have.
  159.  
  160. If you have any comments on this program, or would like to suggest ways in
  161. which it could be improved, I can be contacted at one of the following
  162. addresses:
  163.     
  164.     Until June 1995:
  165.         
  166.         19 Museum Road
  167.         Oxford
  168.         OX1 3PX
  169.         
  170.         alexander.thoukydides@lincoln.oxford.ac.uk
  171.     
  172.     After June 1995:
  173.     
  174.         Thalna
  175.         2 Dukes Drive
  176.         Bearwood
  177.         Bournemouth
  178.         Dorset
  179.         BH11 9SZ
  180.  
  181. If in any communication you make specific reference to the program code please:
  182.  
  183.     Quote the version number and date of the module.
  184.     
  185.     Refer only to the module as released.
  186.     
  187.     Supply as many details as possible about the problem, including the
  188.     hardware and software configuration of the machine being used.
  189.  
  190. Please send a stamped and self addressed envelope, or give details of how to
  191. contact via e-mail, if you would like a reply.
  192.  
  193. I hope you find this module of some use.
  194.  
  195.  
  196. ACKNOWLEDGEMENTS
  197.  
  198. I would like to the thank the following people for their contributions to
  199. the development of this module:
  200.  
  201.     Acorn Computers - The Risc PC, RISC OS and the ObjAsm assembler.
  202.     Aidan Corey     - Thorough testing, and good ideas for improvements.
  203.     Dominic Symes   - The brilliant !Zap editor; get a copy immediately.
  204.     Colin Turnbull  - Reminding me that I should be revising.
  205.     Robin Watts     - !Larger, the greatest backdrop program ever.
  206.     Rob Westwood    - The original idea behind this program.
  207.  
  208. and everyone at the Acorn User Group in Oxford.
  209.  
  210.  
  211. THINGS TO DO
  212.  
  213. The following are changes that may be made to this module sometime in the
  214. future:
  215.  
  216.     Check for format buffer overflow - currently a 1024 byte fixed length
  217.     buffer is used whilst processing the format strings, without any checks
  218.     for overflow.
  219.     
  220.     Incorporate extra %xx tokens for special purposes.
  221.  
  222.     Improve the error handling. If any part of initialisation fails then the
  223.     correct point in the finalisation code should be jumped to allowing any
  224.     successful initialisation to be undone. Memory allocation and deallocation
  225.     should also be more controlled.
  226.     
  227.  
  228. VERSION HISTORY
  229.  
  230. 0.00 (25-Apr-95)    Original development version.
  231.  
  232. 0.01 (26-Apr-95)    Writes to Territory Manager workspace to install as
  233.                     current territory without being the configured territory.
  234.  
  235. 0.02 (26-Apr-95)    Format strings containing the day not replaced to correct
  236.                     problem with both BASIC and the Sys$* code variables
  237.                     expecting fixed width fields. Modified string padded or
  238.                     truncated to original length.
  239.  
  240. 0.03 (28-Apr-95)    Installation routine legalised by reinitialising Territory
  241.                     Manager with OS_Byte vector intercepted to pretend that
  242.                     this is the configured Territory. Added replacement format
  243.                     for earlier the same year. Corrected stack handling over
  244.                     nested SWI calls. Only performs susbtitution if text would
  245.                     not require truncation.
  246.  
  247. 0.04 (29-Apr-95)    Added second choice replacement formats to cope better
  248.                     with small field widths. Substitutions padded individually
  249.                     within each replaced section. Comparisons made case
  250.                     insensitive, and wild-cards supported.
  251.  
  252. 0.05 (01-May-95)    Messages file generated on-the-fly for Territory Manager
  253.                     to give the new territory the same name as the configured
  254.                     territory to avoid problems with applications using the
  255.                     name of the territory to load resources. Installs and uses
  256.                     messages file for configuration.
  257.  
  258. 0.06 (02-May-95)    Preprocessing of configuration messages file to improve
  259.                     conversion performance. Error checking during conversions
  260.                     improved.
  261.  
  262. 0.07 (04-May-95)    Added substitutions for previous years, tomorrow and the
  263.                     future. Improved handling of errors during substitution.
  264.                     Preprocessed substitution messages also for even faster
  265.                     conversions.
  266.  
  267. 0.08 (05-May-95)    Improved macros for subroutine handling, making the code
  268.                     more likely to be correct and shortening the module by
  269.                     32 bytes.
  270.  
  271. 0.09 (07-May-95)    Intercepts Territory Manager SWIs by using the same SWI
  272.                     chunk number and ensuring that this module is the most
  273.                     recently initialised. This has the advantage that a new
  274.                     territory is not required.
  275.  
  276. 1.00 (09-May-95)    First official release version. Changed default
  277.                     configuration to use fully wild-carded search strings
  278.                     and using extra specific stop strings to obtain desired
  279.                     behaviour.
  280.  
  281. 1.01 (10-May-95)    Corrected bug which prevented alternative substitutions
  282.                     from working.
  283.