File        : Sensible
Date        : 31-Jan-98
Author      :  A.Thoukydides, 1995, 1998
Description : Description of the "Sensible Time" module.


INTRODUCTION

The "Sensible Time" module allows dates to be displayed in most applications
more sensibly than with the system default format. The following table
illustrates the way in which a few dates are displayed by the Filer "Full
info" display with and without this module loaded on the 1st May 1995.
    
    Original display    New display
    
    01 May 1995         Today
    30 Apr 1995         Yesterday
    26 Apr 1995         Wednesday
    25 Apr 1995         Tue, 25 Apr
    01 Dec 1994         01 Dec 1994

This module is FreeWare; it may be freely used and copied. However, I retain
full copyright. See the section on "LEGAL MATTERS" for more details.


USAGE

It is possible to use this module just by loading it, e.g. double-clicking on
it. This may be performed at any time, but probably the best way is to load
it automatically in your boot sequence. If you have a Risc PC then simply
place the module in the "$.!Boot.Choices.Boot.PreDesk" directory. Otherwise
add a line "RMEnsure SensibleTime 0.00 RMLoad System:modules.Sensible" to
your !Boot file, and place the module in your !System.Modules directory.

No further installation is required to use "Sensible Time". However, you may
wish to read the next section on "CUSTOMISATION" to discover how its behaviour
can be altered.


CUSTOMISATION

It is recommended that you have a look at pages 1-402/1-403 ("Format field
names") and 3-738/3-739 ("Message file format") of the "RISC OS 3
Programmer's Reference Manual" before reading this section.

This module uses a messages file accessed as "Sensible:Messages" to configure
its behaviour. The default configuration is contained in the pseudo-file
"Resources:$.Resources.Sensible.Messages", which currently contains:

    # Formats that prevent substitution
    STOP1:%we
    STOP2:%w3
    STOP3:%dy-%m3-%yr

    # Wildcarded formats to replace
    SRCH1:%dy#%m3#%ce%yr
    SRCH2:%dy#%m3#%yr
    SRCH3:%dy#%mn#%yr

    # Replacement format strings *must* be NULL terminated
    TMRW1:Tomorrow<0>
    TODY1:Today<0>
    JNOW1:Just now<0>
    YSTR1:Yesterday<0>
    WEEK1:%we<0>
    TODY2/JNOW2/YSTR2/WEEK2:%w3<0>
    YEAR1:%w3, %dy %m3<0>

Note: "<0>" is actually a single ASCII NULL character (value 0).

An alternative configuration may be used by pointing "Sensible$Path" to a
directory containing an alternative messages file on disc.

As can be clearly seen from the default file, there are three areas of
configuration:

    1) Formats that prevent substitution.
    
        The format string is searched for any occurrence of the text
        associated with tokens beginning "STOP". If any matches are found
        then no substitution is performed on the format string before
        conversion proceeds. This is useful to prevent the day name appearing
        twice in formats that already contain the day once.
        
        The search is not case-sensitive, and supports "#" as a single
        character wild-card. Any number of "STOP<x>" tokens may be supplied
        (including zero), where <x> can be any sequence of characters that
        are valid in a token.

    2) Formats to replace
    
        The format string is searched for any occurrence of the text
        associated with tokens beginning "SRCH". Any matches are replaced by
        one of the replacement formats from the next section.
        
        As with the "STOP" tokens any number of "SRCH<x>" tokens may be
        used. The search is also case-insensitive, and "#" is supported as a
        wild-card.
    
    3) Replacement format strings
    
        The final section specifies the replacement format strings which
        should be used for different relative dates. The possible tokens are:
        
            Principal   Auxiliary
            
            "PAST1"     "PAST2"     An earlier year
            "YEAR1"     "YEAR2"     More than five days ago, if the same year
            "WEEK1"     "WEEK2"     Two to five days ago, if the same year
            "YSTR1"     "YSTR2"     Previous day, if the same year
            "TODY1"     "TODY2"     Same day
            "JNOW1"     "JNOW2"     Within the last ten minutes
            "TMRW1"     "TMRW2"     The next day, if the same year
            "FUTR1"     "FUTR2"     A future year, or after the next day
        
        All of these tokens are optional. Auxiliary strings are only used if
        the corresponding principal string exists but generates an error when
        used, e.g. if the field width is too narrow to contain the resulting
        date string. If replacement is unsuccessful the original format
        string is used instead.
        
        All replacement format strings *must* be terminated with NULL
        characters to prevent spurious errors.
        
        Note that a different year takes priority over the other choices of
        substitution; this is deliberate.

The tokens may appear in any order within the Messages file. The only time
that ordering is important is when one search string ("SRCH<x>" token) could
contain part of another, in which case the first matching token is used.


LEGAL MATTERS

The "Sensible Time" module and documentation is supplied "as is"; no
warranty, express or implied, of the merchantability of this software or its
fitness for any particular purpose is given. In no circumstances shall the
author, or any provider or distributor of this software, be liable for any
damage, loss of profits, or any indirect or consequential loss arising out of
the use of this software or inability to use this software.

This module is FreeWare. Permission is granted for anyone to distribute it
unchanged and in its entirety, providing that no profit is made in the
process. The "Sensible Time" module may not be distributed if modified or
incomplete; neither may it be distributed without this documentation.

To use this module, or any part of it, as part of a system or other
application that is for sale (for however much and for whatever reasons) or
released as copyright material then the author's express permission in
writing must be obtained. The author maintains copyright on all the material
supplied and reserves the right to change these conditions at any time
without notice.


CONTACTING THE AUTHOR

I would be interested in hearing of any bugs or other unexpected features in
this module, and will endeavour to correct any such problems in future
releases. Suggestions for improvements are also most welcome. Implementation
depends upon practicability and on how much spare time I have.

If you have any comments on this program, or would like to suggest ways in
which it could be improved, I can be contacted at the following address:

    Thalna
    2 Dukes Drive
    Bearwood
    Bournemouth
    Dorset
    BH11 9SZ
    
    alex@thouky.tcp.co.uk

If in any communication you make specific reference to the program code please:

    Quote the version number and date of the module.
    
    Refer only to the module as released.
    
    Supply as many details as possible about the problem, including the
    hardware and software configuration of the machine being used.

Please send a stamped and self addressed envelope, or give details of how to
contact via e-mail, if you would like a reply.

I hope you find this module of some use.


ACKNOWLEDGEMENTS

I would like to the thank the following people for their contributions to
the development of this module:

    Acorn Computers - The Risc PC, RISC OS and the ObjAsm assembler.
    Aidan Corey     - Thorough testing, and good ideas for improvements.
    Dominic Symes   - The brilliant !Zap editor; get a copy immediately.
    Colin Turnbull  - Reminding me that I should be revising.
    Robin Watts     - !Larger, the greatest backdrop program ever.
    Rob Westwood    - The original idea behind this program.

and everyone at the Acorn User Group in Oxford.


THINGS TO DO

The following are changes that may be made to this module sometime in the
future:

    Check for format buffer overflow - currently a 1024 byte fixed length
    buffer is used whilst processing the format strings, without any checks
    for overflow.
    
    Incorporate extra %xx tokens for special purposes.

    Improve the error handling. If any part of initialisation fails then the
    correct point in the finalisation code should be jumped to allowing any
    successful initialisation to be undone. Memory allocation and deallocation
    should also be more controlled.
    

VERSION HISTORY

0.00 (25-Apr-95)    Original development version.

0.01 (26-Apr-95)    Writes to Territory Manager workspace to install as
                    current territory without being the configured territory.

0.02 (26-Apr-95)    Format strings containing the day not replaced to correct
                    problem with both BASIC and the Sys$* code variables
                    expecting fixed width fields. Modified string padded or
                    truncated to original length.

0.03 (28-Apr-95)    Installation routine legalised by reinitialising Territory
                    Manager with OS_Byte vector intercepted to pretend that
                    this is the configured Territory. Added replacement format
                    for earlier the same year. Corrected stack handling over
                    nested SWI calls. Only performs susbtitution if text would
                    not require truncation.

0.04 (29-Apr-95)    Added second choice replacement formats to cope better
                    with small field widths. Substitutions padded individually
                    within each replaced section. Comparisons made case
                    insensitive, and wild-cards supported.

0.05 (01-May-95)    Messages file generated on-the-fly for Territory Manager
                    to give the new territory the same name as the configured
                    territory to avoid problems with applications using the
                    name of the territory to load resources. Installs and uses
                    messages file for configuration.

0.06 (02-May-95)    Preprocessing of configuration messages file to improve
                    conversion performance. Error checking during conversions
                    improved.

0.07 (04-May-95)    Added substitutions for previous years, tomorrow and the
                    future. Improved handling of errors during substitution.
                    Preprocessed substitution messages also for even faster
                    conversions.

0.08 (05-May-95)    Improved macros for subroutine handling, making the code
                    more likely to be correct and shortening the module by
                    32 bytes.

0.09 (07-May-95)    Intercepts Territory Manager SWIs by using the same SWI
                    chunk number and ensuring that this module is the most
                    recently initialised. This has the advantage that a new
                    territory is not required.

1.00 (09-May-95)    First official release version. Changed default
                    configuration to use fully wild-carded search strings
                    and using extra specific stop strings to obtain desired
                    behaviour.

1.01 (10-May-95)    Corrected bug which prevented alternative substitutions
                    from working.

1.02 (17-Aug-95)    Updated to work with OSLIb version 5, and some
                    development code removed.

1.03 (31-Jan-98)    Corrected handling of future dates within the same year.
                    Added a substitution for the last ten minutes.