home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The Datafile PD-CD 3
/
PDCD_3.iso
/
utilities
/
utilss
/
sensible
/
Docs
/
Sensible
Wrap
Text File
|
1995-05-09
|
12KB
|
283 lines
File : Sensible
Date : 10-May-95
Author : © A.Thoukydides, 1995
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>
YSTR1:Yesterday<0>
WEEK1:%we<0>
TODY2/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
"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 one of the following
addresses:
Until June 1995:
19 Museum Road
Oxford
OX1 3PX
alexander.thoukydides@lincoln.oxford.ac.uk
After June 1995:
Thalna
2 Dukes Drive
Bearwood
Bournemouth
Dorset
BH11 9SZ
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