PPhlp
-----
This is a system for producing both VMS help libraries and printed documentation
from a single file, which has LaTeX commands embedded within it.  Although it is
therefore fairly specific to VMS, the format of help library modules is simple,
and the system could probably be translated fairly easily to take advantage of
another format with a similar heirarchical structure.

The system is not dissimilar to the GNU texinfo format.


Brief Description
-----------------
Help library modules contain plain text, which is given a structure by lines
which consist of a level number in column 1, followed by a heading.  After
they've been inserted into a help library, and help is requested on a particular
topic, the help system will display all the level 1 text for that topic,
followed by all the level 2 headings.  After you select a level 2 heading, you
will see all the level 2 text, and the level 3 headings, and so on.  This is
analogous to the successive levels of section, subsection, paragraph,... of a
paper document.

The help system will not display any lines which have an exclamation mark `!' in
column 1, and we can take advantage of this to embed LaTeX commands in the text.

For example, here is the start of the help file for PPhlp (all the lines should
be taken to start in column 1):

	!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
	...
	!helpsection
	2 HLP_file_format
	This is documented fully in the librarian manual, but
	...

You can see most of the extensions to and changes from LaTeX in this section.
The escape character in PPhlp files is `!', rather than `\'.  `!maketitle' uses
the fields filled in before it to produce a title page.  `!helpsection', which
is followed on the next line by a number and a text string, produces a section,
subsection, paragraph (and so on) heading, depending on the value of the number:
the title is composed of the rest of the line, with any underscores changed to
spaces.  Any text between quotes is set verbatim.

As it stands, this file would be perfectly acceptable to the help librarian, and
could be inserted into a help library with the command

	$ libr/help <library-name> <module-name>

In certain circumstances, the PPhlp file needs some preprocessing, and the
package includes a program designed to do this.

For more information, read the help file.


Files
-----
The package consists of the following files:

	PPHLP.README		This file.
	PPHLP.TEX		The file which is actually LaTeXed, by ...
	PPHLP.COM		DCL com-file, which acts as a `front-end' to the
				package.
	PPHLP.HELP		A help file.  It can either be turned into an
				.hlp file by processing it with helpproc
				(below), or into a .dvi file by invoking the
				com-file.
	HELPPROC.PAS		A preprocessor, which strips out some
				constructions.
	PPROC.CLD		A .cld file for the preprocessor.
	HLP.LSE			An LSE file which defines the language `hlp',
                                and adds adjustments designed for the `folding
                                editor' capacities of LSE, by allowing elision
                                of the help text as you write it.
	PHUTGUIDE.STY		The documentstyle in which the help documents
	PHUTGUIDE11.STY		are set.

[HELPPROC.PAS was written by Krish Singh, and PHUTGUIDE.STY is a modification of
a manuals style written by the Open University's computer service]


Setting it up
-------------
To use the system, edit the line

	$   source_dir := phut:[util.local.pphlp]

in pphlp.com, so that it refers to wherever you've put the files.  Then define a
command

	$ pphlp :== @ <wherever-the-source-files-are>pphlp

and put the two style files wherever it is that TeX expects to find them.  To
make the preprocessor, compile and link helpproc.pas, edit the `image' line in
pproc.cld to point to the newly linked image, and add the command `pproc' to
your command tables with

	$ set command pproc

To use hlp.lse, enter LSE, read this file into a buffer, and give the command
`do'.  You can make the resulting definitions permanent by giving the command
`save environment' within LSE.

Format the help file by giving the command

	$ pphlp pphlp.help	! .help is the default file type

This will produce a .dvi file which can be printed normally.  Alternatively, you
can give the command

	$ pproc pphlp.help	! .help is the default, again

which will produce an .hlp file which can be inserted into a help library.

I hope it's useful - have fun.

Norman

===============================================================================
Norman Gray                     N.O.Gray@open.ac.uk (Internet)
Department of Physics
Open University
Milton Keynes,  MK7 6AA         +44 908 652279
UK                              +44 908 653744 (fax)
===============================================================================