summaryrefslogtreecommitdiff
path: root/macros/latex209/contrib/pphlp/pphlp.tex
blob: 3f99cb1c01f9bd4e57c61ab86cad1a8831ed8d10 (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
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
%%% ======================================================================
%%%  @TeX-file{
%%%     filename        = "pphlp.tex",
%%%     version         = "1.0",
%%%     date            = "19 July 1992",
%%%     time            = "14:12:45.12 ",
%%%     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        = "29376 315 1629 13208",
%%%     docstring       = "This is the core of the PPhlp package, and is
%%%                        driven by the com-file pphlp.com, which LaTeX's
%%%                        this file after customising it through the
%%%                        definitions in pphlpdefs.tex, which this file
%%%                        \input's.
%%%                        
%%%                        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."
%%% }
%%% ======================================================================
%   + This \LaTeX\ file will set VMS |.hlp| files.  \LaTeX\ commands are
%   `hidden' in the file by turning the VMS comment character `!' into an
%   escape character.  Since it's an escape, you can't use `!' as an
%   exclamation point---if you want that character in your help text, use `!!'
%   instead.
%
%   For convenience, the characters |$| and |@| have been made letters.  The
%   character |_| has been made active, producing a |\tt| underscore in text,
%   or a subscript in maths mode (which must be surrounded by |\(..\)| since
%   the dollar has been taken away), and advantage is taken of this catcode to
%   |\let| it equal to |\space| when it appears in helpsection headings.
%
%   The following control sequences and active characters are defined:
%   \begin{description}
%   \item[\verb-\helpsection-]
%	Put this command before each line which consists of a help level number
%	and heading, or before a qualifier line.
%   \item[\verb-\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.
%   \item[\verb-\settab-]
%	When making tables, it is sometimes useful to define a different
%	character, say `-', to be the alignment tab character.
%   \item[\verb-\activate-]
%	Make a character active, for example in the line
%	|!begin{itemize}\activate* \let*\item|, which would help make an
%	itemised list of starred items.
%   \item[\verb-\makeother-]
%	Give a character the catcode `other'.  Takes an optional argument with
%	an alternative catcode.
%   \item[\lq]
%	In-line strings which are to be set verbatim should be placed between
%	`\dots' (and you should avoid using left quotes in other contexts).
%   \item[*]
%	Words or phrases to be emphasised should go between |*...*|.
%   \item[{\tt !<{\it \LaTeX{} text}|{\it hlp text}>}]
%	Put only the first alternate text in the \LaTeX{} file.  If you use
%	this, you'll have to also use Krish's preprocessor ({\tt
%	run tools:helpproc}) to strip the first alternate from the .hlp file
%	before it can be put into a help library.
%   \item[\verb-\beginhlptext...\endhlptext-]
%	The text between these control sequences is not included in the \LaTeX
%	version of the documentation.
%   \item[\verb-{TeXtext}- environment]
%	Blocks of text which are to be omitted from the library should have
%	!~marks at the beginning of each line.  They should additionally be
%	surrounded by the \verb-{TeXtext}- environment, in which !~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.
%   \end{description}
%   \-
%   * \def\commratio{0.5}


\input pphlpdefs
\ifx\pphlpstyleoptions\undefined
    \documentstyle{phutguide}
\else
    % any extra styles should be added AFTER \pphlpstyleoptions
    \expandafter\expandafter\expandafter
	\documentstyle\expandafter[\pphlpstyleoptions]{phutguide}
\fi

%   \percentnextline
\def\dospecials{\do\\\do\{\do\}\do\&\do\#\do\^\do\%\do\~\do\!\do\*}

\catcode`!=0			    % ! in col. 1 is the .hlp comment character
\chardef!!="21			    % `!!' gives exclamation mark
\catcode`\@=11
\catcode`\$=11

\def\Uncatcode{\@noligs \let\do\@makeother \dospecials}

\def\activate#1{\catcode`#1=\active}	% make argument character active
\def\makeother{\@ifnextchar[{\@@makeother}{\@makeother}}
\def\@@makeother[#1]#2{\catcode`#2=#1}
\def\c@c#1{\message	% debugging - print catcode
    {catcode \string #1 is \ifcase\catcode`#1 escape\or begingroup\or
    endgroup\or math\or align\or endline\or parameter\or superscript\or
    subscript\or ignored\or space\or letter\or other\or active\or
    comment\or invalid\fi}}

% make underscore a subscript only in math mode
\def\underscore{\ifmmode _ \else {\tt\char "5F}\fi}
\activate\_ \let_\underscore

\def\paragraph{\@startsection	    % Not all styles have these defined, so\dots
 {paragraph}{4}{\z@}{3.25ex plus 1ex minus .2ex}{1ex plus .2ex }{\normalsize\bf}}
\def\subparagraph{\@startsection
 {subparagraph}{5}{\parindent}{3.25ex plus 1ex minus 
 .2ex}{1ex}{\(\Diamond\)\sl}}


% + The macro |\helpsection| begins a group, and calls |\gethelpsectionparams|
% to get the parameters from the next line.  The latter sets the counter
% |\helpsectiondepth| to be the first parameter, or increments and negates it,
% if the first parameter is the character /, denoting a qualifier line.  Then we
% call |\dohelpsection|, which uses a |\ifcase| statement to set the section
% heading.
%
% In the default case, level~1 headings are ignored, levels 2, 3 and~4 are set
% as |\section|, |\subsection| and |\subsubsection|, and level 5 is simply
% bulleted.  This is because there will be only a single level~1 heading in most
% files.  If this is not the case, then the command |\multilevelone| should be
% given, which sets level~1 headings as |\section|s.
% \-

\let\helpleveli\@gobble
\let\helplevelii\section
\let\helpleveliii\subsection
\let\helpleveliv\subsubsection
\let\helplevelv\subparagraph
\def\multilevelone{% Don't ignore level one headings
    \let\helpleveli\section
    \let\helplevelii\subsection
    \let\helpleveliii\subsubsection
    \let\helpleveliv\paragraph
    \let\helplevelv\subparagraph}

\newcount\helpsectiondepth
% We mustn't do the following within a group, or else things like
% |@currentlabel| don't make it out.
\def\helpsection{%
    \let_\space	    % so |_|'s in section headings turn to space
    \activate\^^M   % so we can read the arguments --- undo these at the end
    \gethelpsectionparams}

{\catcode`\^^M=\active%
\gdef\gethelpsectionparams^^M#1#2^^M{%
    \if/#1 %
	\ifnum\helpsectiondepth > 0 %
	    \global\helpsectiondepth=-\helpsectiondepth %
	    \global\advance\helpsectiondepth by -1 %
	\fi %
    \else %
	\global\helpsectiondepth=#1 %
    \fi %
    \dohelpsection{#2}}%
%
\gdef\dohelpsection#1{%
    \ifnum\helpsectiondepth < 0 %
	\@tempcnta=-\helpsectiondepth	\def\arg{\tt /#1}%
    \else   %
	\@tempcnta\helpsectiondepth	\def\arg{#1}%
    \fi	    %
    \ifcase\@tempcnta \or	%
	\helpleveli  {\arg}     %
	\xdef\toptopic{\arg}    %   Top-level help topic for use in |\advbox|
			    \or %
	\helplevelii {\arg} \or %
	\helpleveliii{\arg} \or %
	\helpleveliv {\arg} \or %
	\helplevelv  {\arg}	%
    \else			%
	\errhelp{See Norman if you need more}%
	\errmessage{There is currently a maximum of five levels of help}%
    \fi	%
    \let_\underscore
    \catcode`\^^M=5   % ... again
    % Undo the redefinition of |_| here, rather than at the end of
    % |\gethelpsectionparams| so that the active underscore means
    % |\space| in the argument to the |\helplevel| commands
    }}

% + We want to be able to select alternate texts depending on whether
% we're producing a \LaTeX\ file or a help library.
%
% For occasional words, use the construction \verb-!<LaTeX text|hlp text>-,
% in which case the text should be run through Krish's preprocessor before
% being put into the help library.  For this latter reason, it should always be
% |!<| rather than |\<|, although they are equivalent to \LaTeX.
%
% To miss out larger chunks of help library text is easy---we just
% surround the text with |\iffalse...\fi|, suitably disguised.  It's
% unfortunate that this doesn't look exactly like a \LaTeX\
% environment, but life's like that\dots.
%
% Putting text in the \LaTeX\ document, whilst keeping it from the
% library seems easy---you just prefix the lines with exclamation
% marks---but there's a subtlety in that we must then have at least
% one blank space after the `!', which is then interpreted as a
% control space, and lines blank apart from the `!' are not
% interpreted as new paragraphs.  Solve both these latter problems by
% making `! ignored within the |{TeXtext}| environment.  Note that
% this means that the environment {\em must\/} be ended with
% |\end{TeXtext}|, rather than |!end|.
% \-

\let\beginhlptext\iffalse
\let\endhlptext\fi

\def\TeXtext{\catcode`\!=9}
\let\endTeXtext\relax

\def\<#1|#2>{#1}

% + A couple of macros for verbatim text.  In-line strings should go between
% |`...'|, and complete lines of verbatim material should be preceded by a
% |\verbatimline| command.  The |!begin{verbatim}| environment may be used, but
% it must be ended by the string |!end{verbatim}|.  This means that the `
% character should be made active---do this inside a group so we can make other
% catcode changes later in this file.
% 
% Finally, make `!' an escape character, rather than ignored, in the \TeX text
% environment, so that `!!' will give an exclamation mark there.
% \-
\activate' \let'\rq
{\obeyspaces\global\let =\ }	% make active space equal to |\ |
%\def\hyspace{\discretionary{\char32\relax}{\char32\relax}{\char32\relax}} % make spaces hyphen-like
%{\activate` \gdef`{\begingroup \catcode"20=12 \Uncatcode \let'\endgroup \tt}}
{\activate`
\obeyspaces\activate\.\activate\_%
% allow spaces, dots and underscores to break verbatim text
\gdef`{\begingroup\Uncatcode\let'\endgroup%
\activate\_\def_{\discretionary{\char"5F\relax}{}{\char"5F\relax}}%
\activate\.\def.{\discretionary{\char"2E\relax}{}{\char"2E\relax}}%
\obeyspaces\def {\discretionary{\char32\relax}{\char32\relax}{\char32\relax}}%
\tt}}

\newcount\@verbatimlinecount
{\activate\^^M
\gdef\verbatimline{\ifvmode \noindent \else \par \fi % If previous line is
		% blank, |\noindent| means we enter horizontal mode with
		% previous parskip.  Otherwise, |\par| forces us into
		% vertical mode, and we enter horizontal mode later, with
		% parskip zero.
    \begingroup \parskip=0pt \activate\^^M%
    \@ifnextchar[{\@verbatimline}{\@verbatimline[1]}}%
\gdef\@verbatimline[#1]^^M{\@verbatimlinecount=#1 \obeyspaces\Uncatcode %
    \def\@tempa{TeXtext}\ifx\@tempa\@currenvir\catcode"21=0\fi % re-escape ! in \TeX{}text
    \tt\do@verbatimline}%
\gdef\do@verbatimline#1^^M{#1\par\noindent  % following text on new line
					    % (new paragraph with parskip zero)
    \advance\@verbatimlinecount by -1 %
    \ifnum\@verbatimlinecount=0 %
	\def\next{\endgroup}% 
    \else %
	\def\next{\do@verbatimline}%
    \fi\next}}

\begingroup \catcode `|=0 \catcode `[= 1  % This is nicked from
		% |latex.tex|---make |\begin{verbatim}| end with
		% |!end{verbatim}|
\catcode`]=2 \catcode `\{=12 \catcode `\}=12
\catcode`\!=12 |gdef|@xverbatim#1!end{verbatim}[#1|end[verbatim]]
|gdef|@sxverbatim#1!end{verbatim*}[#1|end[verbatim*]]
|endgroup

% likewise---make verbatim environment within \TeX text have ! as escape
\def\verbatim{\@verbatim \frenchspacing\@vobeyspaces
    \ifx\@tempa\@currenvir \catcode"21=0\fi \@xverbatim}
\@namedef{verbatim*}{\@verbatim \ifx\@tempa\@currenvir \catcode"21=0\fi
    \@sxverbatim}

% bits and bobs

\def\settab#1{\catcode`#1=4}	    % set the tab character for setting tables

\chardef\star`*			    % |*...*| emphasises things
\activate* \def\emphasise#1*{{\em #1\/}}
\def*{\ifmmode\star\else\emphasise\fi}

\escapechar=`\!			    % so we're free to recatcode backslash

\activate`			    % make it active again

\parskip=\medskipamount
\parindent=0pt

\let\helpproc\@gobble		    % instruction to Krish's preprocessor

\@ifundefined{pphlppreamble}{}{\pphlppreamble}

%%%%%%%%%%%%%%%% Now read in the file %%%%%%%%%%%%%%%%%%%
!begin{document}

!input{!pphlpname}
!advbox
!end{document}