Allan Adler writes in his e-mail message of 1994/06/24

I have received and also written some GAP programs that I plan to use
extensively. It would be convenient to be able to add some online
documentaiton for them, such as already exists for the rest of GAP, for
my private use.

Please tell me in words of one syllable how to do this.

First make a '<chapter>.tex' file for each chapter that you want
to add and add a corresponding line

\Include{<chapter>}

to 'manual.tex'. Note the capitalization. Also note that the name of
the file must not contain more than 8 characters (excluding the '.tex'
suffix) and must not contain any special characters.

The file <chapter.tex> must begin with the line

\Chapter{<name>}

(after optional comments). Again note the capitalization. The name of
the chapter must be different from the names of the other chapters and
their sections.

Each section must begin with a line

\Section{<name>}

(again after optional comments). The name of the section must be
different from the names of the other sections.

In the description use quotes for typewriter style text
(e.g. 'MySpecialFunction'). Use angle brackets for italics
(e.g. <first-argument-for-my-special-function>). Use double quotes for
references to other sections (e.g. see also "The New Chapter"). Use
asterisks for bold text (e.g. do *not* call this function with an
*infinite* group). Use pipes for examples, for example

|    gap> MySpecialFunction( 10 );
    10 |

Run LaTeX on 'manual' often enough to create all crossreferences.
Usually you must run LaTeX three times

latex manual
bibtex manual
latex manual
makeindex manual
latex manual

That should do the trick.

Allan Adler continues

I am pretty sure that the answer involves hacking the TeX files for the
manual, but simply adding new sections or new entries to the table of
contents doesn't seem to be enough. There may also be something involving
the magic word "hashing", but I don't know how to work with that.

As pointed out above it is important to capitalize the '\Chapter' and
'\Section' LateX commands, because this is what the help function is
looking for. Apart from that no special hacking is needed.

Using <italics> instead of {\it italics} is simply used to make the
result look nice on the screen.

The hashing was used in an older version. We have lots of
crossreferences, and they exhausted the small TeX that we were using at
that time. By hashing the labels we used less of TeX's memory. But of
course ultimately there was no way we could get the GAP manual through a
small TeX. When we decided to require a big TeX there was no reason for
hashing any more, and we dropped it. Writing this hashing code was
probably the worst experience I ever had with TeX ;-).

Allan Adler continues

I noticed that there are other tricks that are used on the .g files in
the library, such as putting emacs in Outline mode when one looks at them
in emacs. But I think that has nothing to do with the online
documentation.

Correct, this is simply for our convenience.

I hope this helps.

Martin.

-- .- .-. - .. -.  .-.. --- ...- . ...  .- -. -. .. -.- .-
Martin Sch"onert,   Martin.Schoenert@Math.RWTH-Aachen.DE,   +49 241 804551
Lehrstuhl D f"ur Mathematik, Templergraben 64, RWTH, 52056 Aachen, Germany