This chapter describes the manual format used to generate the GAP manual and the on-line help. The TeX source of the manual is also used to generate the on-line help. Therefore some restrictions apply to the TeX macros one should use. These restriction are described in sections TeX Macros and Examples, Lists, and Verbatim.
The first sections The main file and Chapters and Sections describe the general layout of the files in case you need to write your own package documentation.
The main TeX file is called ``manual.tex''. This file should contain only the following commands:
\input ../gapmacro.tex
\BeginningOfBook{
name-of-book}
\UseReferences{
book1}
...
\UseReferences{
bookn}
\TitlePage{
title}
\Colophon{
text}
\TableOfContents
\FrontMatter
\immediate\write\citeout{\bs bibdata{
mybibliography}}
\Input{
file1}
...
\Input{
filen}
\Chapters
\Input{
file1}
...
\Input{
filen}
\Appendices
\Input{
file1}
...
\Input{
filen}
\Bibliography
\Index
\EndOfBook
The first line inputs the file ``gapmacro.tex''. If you are writing a share package either copy this file or use a relative path. The former method will always work but requires you to keep the file consistent with the system while the latter forces users to change the ``manual.tex'' file if they are installing a package in a private location. See also Section ref:GAP Root Directory in the Reference Manual.
\BeginningOfBook
starts the book, name-of-book is used for
cross-references, see Labels and References. If you are writing a
share package use the name of your package here.
If your manual consists of more than one book the command
\UseReferences
can be used to load the labels of the other books in
case cross-references occur. booki is the path of the directory
containing the book whose references you want to load. If you are
writing a share package and you need to reference the main GAP manual,
use \UseReferences
for each book you want to reference. However, as
said above this requires changes to the ``manual.tex'' file if the
package is not installed in the standard location.
Example
If your ``manual.tex'' file lives in ``pkg/qwer/doc'' and you want to use references to the tutorial use
\UseReferences{../../../doc/tut}
\TitlePage
produces a page containing the title
.
\Colophon
produces a page following the title that can be used for more
explicit author information, acknowledgements, dedications or whatsoever.
\TableOfContents
produces a table of contents.
\FrontMatter
starts the front matter chapters such as
a copyright notice or a preface.
The line
\immediate\write\citeout{\bs bibdata{<mybibliography>}}is for users of BibTeX. It will use the file
mybibliography.bib
to
fetch bibliography information.
\Chapters
starts the chapters of the manual, which are included via
\Input
. For the chapter format, see Section Chapters and Sections.
\Appendices
starts the appendices.
\Bibliography
produces a bibliography, and \Index
an index.
Finally \EndOfBook
closes the book.
Example
Assume you have a share package ``qwert'' with two chapters ``Qwert'' and ``Extending Qwert'', a copyright notice, a preface, no exercises, then your ``manual.tex'' would basically look like:
\input gapmacro.tex \BeginningOfBook{qwert} \TitlePage{ \centerline{\titlefont The Share Package ``qwert''} \centerline{\secfont by} \centerline{\titlefont Q. Mustermensch} } \TableOfContents \FrontMatter \Input{copyright} \Input{preface} \Chapters \Input{qwert} \Input{extend} \Appendices \Index \EndOfBook
The command \Chapter{
chaptername}
starts a new chapter named
chaptername, a chapter begins with an introduction to the chapter and
is followed be sections created with the \Section{
secname}
command. The strings chaptername and secname are automatically
available as references.
There must be no further commands on the same line as the \Chapter
or \Section
line,
and there must be an empty line after a \Chapter
or \Section
command.
This means that \index
commands referring to the chapter or section
can be placed only after this empty line.
The contents of each chapter must be in its own .tex
file.
To use the HTML converter, each \Section
line must be preceded by a line
full of percentage signs.
However the converter will stop converting a section whenever it his such a
line, therefore do not add lines with 16 or more
just before a \Section
command.
As the manual pages are also used as on-line help, and are automatically converted to HTML, the use of special TeX commands should be avoided. The following macros can be used to structure the text, the mentioned fonts are used when printing the manual, however the on-line help and HTML are free to use other fonts or even colour.
text
in typewriter style.
This is typically used to denote GAP keywords such as for
and
false
or variables that are not arguments to a function,
see also <text>
.
Use \<
to get a ``less than'' sign.
text
'' text
in typewriter style, use ``{text
}'' to produce
``text''. Doublequotes are mainly used to mark a phrase which will
be defined later or is used in an uncommon way.
\pif
<text>
$...$
and
``...''.
Use \<
to get a ``less than'' sign.
<text>
is used to denote a variable which is an argument of a
function, a typical application is the description of a function:
\>Group( <U> ) The function `Group' constructs a group isomorphic to <U>.
*text*
$a.b$
.
instead of \cdot
.
Use \.
for a full stop inside math mode.
For example, $a.b$
produces a.b
while $a\.b$
produces a\.b.
\cite{...}
\cite[...]{...}
option of LaTeX is not supported).
"ref"
\Chapter
, \Section
(see Labels and References).
\index{...}
manual.six
used by the on-line help.
An exclamation mark (!
) may be used to indicate index subentries.
\indextt{...}
\index{...}
, except that the index entry
is printed in typewriter style.
{\GAP}
\>
\>
entry must either contain another \>
entry (in which case the further entries are assumed to be variants
and do not start a new subsection) or must be empty.
The description text will follow this empty line.
Here is an example how to use \>
; the index entry is Size
.
\>Size( <obj> )
\>
``command'{label}' \>
but will not use bracket matching but simply display
command as a header.
It will use label as an index entry.
\>`<a> + <b>'{summation} \>`Size(<obj>)'{size}In the first of the above examples,
\>
cannot be used because
no brackets occur.
In the second example, the difference to the use of \>
is
that the index entry will be typeset as ``size'' instead of ``Size''.
\>
``command'{label}@{text}' \>
but will not use bracket matching but simply display
command as a header.
It will use label for sorting the index entry which will be printed
as text.
Here are two examples.
\>`Size(<obj>)'{size}@{`Size'} \>`Size(GL(<n>,<q>))'{size!gl}@{`Size(GL(<n>,<q>))'}
\){\fmark ...}
\>
except that it produces no label and index entry.
2.4 Examples, Lists, and Verbatim
In order to produce a list of items with descriptions use the
\beginitems
, \enditems
environment.
For example, the following list describes base
, knownBase
, and
reduced
.
The different item/description pairs must be separated by blank lines.
\beginitems `base' & must be a list of points ... `knownBase' & If a base for <G> is known in advance ... `reduced' (default `true') & If this is `true' the resulting stabilizer chain will be ... \enditems
This will be printed as
base
knownBase
reduced
(default true
) true
the resulting stabilizer chain will be ...
In order to produce a list in a more compact format,
use the \beginlist
, \endlist
environment.
An example is the following list.
\beginlist \item{(a)} first entry \item{(b)} second entry \item{(c)} third entry \endlist
It is printed as follows.
Example GAP sessions are typeset in typewriter style
using the \beginexample
, \endexample
environment.
\beginexample gap> 1+2; 3endtt
typesets the example
gap> 1+2; 3
Non-GAP examples are typeset in typewriter style
using the \begintt
, \endtt
environment.
The manual style will automatically indent examples. It also will break
examples which become too long to fit on one page. If you want to encourage
breaks at specific points in an example, end the example with \endexample
and immediately start a new example environment with \beginexample
on
the next line.
For purposes of automatically checking the manual,
the GAP examples in one chapter (the text between \beginexample
and \endexample
) should produce the same output, up to line breaks
and whitespace, whenever they are run in the same order
immediately after starting GAP
(this will ensure that the global random number generator is initialized
to the same values).
For more details,
see the last paragraph of tut:Starting and Leaving GAP in the Tutorial.
To permit this automatic running,
examples that shall produce error messages should be put between
\begintt
and \endtt
such that they will not be seen by this automatic test.
The automatic test also requires that examples are not indented
in the files;
in the printed manual,
the lines between \beginexample
and \endexample
and the lines between \begintt
and \endtt
are automatically
indented.
As described in TeX Macros, the use of macros should be restricted to the ones given in the previous sections. However, in rare situations one might be forced to use other TeX macros, for example in order to typeset a lattice. In this case you should provide an alternative for the on-line help. This can be done by putting in guiding commands as TeX comments:
display{tex} TeX version (only used by TeX manual) display{html} HTML version (only used by HTML manual) display{text} Text version (only used by the built-in manual browser)endtt
However, this use of special macros should be limited to a minimum.
To produce Umlauts use \accent127
and not the shorthand
beginverbatim
"
endverbatim
Otherwise the HTML converter will not translate it properly.
To produce a manual you will need the following files:
manual.tex
\Input
commands for other files.
gapmacro.tex
\Input
statement in manual.tex
.
You can either use the version in the doc
directory of GAP
(use a relative path then) or make a copy.
manual.mst
makeindex
to fetch index information.
It must reside in your manual directory.
GAPDOCPATH/manualindex
makeindex
.
GAPDOCPATH
is the path of the doc
directory of your GAP
distribution.
For bibliography information you will need a file manual.bbl
. If you
intend to create it with BibTeX, you will need to indicate the
appropriate .bib
file (as described in section The main file). Then
after running TeX once over the manual, run BibTeX to create the
manual.bbl
file.
Assuming that all necessary files are there,
on a Unix system the following calls will then produce a file manual.dvi
as well as a file manual.six
which is used by the GAP help functions:
Go to the directory holding the manual. Call
tex manualto produce bibliography information. Unless you provide a
manual.bbl
file
which is not produced by BibTeX, call
bibtex manualto produce the
manual.bbl
file. Then run TeX twice over the manual to
fill all references and produce a stable table of contents:
tex manual tex manualIf you have sections which are named like commands, you may get messages about redefined labels. At this point you can ignore these.
Now it is time to produce the index. Call
GAPDOCPATH/manualindex manualto run
makeindex
. This produces a file manual.ind
. Finally, once again
run
tex manualto incorporate the index. The manual is ready.
[Top] [Previous] [Up] [Next] [Index]
GAP 4 manual