summaryrefslogtreecommitdiff
path: root/macros/latex209/contrib/pphlp/pphlp.help
blob: 065d891d69251836ba580960b8b8795bc6c800d2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
!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 !<!LaTeX|LaTeX> version of the documentation.
!beginhlptext
+ ! <LaTeX-text|hlp-text>
!endhlptext
!item[!tt!!<!LaTeX-text|hlp-text>]
	Put only the first alternate text in the !<!LaTeX|LaTeX> 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 !<!LaTeX|LaTeX> 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 !<!TeX|TeX>'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 <input-file> <output-file>

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 !<!LaTeX|LaTeX> 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 !<!LaTeX|LaTex> 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').