!iffalse !!! ====================================================================== !!! @Digital-HELP-Text{ !!! filename = "pphlp.help", !!! version = "1.0", !!! date = "19 July 1992", !!! time = "14:08:28.91 ", !!! author = "Norman Gray", !!! address = "Department of Physics !!! Open University !!! Milton Keynes !!! MK7 6AA, UK", !!! e-mail = "N.O.Gray@open.ac.uk (Internet)", !!! telephone = "+44 908 652279", !!! FAX = "+44 908 653744", !!! archived = "Aston, SHSU", !!! keywords = "hlp-files, VMS, help", !!! abstract = "This file is part of the PPHLP package, which !!! allows both printed manuals and VMS help library !!! modules to be prepared from a single file.", !!! codetable = "ISO/Ascii", !!! checksum = "04228 265 1410 10242", !!! docstring = "This is the main documentation for the PPhlp !!! package. It may be turned into a file suitable !!! for the help librarian by processing through !!! helpproc.pas, or into a printable .dvi file by !!! processing through pphlp.com. !!! !!! The checksum field above contains a CRC-16 !!! checksum as the first value, followed by the !!! equivalent of the standard UNIX wc (word !!! count) utility output of lines, words, and !!! characters. This is produced by Robert !!! Solovay's checksum utility." !!! } !!! ====================================================================== !fi !title{PPHLP: A documentation tool} !pagetitle{Pphlp} !author{Norman Gray} !authorext{2279} !userguide{Util5} !maketitle !begin{TeXtext} ! \begin{abstract} ! PPhlp is a tool for producing both ! printed documentation using \LaTeX, and a help library usable ! through the VMS `help' command, from a single file. ! \end{abstract} !\end{TeXtext} !helpsection 1 PPhlp This utility takes an appropriately formatted `.hlp' file and !<\LaTeX|LaTeX>'s it, to produce formatted documentation. It takes advantage of the fact that the librarian, which turns `.hlp' files into help libraries, ignores any line which has an exclamation mark in the first column. When you are writing documentation for this utility, you can regard the exclamation mark as an escape character, just like the backslash character. When you are writing documentation, you should remember that you are working under two sets of constraints: everything that appears in a line which does not start with an exclamation will appear as-is in the help library; at the same time, everything should be valid !<\LaTeX{}|LaTeX>. Most of the features in this utility are designed to reconcile these conflicting demands. !helpsection 2 HLP_file_format This is documented fully in the librarian manual, but the essential format is: !begin{enumerate}!let*\item * Any line with an exclamation mark in column 1 is ignored; * Any line with a digit in column 1 is taken to be a help library level, and is followed by a key. * The key should be composed of letters, digits, the dollar sign, underscore and hyphen. * Because the material between the keys is indented on-screen, you should limit the lines in the help file to about 60--70 characters. !end{enumerate} !helpsection 2 PPhlp_control_sequences The following control sequences are usable in pphlp file. !begin{description} !activate+ !def+ {!par!begingroup!makeother!!!vitem} !def!vitem#1 {!endgroup!item[!tt #1]} + !helpsection Put this command before each line which consists of a help level number and heading, or before a qualifier line. + !verbatimline Put this command before a line which is to be set verbatim. It takes an optional argument, which is the number of verbatim lines to be set. + !settab When making tables, it is sometimes useful to define a different character, say `-', to be the alignment tab character. For example !verbatimline[5] !begin{center}!settab: !begin{tabular}{ll} first column : second column !\ ... !end{tabular}!end{center} + !activate Make a character active, for example in the line !verbatimline[3] !begin{itemize}!activate* !let*!item * Here is the first item in the list ... which would help make an itemised list of starred items. + !makeother Give a character the catcode `other'. Takes an optional argument with an alternative catcode. + !beginhlptext...!endhlptext The text between these control sequences is not included in the ! version of the documentation. !beginhlptext + ! !endhlptext !item[!tt!!] Put only the first alternate text in the ! file. If you use this, you'll have to also use Krish's preprocessor (`pproc') to strip the first alternate from the `.hlp' file before it can be put into a help library. Do not split this construction over two or more lines. !end{description} A new environment has been defined, and the verbatim environment slightly changed. !begin{description}!activate+ !def+ #1:{!item[!tt!{#1!}]} + TeXtext: Blocks of text which are to be omitted from the library should have exclamation marks at the beginning of each line. Longer sections should additionally be surrounded by the TeXtext environment, in which exclamation marks are ignored, to avoid spacing problems. Note that the environment should be ended by `\end{TeXtext}', rather than `!end{TeXtext}'. The control sequence `\!' will produce an exclamation mark in this environment. + verbatim: The verbatim environment has been changed, so that it must be ended by the string `!end{verbatim}', rather than `\end{verbatim}'. !end{description} The following characters are also made active: !begin{description}!activate+ !def+ #1{!item[!tt #1]} !makeother!` !makeother!* + ` In-line strings which are to be set verbatim should be placed between `...' (and you should avoid using left quotes in other contexts). + * Words or phrases to be emphasised should go between *...*. !end{description} Other changes from standard ! are: !begin{description}!activate+ !def+ #1:{!item[#1]} + `$' and `@' characters: These have been given catcode *other*, that is, they can be used in text as normal characters. This means that maths mode must be begun and ended with `!(...!)' + The underscore: This has been made active, and will produce an ordinary underscore in text, and a subscript in maths mode. !end{description} Finally, remember that !'s `!endinput' command may be used in a help file to indicate that no more of the file should be read. All the text after this point will be seen only by the help librarian. !helpsection 2 Preprocessor In most cases, enough formatting material may be included within an `.hlp' file that it can be used either for input to `pphlp' or given to the help librarian. Sometimes, however, the formatting within the file is involved enough that some preprocessing is required. Specifically, this will be necessary if you use the `!<...|...>' construction. A program exists to do this preprocessing, called `pproc', which is set up by the command !verbatimline $ set command biocom:helpproc The format of the command is !verbatimline $ pproc It is a useful convention to reserve the `.hlp' suffix for file which are directly suitable for the help librarian, and to give the `.help' suffix to files which must be run through the preprocessor. The processor recognises the following constructs. !begin{description}!activate+ !def+{!begingroup!makeother!! !vitem} !def!vitem #1 :{!endgroup!item[!tt #1]} !makeother!` + !<...|...> : The preprocessor leaves only the second alternative in the file. + `...' : Text within quotes is surrounded by escape sequences which will embolden it within the help file. !end{description} !helpsection 2 Calling_pphlp The `pphlp' processor is set up by defining the symbol !verbatimline $ pphlp :== @ phut:[util.local.pphlp]pphlp and has the format !verbatimline[2] $ pphlp [-stylefile ...] [+\preamblecommands ...] - [/extraqualifiers] hlp-file where you may give a list of additional style files prefixed by hyphens, and a list of ! commands (with backslash as the escape character) prefixed with a plus sign, which are to be inserted in the preamble. If the extension is missing from the `hlp-file', then the procedure first searches for a file with the extension `.help', then for one with the extension `.hlp'. For example, given the file `doc.help' and style files `acs_specials.sty' and `doc-sty.sty', the following command will format the help file in batch mode (note that the qualifier must be separated from the filename). !verbatimline $ pphlp -acs_specials -doc-sty +\makeindex doc /batch !helpsection 2 Other_LaTeX_facilities Other ! facilities such as cross referencing, compiling tables of contents, and floating figures and tables are perfectly usable within this system. The indexing program *MakeIndex* can be used with `pphlp', with a minor alteration. That program uses the exclamation mark as a sub-entry delimiter, but this causes problems with `pphlp' as that character is the escape. Accordingly, if you want to use *MakeIndex*, then you should use it with a style file which alters its behaviour so that the `>' character (say) is the sub-entry delimiter. That is, you should create a file (`pphlp.isty', say) with the contents !verbatimline[2] level '>' keyword "!indexentry" invoke `pphlp' with the command !verbatimline $ pphlp +\makeindex doc-file and invoke *MakeIndex* with the command !verbatimline $ makeindex -s pphlp.isty pphlp.idx (note that the index file is called `pphlp.idx', rather than `doc-file.idx').