home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / utilities / utilss / shorthelp / ShortHDocs next >
Text File  |  1995-02-02  |  10KB  |  233 lines
  1. Small Help version 1.00
  2. © Sam Kington 8th August 1994
  3. This program is freeware, *not* public domain – i.e., I retain copyright (see
  4. “Boring legal message”)
  5.  
  6. What this program does
  7. **********************
  8.  
  9.    This program, or rather this set of library routines, allows you to
  10. compact the help messages contained in modules by using RISC OS’s internal
  11. dictionary: the routine FNprint goes through a string, replacing certain
  12. keywords with (much shorter) control codes, which will then be expanded by
  13. *Help, or more exactly expanded by OS_PrettyPrint called by *Help. The
  14. advantage of having these library routines is that a) you don’t have to
  15. re-invent the wheel and b) it’s more readable than hard-wiring the codes into
  16. the source code.
  17.  
  18.    The routines, being written in BASIC, are only usable from within the
  19. BASIC assembler.
  20.  
  21.    To use the routines, add the following lines somewhere near the beginning
  22. of the module’s source code (in the BASIC part, not the assembler part):
  23.       LIBRARY "%.ShortHelp"
  24.       PROCprettyprintinit
  25.    The exact filename you use may be different; however, if you are going to
  26. use the routines regularly, you might as well put them in your Library, in
  27. which case you would use the filename "%.ShortHelp". If you don’t know what a
  28. Library is, or whether you have one, you probably don’t have one, so it isn’t
  29. worth setting one up just for ShortHelp. (See your User Guide for more
  30. information about Libraries).
  31.    Afterwards, in the help part of the module source code, which will
  32. probably look something like this:-
  33.  
  34. .help_Command
  35.    EQUS  "Command does whatever this command is supposed to do."
  36.    EQUB  0
  37.  
  38. - replace it by the following:
  39.  
  40. .help_Command
  41.    EQUS  FNprint("Command does whatever this command is supposed to do.","Command")
  42.    EQUB  0
  43.    
  44.    In other words, replace the string by FNprint(<string>, <name of command).
  45.    
  46. OK, but how does this actually work?
  47. ************************************
  48.  
  49.    When *Help is called, it looks for the appropriate help string in the
  50. module code, and then sends it to a SWI called OS_PrettyPrint, which formats
  51. it correctly, breaking lines at spaces and correctly printing tabs.
  52. OS_PrettyPrint also uses an internal dictionary of regularly occurring text,
  53. and looks through the text for certain combinations of characters that mean
  54. “insert dictionary entry here”. If you have the PRMs, look at the entry for
  55. OS_PrettyPrint for a complete list of the dictionary entries (In the RISC OS
  56. 3 PRMs it's at pages 1-518 to 1-520; in the RISC OS 2 PRMs it's at pages 185
  57. to 187). If you don’t, a complete list follows at the end of this section.
  58.  
  59.    FNprint does the reverse: it scans the string for dictionary entries,
  60. replaces them by the control sequences (which are naturally much shorter,
  61. being only two characters rather than potentially dozens), which will then be
  62. expanded by *Help.
  63.  
  64.    For those who don't have the PRMs, here follows a short resume of what
  65. certain special characters mean:
  66.  
  67.    CR (ASCII 13) causes a newline to be generated.
  68.    TAB (ASCII 9) causes a tabulation to the next multiple of eight columns
  69.    SPACE (ASCII 31) is a hard space (i.e. the line won't break here).
  70.    ESC (ASCII 27) indicates a dictionary entry should be substituted.
  71.    
  72.    The default list of dictionary entries follows:
  73.    
  74.       0: special string
  75.       1: "Syntax: *"special string
  76.       2: " the "
  77.       3: "director"
  78.       4: "filing system"
  79.       5: "current"
  80.       6: " to a variable. Other types of value can be assigned with *"
  81.       7: "file"
  82.       8: "default"
  83.       9: "tion"
  84.       10: "*Configure"
  85.       11: "name"
  86.       12: " server"
  87.       13: "number"
  88.       14: "Syntax: *"special string" <"
  89.       15: " one or more files that match the given wildcard"
  90.       16: " and "
  91.       17: "relocatable module"
  92.       18: CR"*C(onfirm)"Tab"*Prompt for confirmation of each "
  93.       19: "sets the "
  94.       20: "Syntax: *"special string" [<disc spec.>]"
  95.       21: "}"CR"*V(erbose)"Tab"*Printinformation on each file "
  96.       23: "spriteLandscape [<XScale>[<YScale> [<Margin> [<Threshold>]]]]]"
  97.       24: " is used to print a hard copy of the screen on EPSON-"
  98.       25: "."CR"*Options: (use ~ to force off, eg. ~"
  99.       26: "printe"
  100.       27: "Syntax: *"special string"<filename>"
  101.       28: "select"
  102.       29: "xpression"
  103.       30: "Syntax: *"special string" ["
  104.       31: "sprite"
  105.       32: " displays"
  106.       33: "free space"
  107.       34: " {off}"
  108.       35: "library"
  109.       36: "parameter"
  110.       37: "object"
  111.       38: " all "
  112.       39: "disc"
  113.       40: " to "
  114.       41: " is "
  115.    
  116.    Note that there is no entry 22, and also that some entries require the
  117. previous CR to be included in the string. The special string is a string
  118. supplied along with the string to be expanded; in the case of *Help, the
  119. special string is the name of the command, so any time the sequence
  120. CHR$27+CHR$0 was found in any text produced by the command *Help Command,
  121. CHR$27+CHR$0 would be replaced by “Command”. That is why you have to supply
  122. the name of the command to FNprint, so it can look for it and replace it
  123. accordingly.
  124.  
  125. Boring legal message
  126. ********************
  127.  
  128.    This application is freeware, that is, it can be distributed freely as
  129. long as only reasonable charges are made for media and distribution. I retain
  130. copyright on all program code and documentation.
  131.  
  132.    This software is supplied “as is”: I make no warranty, expressed or
  133. implied, of the merchantability of this software or its fitness for any
  134. particular purpose. In no circumstances shall I be liable for any damage,
  135. loss of profits, or any indirect or consequential loss arising out of the use
  136. of this software or inability to use this software, even if I have been
  137. advised of the possibility of such loss.
  138.  
  139.    In other words, if your computer crashes, blows up, you lose all your work
  140. etc. all because of SmallHelp (unlikely I know), don’t blame me.
  141.  
  142. Distribution
  143. ************
  144.  
  145.    You should have two files, ShortHelp and ShortHDocs. There may be other
  146. files in the directory if ShortHelp has been supplied with another program,
  147. but ShortHelp doesn’t need them.
  148.  
  149.    If you are a PD library, an ftp site or whatever, simply distributing
  150. these routines as part of a single package, you should supply both of the
  151. files intact, complete and without modification.
  152.  
  153.    You are allowed, and indeed encouraged, to use these routines in your own
  154. programs. You may make whatever modifications you wish to the routines’ code,
  155. provided you document the changes appropriately in this file and in the
  156. source code. If you use the routines, it would be nice if you could tell me
  157. (see below for contact details); if you use them and distribute the end
  158. result, I would appreciate it if you could send me a copy (or tell me where I
  159. can get one). I will of course expect you to at least make a passing mention
  160. of the routines you used in the documentation.
  161.  
  162.    In other words, if you change anything, document the changes in the
  163. documentation and the source code; if you use it in your code, give me a
  164. credit and tell me (if possible) you’ve done it.
  165.  
  166. About all these strange foreign characters in this file
  167. *******************************************************
  168.  
  169.    OK, so if you’re reading this on a PC or a Mac or another strange machine
  170. like that, you may be wondering what all these strange ae things are. Well,
  171. they’re quotes (sorry, there was another one), dashes, ligatures, etc.
  172. Honest. But not on all machines...
  173.    Basically, character sets are only standard up to character 127, which is
  174. basically alphanumerics and a few standard punctuation marks. Foreign
  175. characters, typographical oddities like quotes and ligatures, and other more
  176. obscure symbols are “non-standard”, and each computer often has its own idea
  177. of where they should go in the character set. So don’t worry: even if it’s
  178. hard to read on your current machine, it won’t be on an Acorn machine. It may
  179. look slightly strange if you’re using the System font, however.
  180.    But why am I using these strange characters in the first place? Well,
  181. they’re in the character set and they look nice in an outine font, and I’ve
  182. written a program called Smart Quotes (sorry for the plug) that substitutes
  183. these sort of characters automatical