Dream 44/Amiga_Dream_44.iso/RiscPc/Utils/ShortHelp.arc/ShortHDocs

Text File | 1994-09-19 | 9KB | 214 lines

Small Help version 1.00
⌐ Sam Kington 8th August 1994
This program is freeware, *not* public domain ù i.e., I retain copyright (see
öBoring legal messageò)

What this program does
**********************

   This program, or rather this set of library routines, allows you to
compact the help messages contained in modules by using RISC OSæs internal
dictionary: the routine FNprint goes through a string, replacing certain
keywords with (much shorter) control codes, which will then be expanded by
*Help, or more exactly expanded by OS_PrettyPrint called by *Help. The
advantage of having these library routines is that a) you donæt have to
re-invent the wheel and b) itæs more readable than hard-wiring the codes into
the source code.

   The routines, being written in BASIC, are only usable from within the
BASIC assembler.

   To use the routines, add the following lines somewhere near the beginning
of the moduleæs source code (in the BASIC part, not the assembler part):
      LIBRARY "%.ShortHelp"
      PROCprettyprintinit
   The exact ₧lename you use may be different; however, if you are going to
use the routines regularly, you might as well put them in your Library, in
which case you would use the ₧lename "%.ShortHelp". If you donæt know what a
Library is, or whether you have one, you probably donæt have one, so it isnæt
worth setting one up just for ShortHelp. (See your User Guide for more
information about Libraries).
   Afterwards, in the help part of the module source code, which will
probably look something like this:-

.help_Command
   EQUS  "Command does whatever this command is supposed to do."
   EQUB  0

- replace it by the following:

.help_Command
   EQUS  FNprint("Command does whatever this command is supposed to do.","Command")
   EQUB  0

   In other words, replace the string by FNprint(<string>, <name of command).

OK, but how does this actually work?
************************************

   When *Help is called, it looks for the appropriate help string in the
module code, and then sends it to a SWI called OS_PrettyPrint, which formats
it correctly, breaking lines at spaces and correctly printing tabs.
OS_PrettyPrint also uses an internal dictionary of regularly occurring text,
and looks through the text for certain combinations of characters that mean
öinsert dictionary entry hereò. If you have the PRMs, look at the entry for
OS_PrettyPrint for a complete list of the dictionary entries (In the RISC OS
3 PRMs it's at pages 1-518 to 1-520; in the RISC OS 2 PRMs it's at pages 185
to 187). If you donæt, a complete list follows at the end of this section.

   FNprint does the reverse: it scans the string for dictionary entries,
replaces them by the control sequences (which are naturally much shorter,
being only two characters rather than potentially dozens), which will then be
expanded by *Help.

   For those who don't have the PRMs, here follows a short resume of what
certain special characters mean:

   CR (ASCII 13) causes a newline to be generated.
   TAB (ASCII 9) causes a tabulation to the next multiple of eight columns
   SPACE (ASCII 31) is a hard space (i.e. the line won't break here).
   ESC (ASCII 27) indicates a dictionary entry should be substituted.

   The default list of dictionary entries follows:

      0: special string
      1: "Syntax: *"special string
      2: " the "
      3: "director"
      4: "filing system"
      5: "current"
      6: " to a variable. Other types of value can be assigned with *"
      7: "file"
      8: "default"
      9: "tion"
      10: "*Configure"
      11: "name"
      12: " server"
      13: "number"
      14: "Syntax: *"special string" <"
      15: " one or more files that match the given wildcard"
      16: " and "
      17: "relocatable module"
      18: CR"*C(onfirm)"Tab"*Prompt for confirmation of each "
      19: "sets the "
      20: "Syntax: *"special string" [<disc spec.>]"
      21: "}"CR"*V(erbose)"Tab"*Printinformation on each file "
      23: "spriteLandscape [<XScale>[<YScale> [<Margin> [<Threshold>]]]]]"
      24: " is used to print a hard copy of the screen on EPSON-"
      25: "."CR"*Options: (use ~ to force off, eg. ~"
      26: "printe"
      27: "Syntax: *"special string"<filename>"
      28: "select"
      29: "xpression"
      30: "Syntax: *"special string" ["
      31: "sprite"
      32: " displays"
      33: "free space"
      34: " {off}"
      35: "library"
      36: "parameter"
      37: "object"
      38: " all "
      39: "disc"
      40: " to "
      41: " is "

   Note that there is no entry 22, and also that some entries require the
previous CR to be included in the string. The special string is a string
supplied along with the string to be expanded; in the case of *Help, the
special string is the name of the command, so any time the sequence
CHR$27+CHR$0 was found in any text produced by the command *Help Command,
CHR$27+CHR$0 would be replaced by öCommandò. That is why you have to supply
the name of the command to FNprint, so it can look for it and replace it
accordingly.

Boring legal message
********************

   This application is freeware, that is, it can be distributed freely as
long as only reasonable charges are made for media and distribution. I retain
copyright on all program code and documentation.

   This software is supplied öasáisò: I make no warranty, expressed or
implied, of the merchantability of this software or its ₧tness for any
particular purpose. In no circumstances shall I be liable for any damage,
loss of pro₧ts, or any indirect or consequential loss arising out of the use
of this software or inability to use this software, even if I have been
advised of the possibility of such loss.

   In other words, if your computer crashes, blows up, you lose all your work
etc. all because of SmallHelp (unlikely I know), donæt blame me.

Distribution
************

   You should have two ₧les, ShortHelp and ShortHDocs. There may be other
₧les in the directory if ShortHelp has been supplied with another program,
but ShortHelp doesnæt need them.

   If you are a PD library, an ftp site or whatever, simply distributing
these routines as part of a single package, you should supply both of the
₧les intact, complete and without modi₧cation.

   You are allowed, and indeed encouraged, to use these routines in your own
programs. You may make whatever modi₧cations you wish to the routinesæ code,
provided you document the changes appropriately in this ₧le and in the
source code. If you use the routines, it would be nice if you could tell me
(see below for contact details); if you use them and distribute the end
result, I would appreciate it if you could send me a copy (or tell me where I
can get one). I will of course expect you to at least make a passing mention
of the routines you used in the documentation.

   In other words, if you change anything, document the changes in the
documentation and the source code; if you use it in your code, give me a
credit and tell me (if possible) youæve done it.

About all these strange foreign characters in this ₧le
*******************************************************

   OK, so if youære reading this on a PC or a Mac or another strange machine
like that, you may be wondering what all these strange ae things are. Well,
theyære quotes (sorry, there was another one), dashes, ligatures, etc.
Honest. But not on all machines...
   Basically, character sets are only standard up to character 127, which is
basically alphanumerics and a few standard punctuation marks. Foreign
characters, typographical oddities like quotes and ligatures, and other more
obscure symbols are önon-standardò, and each computer often has its own idea
of where they should go in the character set. So donæt worry: even if itæs
hard to read on your current machine, it wonæt be on an Acorn machine. It may
look slightly strange if youære using the System font, however.
   But why am I using these strange characters in the ₧rst place? Well,
theyære in the character set and they look nice in an outine font, and Iæve
written a program called Smart Quotes (sorry for the plug) that substitutes
these sort of characters automatically, and Iæve got it turned on at the
moment...

How to contact me
*****************

All bug-reports, suggestions, comments or indeed any feedback at all will be
welcomed. Hereæs how to get to me:

E-mail     : [e-mail], [e-mail] during term-time
             These should be OK until June 1996
             At Christmas, Easter and during the summer, you can get me at
             [e-mail], [e-mail] or [e-mail], in order
             of preference (that is, if mail bounces off one of these or I donæt
             answer within a week send to the next one).

Snail-mail : My term-time address, at least until June 1995, is:
             Sam Kington
             Flat 2/1
             44 Hotspur Street
             Glasgow G20 8NL
             SCOTLAND

             Again, a backup is the home address ù anything that goes here will get
             to me eventually.
             Sam Kington
             Merlhiot
             24420 Savignac les Eglises
             FRANCE

Term-time is October to June, with bits off at Christmas (3 weeks) and
Easter (4 weeks).