2 The gapmacro.tex Manual Format

Sections

1. The Main File
2. Chapters and Sections
3. Suppressing Indexing and Labelling of a Section and Resolving Label Clashes
4. Labels and References
5. TeX Macros
6. TeX Macros for Domains
7. Examples, Lists, and Verbatim
8. Tables, Displayed Mathematics and Mathematics Alignments
9. Testing the Examples
10. Usage of the Percent Symbol
11. Catering for Plain Text and HTML Formats
12. Umlauts
13. Producing a Manual
14. Using buildman.pe

The current GAP manual books and most of the GAP 4 package documentation is written in a restricted TeX format, using a set of macros defined in the file GAPPATH/doc/gapmacro.tex. This chapter describes this format and how to create the final documents (which can be printed or used by GAP's online help) from it.

See TeX Macros and Examples, Lists, and Verbatim for details on the restricted set of available TeX commands.

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.

If you are planning to write new documentation for a GAP package you can either use the format described in this chapter or use an alternative approach. For example some packages have started to use the GAPDoc package for their documentation, see Chapter GAPDoc:Introduction and Example in the GAPDoc manual or type

gap> ?GAPDoc:chapters

in GAP's online help for a table of contents, or (if it is not available in your installation) see: http://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc/

If you want to use yet another document format you must provide certain information to the interface of GAP's online help. This is described in chapter Interface to the GAP Help System.

2.1 The Main File

The main TeX file is called manual.tex. This file should contain the following commands:

\input ../gapmacro
\Package{package-name}
\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

Now we describe what these commands do:

\input path/gapmacro.tex

inputs the GAP ``style'' and macros file gapmacro.tex. If you are writing a GAP 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 GAP Root Directory in the Reference Manual.

\Package{package-name}

defines a macro \package-name so that when you type {\package-name} (please include the curly braces) the text package-name is typeset in the right way for GAP packages, e.g. if you are writing a package MyPackage then you should include the line

\Package{MyPackage}

in your manual.tex file and then in your chapter files use {\MyPackage} when you refer to MyPackage by name. There is also the command \package{pkg} when you wish to refer to other GAP packages; don't confuse the two i.e. \Package{package-name} defines a macro \package-name but produces no text, and \package{pkg} produces pkg set in the font that is right for GAP packages.

\BeginningOfBook{name-of-book}

starts the book name-of-book. It is used for cross-references, see Labels and References. If you are writing a GAP package use the name of your package here.

\UseReferences{booki}

If your manual cross-refers to another manual, \UseReferences can be used to load the labels of the other books in case cross-references occur. booki should be the path of the directory containing the book whose references you want to load. If you are writing a GAP 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.

If your manual.tex file lives in pkg/qwer/doc and you want to use references to the tutorial use

\UseReferences{../../../doc/tut}

You may also cross-refer to other package manuals and even GapDoc-produced manuals. Just ensure you get the path to the other manual's directory correct relative to the directory in which your manual resides, and if it's a GapDoc-produced manual that you are cross-referring to, use \UseGapDocReferences instead of \UseReferences.

\TitlePage

produces a page containing the title. Please see the example.

\Colophon

\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 in double-column format. For short manuals, the double-column format may be inappropriate; in this case, use \OneColumnTableOfContents instead.

\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. \Input{filei} inputs the file filei.tex, i.e. filei should be the name of the file without the .tex extension. For the chapter format, see Section Chapters and Sections.

\Appendices

starts the appendices, i.e. it modifies the \Chapter command to use uppercase letters to number chapters.

\Bibliography

produces a bibliography, i.e. it reads and typesets the manual.bbl file produced by BibTeX.

\Index

produces an index, i.e. it reads and typesets the manual.ind file produced by the external manualindex program.

\EndOfBook

Finally \EndOfBook closes the book.

Example

Assume you have a GAP 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 ../../../doc/gapmacro         % The right path from pkg/qwert/doc
\Package{Qwert}                      % Defines macro {\Qwert}
\BeginningOfBook{qwert}
  \TitlePage{
    \centerline{\titlefont Qwert}\medskip           % Package name
    \centerline{\titlefont ---}\medskip
    \centerline{\titlefont A GAP4 Package}\bigskip\bigskip
    \centerline{\secfont Version 1.0}\medskip
    % If the package interfaces with an external program ...
    \centerline{\secfont Based on qwert Standalone Version 3.14}\vfill
    \centerline{\secfont by}\vfill
    \centerline{\secfont Q. Mustermensch}\medskip   % Author
    \centerline{Department of Mathematics}\medskip  % Affiliation
    \centerline{University of Erewhon}\medskip
    \centerline{\secfont email: qmuster@erewhon.uxyz.edu.ut} % Email address
    \vfill
    \centerline{\secfont{\Month} \Year}
  }
  \TableOfContents
  \FrontMatter
    \Input{copyright}
    \Input{preface}
  \Chapters
    \Input{qwert}
    \Input{extend}
  \Appendices
    \Index
\EndOfBook

Occasionally there will be the need for additional commands over and above those shown above. The ones described below should be the only exceptions.

• There may be other packages that are referred to a lot, so that it's worthwhile to add more \Package commands. (There's nothing special about \Package, you can use it to define macros for other packages besides the package being documented.)

• Besides the macros {\Month} and {\Year}, which typeset the current month (as an English word) and the year (all four digits), respectively, there are also {\Day} and {\Today} which are mainly intended for drafts. {\Day} typesets the day of the month as a number and {\Today} is equivalent to: {\Day} {\Month} {\Year}.

• Sometimes one desires a chapter to be unnumbered in the TeX-produced manuals, e.g. the Tutorial manual has GAP's Copyright Notice as an unnumbered chapter. To achieve this one inputs the file containing the chapter via TeX's \input command rather than \Input. However, neither the on-line help browser nor the HTML converter ``sees'' such chapters. Thus if it is desired that the on-line help browser and the HTML manuals should also have such chapters, they must be ``input'' again via the \PseudoInput command (not necessarily in the same manual).

• For chapters that should only appear via the on-line help browser or in the HTML manuals, one may use the \PseudoInput command. Any \PseudoInput commands should come after all \Input commands; failure to do this will result in different numbering of \Input chapters for TeX-produced and HTML manuals. The syntax of this command is as follows:

  \PseudoInput{filename}{six-entry}{chaptername}

  where filename is the name of the file containing the chapter without the .tex extension, as for the \Input command, six-entry is the section-index-entry for the chapter (written to the manual.six file) and chaptername is the actual argument of the \Chapter command that appears at the beginning of filename.tex. The argument six-entry enables the on-line text browser to reference the chapter by a name other than chaptername. Thus a copyright chapter for the book with name name-of-book might have chaptername ``Copyright Notice'' but six-entry ``Copyright'', which would enable one to access the chapter ``Copyright Notice'' via ?name-of-book:copyright via the on-line browser. The HTML converter adds an index entry for both six-entry and chaptername.

Note

Usage of the commands \input and \PseudoInput in the way described above will necessitate special treatment of references to such chapters. For such purposes, there is a special variant of the %display environment (see Catering for Plain Text and HTML Formats), e.g. a copyright notice appearing via \input at the beginning of a TeX-produced manual and appearing in the non-TeX manuals -- the on-line help browser or HTML manual -- via a \PseudoInput command as described above, may be referenced via

%display{tex}
See the copyright notice at the beginning of this book.
%display{nontex}
%See "Copyright".
%enddisplay

2.2 Chapters and Sections

The contents of each chapter must be in its own .tex file. The command \Chapter{chaptername} starts a new chapter named chaptername; it should constitute the first non-comment (and non-blank) line of the file containing a chapter. A chapter begins with an introduction to the chapter and is followed by sections created with the \Section{secname} command. The strings chaptername and secname are automatically available as references (see Section Labels and 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.

Finally, the HTML converter requires that each \Section line is preceded by a line starting with at least 16 percentage signs (conventionally, one actually types a full line of percentage signs). The HTML converter stops converting a section whenever it hits such a line; therefore do not add lines starting with 16 or more % signs which are not just before a \Section command. Failure to include the line of percentage signs before a \Section line will cause the converter to crash, due to the discovery of what it sees as two \Section commands within the one section.

2.3 Suppressing Indexing and Labelling of a Section and Resolving Label Clashes

Sometimes one does not wish a section to be indexed. To suppress the indexing of a section, simply add the macro \null after the \Section command, e.g.

\Section{section-name}\null

and then section-name will still generate a label (so that you can still refer to it via Section "section-name"), but section-name will not appear in the index.

Occasionally, one has a dedicated section for the description of a single function. If the label generated for the section coincides with the label for a subsection (generated by a \> command) a multiply defined label results. In these cases, one would generally rather that the section did not generate a label or an index entry. To suppress the generation of both the label and the index entry of such a section, simply add the macro \nolabel immediately after the \Section command, e.g. for a section dedicated to the function func:

\Section{func}\nolabel

Note: Labels are generated by converting to lowercase and removing whitespace. So coincidences can occur when you might not have expected it. An alternative to index suppression to resolve label clashes is to include a sub-label for the function in the \> command (see Section TeX Macros).

2.4 Labels and References

Each \Chapter, \Section and \> command generates a (short) label label, which is extended by name-of-book (the argument of \BeginningOfBook mentioned earlier in Section The Main File), to create a ``long label'' long-label, and emitted to a file manual.lab. The construction of long-label is name-of-book:label, where the label generated by either of the commands \Chapter or \Section is just its chaptername or secname argument. For \>, there are a few cases to consider, and we'll consider them in Section TeX Macros, where we meet the various forms of the \> command. To see how to resolve problems with label clashes see Section Suppressing Indexing and Labelling of a Section and Resolving Label Clashes.

A reference to a label any-label (long or short) is made by enclosing any-label in a pair of double quotation marks: "any-label"; it is replaced by the number of the \Chapter, \Section or \> command that generated any-label in the first place. Generally, one only needs to make references to long labels when referring to other manuals. For references within the same manual, short labels are sufficient, except when the short label itself contains a colon.

Example

Since the \BeginningOfBook command for this manual defines name-of-book to be ext, the long label for the current section is ext:Labels and References and so a reference to this section within this manual might be: Section "Labels and References" (which is typeset as: Section Labels and References). From another manual, a long label reference is required.

Another example

The first chapter of this manual has the title ``About: Extending GAP'', which contains a colon. Hence, to refer to that chapter, one must use a long label:

Chapter "ext:About: Extending GAP"

Note

In actual fact long labels are first sanitised by conversion to lower case and removal of superfluous white space (multiple blanks and new lines are converted to a single space). The same sanitisation process is applied to references. Thus,

Chapter "ext:about:                                             extending
Gap"

2.5 TeX Macros

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. Since, the plain text on-line help, doesn't have special fonts, it leaves in much of the markup, including the left and right quotes that surround something intended to be displayed in typewriter type, the angle brackets that surround something intended to appear in italics, and the dollar-signs enclosing mathematics; you will need to keep that in mind when reading the following section.

`text'

sets 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, e.g., `for' produces for. See also <text>. Use \< to get a ``less than'' sign.

``text''

encloses text in double quotes, e.g., ``double-quoted text'' produces ``double-quoted text''. In particular, ``text'' does not set `text' in typewriter style; use `{`text'}' to produce `text'. Double quotes are mainly used to mark a phrase which will be defined later or is used in an uncommon way.

\lq

sets a single left quote: `. For a phrase text that is to be defined later or is used in an uncommon way, please use ``text'' (which encloses text in double quotes rather than single quotes).

\rq, \pif

each set a single apostrophe (right quote): '. For the HTML and on-line manuals \accent19{} also sets an apostrophe; however the TeX-derived manuals produce an acute-d blankspace (what it in fact is).

\accent127

sets an umlaut, e.g. \accent127a produces ä. Do not use the shorthand \" (otherwise the HTML converter will not translate it properly).

<text>

sets text in italics. This can also be used inside $...$ and `...'. Use \< to get a ``less than'' sign. <...> is used to denote a variable which is an argument of a function; a typical application is the description of a function:

\>Group( <gens> ) F
The function `Group' constructs a group generated by <gens>.

The F at the end of the first line in the above example indicates that Group is a function (see the \> entry, below).

*text*

sets text in emphasized style.

$a.b$

Inside math mode, you can use . instead of \cdot (a centred multiplication dot). Use \. for a full stop inside math mode. For example, $a.b$ produces a·b while $a\.b$ produces a.b.

\cite{...}

produces a reference to a bibliography entry (the \cite[...]{...} option of LaTeX is not supported).

"label"

produces a reference to label. Labels are generated by the commands \Chapter, \Section (see Labels and References), and \> commands (see below).

\index{index-entry}

defines an index entry index-entry. Besides appearing in the index, index-entry is also written to the section index file manual.six used by the on-line help. An exclamation mark (!), if present, is used to partition index-entry into main entry (left part) and subentry (right part) components, in the index. TeX converts index-entry to lowercase and sets it in roman type, in the index. The HTML converter respects case and uses the default font, in producing the HTML manual index. index-entry must be completely free of special characters and font changing commands; if you need special fonts, characters or commands use one of \indextt or \atindex.

Note that for the HTML converter to process indexing commands (\index, \indextt and \atindex) correctly they must be on lines of their own. There can be several indexing commands on the same line, but there should be no horizontal whitespace before each indexing command, and if an indexing command needs to be broken over lines place a % at the point of the break at the end of the line to mark a ``continuation''.

For the HTML converter it works best to put indexing commands all together at the beginning of a paragraph, rather than strewn between lines of a paragraph. However, for the TeX-produced manuals after a maths display one gets a rogue space if you do this (this is a bug); you can work around the bug by putting at least one word of the paragraph followed by your line(s) of indexing commands.

Note also that indexing commands do not produce labels for cross-references; they only produce entries for the index. Labels are only produced by the chapter (\Chapter), section (\Section) and subsection (\>) commands.

\indextt{index-entry}

is the same as \index{index-entry}, except that index-entry is set by TeX in typewriter style, respecting case; the HTML converter sets index-entry in the default font. Again, index-entry should be completely free of special characters and font changing commands, and ! may be used for sub-entries in the same way as for \index. Note that a sub-entry component, if present, is not set in typewriter style for the TeX-produced manuals; if you want that it is, use \atindex.

\atindex{sort-entry}{|indexit}

is simply a special form of the \index command that tells TeX to typeset the page number in italics.

\atindex{sort-entry}{@index-entry}

The HTML converter treats this command as if it was \index{index-entry}, except that it strips out any font information and sets it in the default font, but nevertheless respects case. index-entry may have |indexit at the end which is ignored by the HTML converter.

The TeX-produced manuals set the index entry as index-entry respecting font and case, and list it according to sort-entry. If a sub-entry is required then it should be present behind a ! in both the sort-entry and index-entry; the only difference between the sub-entry in sort-entry and that in index-entry, is that the sort-entry sub-entry should be stripped of mark-up and font changing command. The index-entry component is ignored when constructing the manual.six files, and is also ignored by the HTML converter. Anything after an ! in sort-entry is ignored when constructing the manual.idx file that is processed by MakeIndex. Macros like {\GAP} are allowed in index-entry. However, any ` that appears in index-entry must be preceded by \noexpand; sort-entry must be completely free of special characters and font changing commands.

In general, one should make sort-entry the same as index-entry modulo fonts and other mark-up, e.g.,

\atindex{Fred!Nerk}{@\noexpand`Fred'!\noexpand`Nerk'}

{\GAP}

typesets GAP.

\package{pkg}

typesets pkg in the font correct for GAP packages (respecting case). This is intended for cross-referencing other GAP packages. There is also the command \Package{mypkg} command which defines a macro \mypkg so that when you type {\mypkg} (please include the curly braces) the text mypkg is typeset in the right way for GAP packages. The \Package command should normally be included in one's manual.tex file (see The Main File) and just allows one to type {\mypkg} rather than the longer \Package{mypkg} as one is frequently likely to do when formulating one's own GAP package documentation. So, just to be clear about the difference between \Package and \package, \Package{mypkg} defines a macro \mypkg but produces no text, and \package{pkg} produces pkg set in the font that is right for GAP packages.

\>

produces a subsection. The line following the \> 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.

There are several forms of the \> command. In all forms, a label and index entry are generated; the HTML converter uses the label to form an index entry, respecting case and setting in roman type. If the next non-space character is not a left quote (`) it is assumed that the subsection is for a ``function''; we exhibit these forms first.

\>func

While this form is supported; it is discouraged. If func is a 0-argument function, func should be followed by an empty pair of brackets (see \>func(args) below). If func is actually a global variable then \>`global-var' V should be used instead (see below). In order for this form to be parsed correctly the remainder of the line to the right of func must be empty. It generates func as both a label and index entry; func appears as is, in typewriter type in the TeX-derived manual index.

\>func(args)

The macro uses the brackets after func to parse the arguments args. Thus, it is necessary for the function to use brackets and for the arguments to have none. (We use the term ``function'' loosely here to mean ``a GAP command with arguments''; we really mean an object that GAP knows as a: ``Function'', ``Property'', ``Operation'', ``Category'', or ``Representation'' --- but not ``Variable'', since a ``Variable'' does not have arguments.) The label and index entry generated consists of the text between the > and opening bracket. The index entry is set as is (i.e. without conversion to lowercase) in typewriter type in the TeX-derived manual index. Here is an example of how to use \>; the index entry is ``Size'' (in typewriter type, with mixed case preserved).

\>Size( <obj> ) A

The A indicates that Size is an ``Attribute''. Instead of A there can be F, P, O, C, or R which indicate that a command is a ``Function'' (probably the most common), ``Property'', ``Operation'', ``Category'', or ``Representation'', respectively. For the forms of the \> command followed by a left quote, V indicating ``Variable'' (an object without arguments), is also possible. (See Section Manual Conventions and Chapter Types of Objects in the reference manual).

\>func(args)!{sub-entry}

This is a special form of the previous command, that forms a label func!sub-entry and an index entry with main entry func (set in typewriter type and respecting case) and sub-entry sub-entry (set in roman type but also respecting case).

The remaining forms of the command \> expect to be followed by a `.

\>`command'{label}

works as \> without `...', but will not use bracket matching; it simply displays command as a header, which appears in typewriter type. It will use label as both the label and index entry, and the index entry is set in roman type. Whenever label contains a !, it is used to partition label into main entry (left part) and subentry (right part) components, in the index.

\>`<a> + <b>'{addition}
\>`Size( <obj> )'{size} A

In the first of the examples immediately above, the first form of \> cannot be used because no brackets occur. Also, observe that there is no command type (it's not appropriate here); TeX does not need it to correctly parse a \> entry, in general. The second example differs from our previous Size example, in that the index entry will be typeset as ``size'' (in roman type), rather than ``Size''. Also, the index entry is always converted to lowercase, no matter what case or mixed case was used.

\>`command'{label}!{sub-entry}

is equivalent to: \>`command'{label!sub-entry}.

\>`command'{label}@{index-entry}

works as \>`command'{label}, except that it uses label for sorting the index entry and the index entry itself is printed as index-entry. References to the subsection use label. (Note that the HTML converter ignores everything after an @ symbol in these commands, essentially treating the command as if it were \>`command'{label}. However, the HTML converter also always preserves the case in a label. ) Here are two examples.

\>`Size( <obj> )'{size}@{`Size'} A
\>`Size( GL( <n>, <q> ) )'{Size!GL( n, q )}@{`Size'! `GL'( \noexpand<n>, \noexpand<q> )} A

The first of these examples is equivalent to ``\>Size( <obj> )''. For the second example, it was necessary to use ` and ', since the argument contained brackets. Note that \noexpand is needed before < here, but not needed before ` in the index-entry argument. Otherwise, the rules for sub-entries are the same as for \atindex.

\>`global-var' V

This is actually a short-hand for: ``\>`global-var'{global-var}@{`global-var'} V'' to save you some typing when creating subsections for global variables, i.e., global-var is the label and the index entry appears in typewriter type, with mixed case preserved.

\){\fmark ...}

is like \> except that it produces no label and index entry. It is \fmark that produces the filled in right arrow. Omitting it produces a line in typewriter type.

\){\kernttindent ...}

is useful for producing a line in typewriter type, that you might otherwise have typed between \begintt and \endtt, but where you actually want the TeX macros and variables <...> to be interpreted.

\URL{url}

prints the WWW URL url. In the HTML version this will be a HREF link.

\Mailto{email}

prints the email address email. In the HTML version this will be a mailto link.

Note: When a TeX macro is followed by a space, TeX generally swallows up the space; one way, and it is the GAP-preferred way, of preventing the space being swallowed up, is by enclosing the macro in {...}. When a macro is often followed by a space, it's a good habit to get into to always enclose that macro in {...} (the braces do nothing when the macro is not followed by a space, and prevent TeX from swallowing up the space, otherwise). Thus the macro for GAP should always be typed {\GAP}. Similarly, macros like \lq, \rq and \pif should probably always appear in braces; moreover the word ``don't'' typeset via ``don{\pif}t'' will actually be interpreted correctly by the on-line browser.

2.6 TeX Macros for Domains

The following macros are required for the following common domains:

\N

the natural numbers (you should probably indicate whether by your convention N includes zero or not, when using this);

\Z

the integers;

\Q

the rational numbers;

\R

the real numbers;

\C

the complex numbers;

\F

a field; and

\calR

a general domain e.g. a ring.

2.7 Examples, Lists, and Verbatim

In order to produce a list of items with descriptions use the \beginitems, \enditems environment, i.e. this is a ``description'' environment in the parlance of LaTeX and HTML.

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

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 ...

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
\itemitem{--}
    a sub-item of the second entry
\itemitem{--}
    another sub-item of the second entry
\item{(c)}
    third entry
\endlist

It is printed as follows.

(a)

first entry

(b)

second entry

--

a sub-item of the second entry

--

another sub-item of the second entry

(c)

third entry

The above example will take advantage of the ordered and unordered list environments in the HTML version, with the addition of slightly more mark-up. First, we present the example again with that additional mark-up, and then we explain how it works.

\beginlist%ordered{a}
\item{(a)}
    first entry
\item{(b)}
    second entry
\itemitem{--}%unordered
    a sub-item of the second entry
\itemitem{--}
    another sub-item of the second entry
\item{(c)}
    third entry
\endlist

It is printed as follows (of course, you should see no difference in the TeX-produced and on-line versions of this manual).

1. first entry
2. second entry
   • a sub-item of the second entry
   • another sub-item of the second entry

\beginexample
gap> 1+2;
3
\endexample

gap> 1+2;
3

\beginexample|unstableoutput
gap> Exec("date");
Sun Oct  7 16:23:45 CEST 2001
\endexample

gap> Exec("date");
Sun Oct  7 16:23:45 CEST 2001

From a theorem of Gauss we know that
$$
b_N = \left\{
\matrix{
\frac{1}{2}(-1+\sqrt{N})    &{\rm if} &N \equiv 1  &\pmod 4\cr
\frac{1}{2}(-1+i \sqrt{N})  &{\rm if} &N \equiv -1 &\pmod 4\cr
}
\right.
$$

%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)
%enddisplay

%display{tex}
TeX version (only used by TeX manual)
%display{nontex}
%HTML and Text version (interpreted normally, after removing the \% symbol)
%enddisplay

%display{nonhtml}
%Text version (interpreted normally by built-in browser, after removing the
%\% symbol)
%enddisplay

%display{nontext}
%HTML version (interpreted normally by HTML converter, after removing the 
%\% symbol)
%enddisplay

tex manual

bibtex manual

tex manual
tex manual

GAPDOCPATH/manualindex manual

tex manual

#############################################################################
##
#O  DirectSumOfAlgebras( <A1>, <A2> )
#O  DirectSumOfAlgebras( <list> )
##
##  is the direct sum of the two algebras <A1> and <A2> respectively of the
##  algebras in the list <list>.
##
##  If all involved algebras are associative algebras then the result is also
##  known to be associative.
##  If all involved algebras are Lie algebras then the result is also known
##  to be a Lie algebra.
##
##  All involved algebras must have the same left acting domain.
##
##  The default case is that the result is a structure constants algebra.
##  If all involved algebras are matrix algebras, and either both are Lie
##  algebras or both are associative then the result is again a
##  matrix algebra of the appropriate type.
##
DeclareOperation( "DirectSumOfAlgebras", [ IsDenseList ] );

\Declaration{DirectSumOfAlgebras}

@msfiles = ("algebra","algfp","alglie","mgmring");
@gdfiles = ("algebra","alghom","alglie","object","liefam","mgmring","algrep",
            "lierep");
DIR = "../ref";
LIB = "../../lib";

\>DirectSumOfAlgebras( <A1>, <A2> ) O
\>DirectSumOfAlgebras( <list> ) O

versionnumber=4.3
versionsuffix=4r3

When `unzoo -x' is applied to {\GAP}~{{versionnumber}}'s `zoo' file
`gap{{versionsuffix}}.zoo' a directory `gap{{versionsuffix}}' is formed.

When `unzoo -x' is applied to {\GAP}~4.3's `zoo' file
`gap4r3.zoo' a directory `gap4r3' is formed.