%%% ======================================================================
%%%  @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}