Quelle AutoDoc.tex Sprache: Latech

% generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[a4paper,11pt]{report}

            \usepackage{a4wide}
            \newcommand{\bbZ}{\mathbb{Z}}

\usepackage[top=37mm,bottom=37mm,left=27mm,right=27mm]{geometry}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage[utf8]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{color}
\definecolor{FireBrick}{rgb}{0.5812,0.0074,0.0083}
\definecolor{RoyalBlue}{rgb}{0.0236,0.0894,0.6179}
\definecolor{RoyalGreen}{rgb}{0.0236,0.6179,0.0894}
\definecolor{RoyalRed}{rgb}{0.6179,0.0236,0.0894}
\definecolor{LightBlue}{rgb}{0.8544,0.9511,1.0000}
\definecolor{Black}{rgb}{0.0,0.0,0.0}

\definecolor{linkColor}{rgb}{0.0,0.0,0.554}
\definecolor{citeColor}{rgb}{0.0,0.0,0.554}
\definecolor{fileColor}{rgb}{0.0,0.0,0.554}
\definecolor{urlColor}{rgb}{0.0,0.0,0.554}
\definecolor{promptColor}{rgb}{0.0,0.0,0.589}
\definecolor{brkpromptColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapinputColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapoutputColor}{rgb}{0.0,0.0,0.0}

%%  for a long time these were red and blue by default,
%%  now black, but keep variables to overwrite
\definecolor{FuncColor}{rgb}{0.0,0.0,0.0}
%% strange name because of pdflatex bug:
\definecolor{Chapter }{rgb}{0.0,0.0,0.0}
\definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064}

\usepackage{fancyvrb}

\usepackage{mathptmx,helvet}
\usepackage[T1]{fontenc}
\usepackage{textcomp}

\usepackage[
            pdftex=true,
            bookmarks=true,
            a4paper=true,
            pdftitle={Written with GAPDoc},
            pdfcreator={LaTeX with hyperref package / GAPDoc},
            colorlinks=true,
            backref=page,
            breaklinks=true,
            linkcolor=linkColor,
            citecolor=citeColor,
            filecolor=fileColor,
            urlcolor=urlColor,
            pdfpagemode={UseNone},
           ]{hyperref}

\newcommand{\maintitlesize}{\fontsize{50}{55}\selectfont}

% write page numbers to a .pnr log file for online help
\newwrite\pagenrlog
\immediate\openout\pagenrlog =\jobname.pnr
\immediate\write\pagenrlog{PAGENRS := [}
\newcommand{\logpage}[1]{\protect\write\pagenrlog{#1, \thepage,}}
%% were never documented, give conflicts with some additional packages

\newcommand{\GAP}{\textsf{GAP}}

%% nicer description environments, allows long labels
\usepackage{enumitem}
\setdescription{style=nextline}

%% depth of toc
\setcounter{tocdepth}{1}

%% command for ColorPrompt style examples
\newcommand{\gapprompt}[1]{\color{promptColor}{\bfseries #1}}
\newcommand{\gapbrkprompt}[1]{\color{brkpromptColor}{\bfseries #1}}
\newcommand{\gapinput}[1]{\color{gapinputColor}{#1}}

\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\mbox{}\vfill

\begin{center}{\maintitlesize \textbf{ AutoDoc \mbox{}}}\\
\vfill

\hypersetup{pdftitle= AutoDoc }
\markright{\scriptsize \mbox{}\hfill  AutoDoc  \hfill\mbox{}}
{\Huge \textbf{ Generate documentation from \textsf{GAP} source code \mbox{}}}\\
\vfill

{\Huge  2025.10.16 \mbox{}}\\[1cm]
{ 16 October 2025 \mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\Large \textbf{ Sebastian Gutsche\\
    \mbox{}}}\\
{\Large \textbf{ Max Horn\\
    \mbox{}}}\\
\hypersetup{pdfauthor= Sebastian Gutsche\\
    ;  Max Horn\\
    }
\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{ Sebastian Gutsche\\
    }  Email: \href{mailto://gutsche@mathematik.uni-siegen.de} {\texttt{gutsche@mathematik.uni\texttt{\symbol{45}}siegen.de}}\\
  Homepage: \href{https://algebra.mathematik.uni-siegen.de/gutsche/} {\texttt{https://algebra.mathematik.uni\texttt{\symbol{45}}siegen.de/gutsche/}}\\
  Address: \begin{minipage}[t]{8cm}\noindent
Department Mathematik\\
Universit{\"a}t Siegen\\
Walter\texttt{\symbol{45}}Flex\texttt{\symbol{45}}Stra{\ss}e 3\\
57072 Siegen\\
Germany\\
\end{minipage}
}\\
{\mbox{}\\
\small \noindent \textbf{ Max Horn\\
    }  Email: \href{mailto://mhorn@rptu.de} {\texttt{mhorn@rptu.de}}\\
  Homepage: \href{https://www.quendi.de/math} {\texttt{https://www.quendi.de/math}}\\
  Address: \begin{minipage}[t]{8cm}\noindent
Fachbereich Mathematik\\
RPTU Kaiserslautern\texttt{\symbol{45}}Landau\\
Gottlieb\texttt{\symbol{45}}Daimler\texttt{\symbol{45}}Stra{\ss}e 48\\
67663 Kaiserslautern\\
Germany\\
\end{minipage}
}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small
\section*{Abstract}
\logpage{[ 0, 0, 1 ]}
\textsf{AutoDoc} is a \textsf{GAP} package whose purpose is to aid \textsf{GAP} package authors in creating and maintaining the documentation of their
packages. \mbox{}}\\[1cm]
{\small
\section*{Copyright}
\logpage{[ 0, 0, 2 ]}
{\copyright} 2012\texttt{\symbol{45}}2022 by Sebastian Gutsche and Max Horn

This package may be distributed under the terms and conditions of the GNU
Public License Version 2 or (at your option) any later version. \mbox{}}\\[1cm]
{\small
\section*{Acknowledgements}
\logpage{[ 0, 0, 3 ]}
This documentation was prepared using the \textsf{GAPDoc} package \cite{GAPDoc}.

\mbox{}}\\[1cm]
\newpage

\def\contentsname{Contents\logpage{[ 0, 0, 4 ]}}

\tableofcontents
\newpage

\chapter{\textcolor{Chapter }{Getting started using \textsf{AutoDoc}}}\label{Tutorials}
\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X7A0D7AA484F466E1}{}
{
  \textsf{AutoDoc} is a \textsf{GAP} package which is meant to aid \textsf{GAP} package authors in creating and maintaining the documentation of their
packages. In this capacity it builds upon the \textsf{GAPDoc} package (see \href{https://www.gap-system.org/Packages/gapdoc.html} {\texttt{https://www.gap\texttt{\symbol{45}}system.org/Packages/gapdoc.html}}). As such, it is not a replacement for \textsf{GAPDoc}, but rather complements it.

In this chapter we describe how to get started using \textsf{AutoDoc} for your package. First, we explain in Section \ref{Tut:Scratch} how to write a new package manual from scratch.

Then we show in Section \ref{Tut:IntegrateExisting} how you might benefit from \textsf{AutoDoc} even if you already have a complete manual written using \textsf{GAPDoc}.

In Section \ref{Tut:Scaffolds}, we explain how you may use \textsf{AutoDoc} to generate a title page and the main XML file for your manual.

Finally, Section \ref{Tut:AutoDocWorksheet}, explains what \textsf{AutoDoc} worksheets are and how to use them.

\section{\textcolor{Chapter }{Creating a package manual from scratch}}\label{Tut:Scratch}
\logpage{[ 1, 1, 0 ]}
\hyperdef{L}{X7BFBC6907B26AA95}{}
{
  Suppose your package is already up and running, but so far has no manual. Then
you can rapidly generate a ``scaffold'' for a package manual using the \texttt{AutoDoc} (\ref{AutoDoc}) command like this, while running \textsf{GAP} from within your package's directory (the one containing the \texttt{PackageInfo.g} file):
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "AutoDoc" );
  AutoDoc( rec( scaffold := true ) );
\end{Verbatim}
This first reads the \texttt{PackageInfo.g} file from the current directory. It extracts information about the package
from it (such as its name and version, see Section \ref{Tut:Scaffolds:Title}). It then creates two XML files \texttt{doc/NAME{\textunderscore}OF{\textunderscore}YOUR{\textunderscore}PACKAGE.xml} and \texttt{doc/title.xml} inside the package directory. Finally, it runs \textsf{GAPDoc} on them to produce a nice initial PDF and HTML version of your fresh manual.

To ensure that the \textsf{GAP} help system picks up your package manual, you should also add something like
the following to your \texttt{PackageInfo.g}:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  PackageDoc := rec(
    BookName  := ~.PackageName,
    ArchiveURLSubset := ["doc"],
    HTMLStart := "doc/chap0.html",
    PDFFile   := "doc/manual.pdf",
    SixFile   := "doc/manual.six",
    LongTitle := ~.Subtitle,
  ),
\end{Verbatim}
Congratulations, your package now has a minimal working manual. Of course it
will be mostly empty for now, but it already should contain some useful
information, based on the data in your \texttt{PackageInfo.g}. This includes your package's name, version and description as well as
information about its authors. And if you ever change the package data, (e.g.
because your email address changed), just re\texttt{\symbol{45}}run the above
command to regenerate the two main XML files with the latest information.

Next of course you need to provide actual content (unfortunately, we were not
yet able to automate \emph{that} for you, more research on artificial intelligence is required). To add more
content, you have several options: You could add further \textsf{GAPDoc} XML files containing extra chapters, sections and so on. Or you could use
classic \textsf{GAPDoc} source comments. For details on either, please refer to  (\textbf{GAPDoc: Distributing a Document into Several Files}), as well as Section \ref{Tut:IntegrateExisting} of this manual on how to teach the \texttt{AutoDoc} (\ref{AutoDoc}) command to include this extra documentation. Or you could use the special
documentation facilities \textsf{AutoDoc} provides (see Section \ref{Tut:AdvancedAutoDoc}).

You will probably want to re\texttt{\symbol{45}}run the \texttt{AutoDoc} (\ref{AutoDoc}) command frequently, e.g. whenever you modified your documentation or your \texttt{PackageInfo.g}. To make this more convenient and reproducible, we recommend putting its
invocation into a file \texttt{makedoc.g} in your package \index{makedoc.g@\texttt{makedoc.g}} directory, with content based on the following example:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "AutoDoc" );
  AutoDoc( rec( autodoc := true ) );
  QUIT;
\end{Verbatim}
Then you can regenerate the package manual from the command line with the
following command, executed from within in the package directory:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  gap makedoc.g
\end{Verbatim}
}

\section{\textcolor{Chapter }{Documenting code with \textsf{AutoDoc}}}\label{Tut:AdvancedAutoDoc}
\logpage{[ 1, 2, 0 ]}
\hyperdef{L}{X87A00EED866E22E8}{}
{
  To get one of your global functions, operations, attributes etc. to appear in
the package manual, simply insert an \textsf{AutoDoc} comment of the form \texttt{\#!} directly in front of it. For example:
\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=]
  #!
  DeclareOperation( "ToricVariety", [ IsConvexObject ] );
\end{Verbatim}
This tiny change is already sufficient to ensure that the operation appears in
the manual. In general, you will want to add further information about the
operation, such as in the following example:
\begin{Verbatim}[commandchars=|BE,fontsize=\small,frame=single,label=]
  #! @Arguments conv
  #! @Returns a toric variety
  #! @Description
  #!  Creates a toric variety out
  #!  of the convex object <A>conv</A>.
  DeclareOperation( "ToricVariety", [ IsConvexObject ] );
\end{Verbatim}
For a thorough description of what you can do with \textsf{AutoDoc} documentation comments, please refer to chapter \ref{Comments}.

   Suppose you have not been using \textsf{GAPDoc} before but instead used the process described in section \ref{Tut:Scratch} to create your manual. Then the following \textsf{GAP} command will regenerate the manual and automatically include all newly
documented functions, operations etc.:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "AutoDoc" );
  AutoDoc( rec( scaffold := true,
                autodoc := true ) );
\end{Verbatim}
If you are not using the scaffolding feature, e.g. because you already have an
existing \textsf{GAPDoc} based manual, then you can still use \textsf{AutoDoc} documentation comments. Just make sure to first edit the main XML file of your
documentation, and insert the line
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  <#Include SYSTEM "_AutoDocMainFile.xml">
\end{Verbatim}
in a suitable place. This means that you can mix \textsf{AutoDoc} documentation comment freely with your existing documentation; you can even
still make use of any existing \textsf{GAPDoc} documentation comments in your code. The following command should be useful
for you in this case; it still scans the package code for \textsf{AutoDoc} documentation comments and the runs \textsf{GAPDoc} to produce HTML and PDF output, but does not touch your documentation XML
files otherwise.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "AutoDoc" );
  AutoDoc( rec( autodoc := true ) );
\end{Verbatim}
}

\section{\textcolor{Chapter }{Using \textsf{AutoDoc} in an existing \textsf{GAPDoc} manual}}\label{Tut:IntegrateExisting}
\logpage{[ 1, 3, 0 ]}
\hyperdef{L}{X7FA614637B807F4D}{}
{
  Even if you already have an existing \textsf{GAPDoc} manual, it might be interesting for you to use \textsf{AutoDoc} for two purposes:

First off, with \textsf{AutoDoc} it is very convenient to regenerate your documentation.

Secondly, the scaffolding feature which generates a title page with all the
metadata of your package in a uniform way is very handy. The somewhat tedious
process of keeping your title page in sync with your \texttt{PackageInfo.g} is fully automated this way (including the correct version, release data,
author information and so on).

There are various examples of packages using \textsf{AutoDoc} for this purpose only, e.g. \textsf{io} and \textsf{orb}.

\subsection{\textcolor{Chapter }{Using \textsf{AutoDoc} on a complete \textsf{GAPDoc} manual}}\label{Tut:IntegrateExisting:EverythingThere}
\logpage{[ 1, 3, 1 ]}
\hyperdef{L}{X7F3CEB097AF47C1E}{}
{
  Suppose you already have a complete XML manual, with some main and title XML
files and some documentation for operations distributed over all your \texttt{.g}, \texttt{.gd}, and \texttt{.gi} files. Suppose the main XML file is named \texttt{PACKAGENAME.xml} and is in the \texttt{/doc} subdirectory of your package. Then you can rebuild your manual by executing
the following two \textsf{GAP} commands from a \textsf{GAP} session started in the root directory of your package:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "AutoDoc" );
  AutoDoc( );
\end{Verbatim}
In contrast, the \textsf{RingsForHomalg} package currently uses essentially the following code in its \texttt{makedoc.g} file to achieve the same result:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "GAPDoc" );
  SetGapDocLaTeXOptions( "utf8" );
  bib := ParseBibFiles( "doc/RingsForHomalg.bib" );
  WriteBibXMLextFile( "doc/RingsForHomalgBib.xml", bib );
  list := [
           "../gap/RingsForHomalg.gd",
           "../gap/RingsForHomalg.gi",
           "../gap/Singular.gi",
           "../gap/SingularBasic.gi",
           "../examples/RingConstructionsExternalGAP.g",
           "../examples/RingConstructionsSingular.g",
           "../examples/RingConstructionsMAGMA.g",
           "../examples/RingConstructionsMacaulay2.g",
           "../examples/RingConstructionsSage.g",
           "../examples/RingConstructionsMaple.g",
           ];
  MakeGAPDocDoc( "doc", "RingsForHomalg", list, "RingsForHomalg" );
  GAPDocManualLab( "RingsForHomalg" );
\end{Verbatim}
Note that in particular, you do not have to worry about keeping a list of your
implementation files up\texttt{\symbol{45}}to\texttt{\symbol{45}}date.

But there is more. \textsf{AutoDoc} can create \texttt{.tst} files from the examples in your manual to test your package. This can be
achieved via
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "AutoDoc" );
  AutoDoc( rec( extract_examples := true ) );
\end{Verbatim}
Now files \texttt{PACKAGENAME01.tst}, \texttt{PACKAGENAME02.tst} and so appear in the \texttt{tst/} subdirectory of your package, and can be tested as usual using \texttt{Test} (\textbf{Reference: Test}) respectively \texttt{TestDirectory} (\textbf{Reference: TestDirectory}). }

\subsection{\textcolor{Chapter }{Setting different \textsf{GAPDoc} options}}\label{Tut:IntegrateExisting:GapDocOptions}
\logpage{[ 1, 3, 2 ]}
\hyperdef{L}{X7D0DDF2284F2D24A}{}
{
  Sometimes, the default values for the \textsf{GAPDoc} command used by \textsf{AutoDoc} may not be suitable for your manual.

Suppose your main XML file is \emph{not} named \texttt{PACKAGENAME.xml}, but rather something else, e.g. \texttt{main.xml}. Then you can tell \textsf{AutoDoc} to use this file as the main XML file via
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "AutoDoc" );
  AutoDoc( rec( gapdoc := rec( main := "main" ) ) );
\end{Verbatim}

As explained above, by default \textsf{AutoDoc} scans all \texttt{.g}, \texttt{.gd} and \texttt{.gi} files it can find inside of your package root directory, and in the
subdirectories \texttt{gap}, \texttt{lib}, \texttt{examples} and \texttt{examples/doc} as well. If you keep source files with documentation in other directories, you
can adjust the list of directories AutoDoc scans via the \texttt{scan{\textunderscore}dirs} option. The following example illustrates this by instructing \textsf{AutoDoc} to only search in the subdirectory \texttt{package{\textunderscore}sources} of the packages root directory.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "AutoDoc" );
  AutoDoc( rec( gapdoc := rec( scan_dirs := [ "package_sources" ] ) ) );
\end{Verbatim}
You can also specify an explicit list of files containing documentation, which
will be searched in addition to any files located within the scan directories:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "AutoDoc" );
  AutoDoc( rec( gapdoc := rec( files := [ "path/to/some/hidden/file.gds" ] ) ) );
\end{Verbatim}
Giving such a file does not prevent the standard \texttt{scan{\textunderscore}dirs} from being scanned for other files.

Next, \textsf{GAPDoc} supports the documentation to be built with relative paths. This means, links
to manuals of other packages or the \textsf{GAP} library will not be absolute, but relative from your documentation. This can
be particularly useful if you want to build a release tarball or move your \textsf{GAP} installation around later. Suppose you are starting \textsf{GAP} in the root path of your package as always, and the standard call of \texttt{AutoDoc} (\ref{AutoDoc}) will then build the documentation in the \texttt{doc} subdirectory of your package. From this directory, the gap root directory has
the relative path \texttt{../../..}. Then you can enable the relative paths by
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "AutoDoc" );
  AutoDoc( rec( gapdoc := rec( gap_root_relative_path := "../../.." ) ) );
\end{Verbatim}
or, since \texttt{../../..} is the standard option for \texttt{gap{\textunderscore}root{\textunderscore}relative{\textunderscore}path}, by
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "AutoDoc" );
  AutoDoc( rec( gapdoc := rec( gap_root_relative_path := true ) ) );
\end{Verbatim}
}

\subsection{\textcolor{Chapter }{ Checklist for converting an existing \textsf{GAPDoc} manual to use \textsf{AutoDoc} }}\label{Tut:Checklist}
\logpage{[ 1, 3, 3 ]}
\hyperdef{L}{X83448D91868D7994}{}
{
  Here is a checklist for authors of a package \textsf{PackageName}, \emph{which already has a \textsf{GAPDoc} based manual}, who wish to use \textsf{AutoDoc} to build the manual from now on. We assume that the manual is currently built
by reading a file \texttt{makedoc.g} and that the main \texttt{.xml} file is named \texttt{manual.xml}.

The files \texttt{PackageInfo.g}, \texttt{makedoc.g}, \texttt{doc/title.xml} and \texttt{doc/PackageName.xml} (if it exists) will be altered by this procedure, so it may be wise to keep
backup copies.

You should have copies of the \textsf{AutoDoc} files \texttt{PackageInfo.g} and \texttt{makedoc.g} to hand when reading these instructions.

\begin{itemize}
\item  Copy \texttt{AutoDoc/makedoc.g} to \texttt{PackageName/makedoc.g}.
\item  Edit \texttt{PackageName/makedoc.g} as follows.
\begin{itemize}
\item  Change the header comment to match other files in your package.
\item  After \texttt{LoadPackage("AutoDoc");} add \texttt{LoadPackage("PackageName");}.
\item  In the \texttt{AutoDoc} record delete \texttt{autodoc := true;}.
\item  \index{Scaffold record in makedoc.g@} In the \texttt{scaffold} record change the \texttt{includes} list to be the list of your \texttt{.xml} files that are contained in \texttt{manual.xml}.
\item  \index{Bibliography field in makedoc.g@} If you do not have a bibliography you may delete the \texttt{bib := "bib.xml",} field in the scaffold. Otherwise, edit the file name if you have a different
file. If you only have a \texttt{.bib} file (\texttt{manual.bib} or \texttt{bib.xml.bib} say) you should rename this file \texttt{PackageName.bib}.
\item  \index{LaTeXOptions record in makedoc.g@} In the \texttt{LaTeXOptions} record, which is in the \texttt{gapdoc} record, enter any {\LaTeX} \texttt{newcommands} previously in \texttt{manual.xml}. (If there are none you may safely delete this record.) To illustrate this
option, the \textsf{AutoDoc} file \texttt{makedoc.g} defines the command \texttt{\texttt{\symbol{92}}bbZ} by \texttt{\texttt{\symbol{92}}newcommand\texttt{\symbol{123}}\texttt{\symbol{92}}bbZ\texttt{\symbol{125}}\texttt{\symbol{123}}\texttt{\symbol{92}}mathbb\texttt{\symbol{123}}Z\texttt{\symbol{125}}\texttt{\symbol{125}}}, which may be used to produce the {\LaTeX} formula $f : \bbZ^2 \to \bbZ$. However, note that this only works in the PDF version of the file.
\end{itemize}

\item  Now edit \texttt{PackageName/PackageInfo.g} as follows.
\begin{itemize}
\item  Delete any \texttt{PKGVERSIONDATA} chunk that may be there. One reason for converting your manual to use \textsf{AutoDoc} is to stop using entities such as \texttt{PACKAGENAMEVERSION}.
\item  Copy the \texttt{AutoDoc} record from \texttt{AutoDoc/PackageInfo.g} to the end of your file (just before the final \texttt{"));"}.
\item  \index{Copyright field in PackageInfo.g@} \index{Abstract field in PackageInfo.g@} \index{Acknowledgements field in PackageInfo.g@} Replace the \texttt{Copyright}, \texttt{Abstract} and \texttt{Acknowledgements} fields of the \texttt{TitlePage} record with the corresponding material from your \texttt{manual.xml}. (If you do not have an abstract, then delete the \texttt{Abstract} field, etc.)
\item  \index{Entities record in makedoc.g@} In the \texttt{entities} record enter any entities previously stored in your \texttt{manual.xml}. (Again, if you have none, you may safely delete this record.) To illustrate
this option the \textsf{AutoDoc} file \texttt{PackageInfo.g} defines entities for the names of packages \textsf{io} and \textsf{PackageName}.
\end{itemize}

\item  If you are using a GitHub repository, as well as running "\texttt{git add}" on files \texttt{makedoc.g}, \texttt{PackageInfo.g} and \texttt{doc/PackageName.bib}, you should run "\texttt{git rm \texttt{\symbol{45}}f}" on files \texttt{doc/manual.xml}, and \texttt{doc/title.xml}.
\end{itemize}
You should now be ready to run \textsf{GAP} and \texttt{Read("makedoc.g");} in your package root directory. }

}

\section{\textcolor{Chapter }{Scaffolds}}\label{Tut:Scaffolds}
\logpage{[ 1, 4, 0 ]}
\hyperdef{L}{X8524193D824CDE0D}{}
{

\subsection{\textcolor{Chapter }{Generating a title page}}\label{Tut:Scaffolds:Title}
\logpage{[ 1, 4, 1 ]}
\hyperdef{L}{X7CF22DE28478316F}{}
{
  For most (if not all) \textsf{GAP} packages, the title page of the package manual lists information such as the
release date, version, names and contact details of the authors, and so on.
All this data is also contained in your \texttt{PackageInfo.g}, and whenever you make a change to that file, there is a risk that you forget
to update your manual to match. And even if you don't forget it, you of course
have to spend some time to adjust the manual. \textsf{GAPDoc} can help to a degree with this via entities. Thus, you will sometimes see code
like this in \texttt{PackageInfo.g} files:
\begin{Verbatim}[commandchars=@|B,fontsize=\small,frame=single,label=]
  Version        := "1.2.3",
  Date           := "20/01/2015",
  ##  <#GAPDoc Label="PKGVERSIONDATA">
  ##  <!ENTITY VERSION "1.2.3">
  ##  <!ENTITY RELEASEDATE "20 January 2015">
  ##  <!ENTITY RELEASEYEAR "2015">
  ##  <#/GAPDoc>
\end{Verbatim}
However, it is still easy to forget both of these versions. And it doesn't
solve the problem of updating package authors addresses. Neither of these is a
big issue, of course, but there have been plenty examples in the past where
people forget either of these two things, and it can be slightly embarrassing.
It may even require you to make a new release just to fix the issue, which in
our opinion is a sad waste of your valuable time.

So instead of worrying about manually synchronising these things, you can
instruct \textsf{AutoDoc} to generate a title page for your manual based on the information in your \texttt{PackageInfo.g}. The following commands do just that (in addition to building your manual),
by generating a file called \texttt{doc/title.xml}.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "AutoDoc" );
  AutoDoc( rec( scaffold := rec( MainPage := false ) ) );
\end{Verbatim}
Note that this only outputs \texttt{doc/title.xml} but does not touch any other files of your documentation. In particular, you
need to explicitly include \texttt{doc/title.xml} from your main XML file.

However, you can also tell \textsf{AutoDoc} to maintain the main XML file for you, in which case this is automatic. In
fact, this is the default if you enable scaffolding; the above example command
explicitly told \textsf{AutoDoc} not to generate a main page. }

\subsection{\textcolor{Chapter }{Generating the main XML file}}\label{Tut:Scaffolds:Main}
\logpage{[ 1, 4, 2 ]}
\hyperdef{L}{X7CD72CC780874FD5}{}
{
  The following generates a main XML file for your documentation in addition to
the title page. The main XML file includes the title page by default, as well
as any documentation generated from \textsf{AutoDoc} documentation comments.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "AutoDoc" );
  AutoDoc( rec( scaffold := true ) );
\end{Verbatim}
You can instruct \textsf{AutoDoc} to include additional XML files by giving it a list of filenames, as in the
following example:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "AutoDoc" );
  AutoDoc(rec(
      scaffold := rec(
          includes := [ "somefile.xml", "anotherfile.xml" ]
      )
  ));
\end{Verbatim}
For more information, please consult the documentation of the \texttt{AutoDoc} (\ref{AutoDoc}) function. }

\subsection{\textcolor{Chapter }{What data is used from \texttt{PackageInfo.g}?}}\label{Tut:PackageInfo}
\logpage{[ 1, 4, 3 ]}
\hyperdef{L}{X799956EA85D3FC15}{}
{
  \textsf{AutoDoc} can use data from \texttt{PackageInfo.g} in order to generate a title page. Specifically, the following components of
the package info record are taken into account:
\begin{description}
\item[{PackageName}]  This is used to set the \texttt{{\textless}Title{\textgreater}} element of the title page.
\item[{Subtitle}]  This is used to set the \texttt{{\textless}Subtitle{\textgreater}} element of the title page.
\item[{Version}]  This is used to set the \texttt{{\textless}Version{\textgreater}} element of the title page, with the string ``Version '' prepended.
\item[{Date}]  This is used to set the \texttt{{\textless}Date{\textgreater}} element of the title page.
\item[{Persons}]  This is used to generate \texttt{{\textless}Author{\textgreater}} elements in the generated title page.
\item[{PackageDoc}]  This is a record (or a list of records) which is used to tell the \textsf{GAP} help system about the package manual. Currently \textsf{AutoDoc} extracts the value of the \texttt{PackageDoc.BookName} component and then passes that on to \textsf{GAPDoc} when creating the HTML, PDF and text versions of the manual.
\item[{AutoDoc}]  This is a record which can be used to control the scaffolding performed by \textsf{AutoDoc}, specifically to provide extra information for the title page. For example,
you can set \texttt{AutoDoc.TitlePage.Copyright} to a string which will then be inserted on the generated title page. Using
this method you can customize the following title page elements: \texttt{TitleComment}, \texttt{Abstract}, \texttt{Copyright}, \texttt{Acknowledgements} and \texttt{Colophon}.

Note that \texttt{AutoDoc.TitlePage} behaves exactly the same as the \texttt{scaffold.TitlePage} parameter of the \texttt{AutoDoc} (\ref{AutoDoc}) function.
\end{description}
}

}

\section{\textcolor{Chapter }{AutoDoc worksheets}}\label{Tut:AutoDocWorksheet}
\logpage{[ 1, 5, 0 ]}
\hyperdef{L}{X80ED3C2A78146AD1}{}
{
  \textsf{AutoDoc} worksheets can be used to create HTML and PDF documents using AutoDoc syntax
and possibly including \textsf{GAP} examples and implementations without having them associated to a package. A
file for a worksheet could look like this:
\begin{Verbatim}[commandchars=|DF,fontsize=\small,frame=single,label=]
  #! @Title My first worksheet
  #! @Author Charlie Brown

  #! @Chapter Some groups

  #! @BeginExample
  S3 := SymmetricGroup( 3 );;
  S4 := SymmetricGroup( 4 );;
  #! @EndExample
\end{Verbatim}
Now, one can create a PDF and HTML document, like a package documentation out
of it. Suppose the document above is saved as \texttt{worksheet.g}. Then, when \textsf{GAP} is started in the directory of this file, the command
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  AutoDocWorksheet( "worksheet.g" );
\end{Verbatim}
will create a subdirectory called \texttt{doc} of the current directory in which it will create the documentation. There are
several options to configure the output of the worksheet command, which are
identical to the options of the \texttt{AutoDoc} (\ref{AutoDoc}) command. It is even possible to test the examples in the worksheet using the \texttt{extract{\textunderscore}examples} option of the \texttt{AutoDoc} (\ref{AutoDoc}) command.

Since the worksheets do not have a \texttt{PackageInfo.g} to extract information, all possible tags that \textsf{GAPDoc} supports for the title page can be set into the document. A fully typed title
page can look like this:
\begin{Verbatim}[commandchars=|FH,fontsize=\small,frame=single,label=]
  #! @Title My first worksheet
  #! @Subtitle Some small examples
  #! @Author Charlie Brown

  #! @Version 0.1
  #! @TitleComment Some worksheet
  #! @Date 01/01/2016
  #! @Address TU Kaiserslautern
  #! @Abstract
  #!  A worksheet showing some small examples about groups.
  #! @Copyright 2016 Charlie Brown
  #! @Acknowledgements Woodstock
  #! @Colophon Some colophon

  #! @Chapter Some groups

  #! @BeginExample
  S3 := SymmetricGroup( 3 );;
  S4 := SymmetricGroup( 4 );;
  #! @EndExample
\end{Verbatim}
}

}

\chapter{\textcolor{Chapter }{\textsf{AutoDoc} documentation comments}}\label{Comments}
\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X87668C487B1A2094}{}
{
  You can document declarations of global functions and variables, operations,
attributes etc. by inserting \emph{\textsf{AutoDoc}} comments into your sources before these declaration. An \textsf{AutoDoc} comment always starts with \texttt{\#!}. This is also the smallest possible \textsf{AutoDoc} command. If you want your declaration documented, just write \texttt{\#!} at the line before the documentation. For example:
\begin{Verbatim}[commandchars=@|B,fontsize=\small,frame=single,label=]
  #!
  DeclareOperation( "AnOperation",
                    [ IsList ] );
\end{Verbatim}
This will produce a manual entry for the operation \texttt{AnOperation}.

Inside of \textsf{AutoDoc} comments, \emph{\textsf{AutoDoc} commands} starting with \texttt{@} can be used to control the output \textsf{AutoDoc} produces.
\section{\textcolor{Chapter }{Documenting declarations}}\logpage{[ 2, 1, 0 ]}
\hyperdef{L}{X871482CE838C68F6}{}
{
  In the bare form above, the manual entry for \texttt{AnOperation} will not contain much more than the name of the operation. In order to change
this, there are several commands you can put into the \textsf{AutoDoc} comment before the declaration. Currently, the following commands are
provided:
\subsection{\textcolor{Chapter }{\texttt{@Description \mbox{\texttt{\mdseries\slshape descr}}}}}\label{@Description}
\logpage{[ 2, 1, 1 ]}
\hyperdef{L}{X7F1D85188262A827}{}
{
\index{"@Description@\texttt{"@Description \mbox{\texttt{\mdseries\slshape descr}}}}  Adds the text in the following lines of the \textsf{AutoDoc} to the description of the declaration in the manual. Lines are until the next \textsf{AutoDoc} command or until the declaration is reached. }

\subsection{\textcolor{Chapter }{\texttt{@Returns \mbox{\texttt{\mdseries\slshape ret{\textunderscore}val}}}}}\label{@Returns}
\logpage{[ 2, 1, 2 ]}
\hyperdef{L}{X7DCAB2F87E8FAE90}{}
{
\index{"@Returns@\texttt{"@Returns \mbox{\texttt{\mdseries\slshape ret{\textunderscore}val}}}}  The string \mbox{\texttt{\mdseries\slshape ret{\textunderscore}val}} is added to the documentation, with the text ``Returns: '' put in front of it. This should usually give a brief hint about the type or
meaning of the value returned by the documented function. }

\subsection{\textcolor{Chapter }{\texttt{@Arguments \mbox{\texttt{\mdseries\slshape args}}}}}\label{@Arguments}
\logpage{[ 2, 1, 3 ]}
\hyperdef{L}{X81DAA454857F7971}{}
{
\index{"@Arguments@\texttt{"@Arguments \mbox{\texttt{\mdseries\slshape args}}}}  The string \mbox{\texttt{\mdseries\slshape args}} contains a description of the arguments the function expects, including
optional parts, which are denoted by square brackets. The argument names can
be separated by whitespace, commas or square brackets for the optional
arguments, like ``grp[, elm]'' or ``xx[y[z] ]''. If \textsf{GAP} options are used, this can be followed by a colon : and one or more
assignments, like ``n[, r]: tries := 100''. }

\subsection{\textcolor{Chapter }{\texttt{@Group \mbox{\texttt{\mdseries\slshape grpname}}}}}\label{@Group}
\logpage{[ 2, 1, 4 ]}
\hyperdef{L}{X8677FE8F80C00B14}{}
{
\index{"@Group@\texttt{"@Group \mbox{\texttt{\mdseries\slshape grpname}}}}  Adds the following method to a group with the given name. See section \ref{Groups} for more information about groups. }

\subsection{\textcolor{Chapter }{\texttt{@Label \mbox{\texttt{\mdseries\slshape label}}}}}\label{@Label}
\logpage{[ 2, 1, 5 ]}
\hyperdef{L}{X7B0E20A27D64DF6F}{}
{
\index{"@Label@\texttt{"@Label \mbox{\texttt{\mdseries\slshape label}}}}  Adds label to the function as label. If this is not specified, then for
declarations that involve a list of input filters (as is the case for \texttt{DeclareOperation}, \texttt{DeclareAttribute}, etc.), a default label is generated from this filter list. }

\begin{Verbatim}[commandchars=|BC,fontsize=\small,frame=single,label=]
  #! @Label testlabel
  DeclareProperty( "AProperty",
                   IsObject );
\end{Verbatim}
leads to this:

\subsection{\textcolor{Chapter }{AProperty (testlabel)}}
\logpage{[ 2, 1, 6 ]}\nobreak
\hyperdef{L}{X83B63B847B5199CF}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AProperty({\mdseries\slshape arg})\index{AProperty@\texttt{AProperty}!testlabel}
\label{AProperty:testlabel}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} or \texttt{false}

}

while
\begin{Verbatim}[commandchars=@|B,fontsize=\small,frame=single,label=]
  #!
  DeclareProperty( "AProperty",
                   IsObject );
\end{Verbatim}
leads to this:

\subsection{\textcolor{Chapter }{AProperty (for IsObject)}}
\logpage{[ 2, 1, 7 ]}\nobreak
\hyperdef{L}{X78A9022A7D5CB20E}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AProperty({\mdseries\slshape arg})\index{AProperty@\texttt{AProperty}!for IsObject}
\label{AProperty:for IsObject}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} or \texttt{false}

}

\subsection{\textcolor{Chapter }{\texttt{@ChapterInfo \mbox{\texttt{\mdseries\slshape chapter}}, \mbox{\texttt{\mdseries\slshape section}}}}}\label{@ChapterInfo}
\logpage{[ 2, 1, 8 ]}
\hyperdef{L}{X78938EE37A532FFA}{}
{
\index{"@ChapterInfo@\texttt{"@ChapterInfo}}  Adds the entry to the given chapter and section. Here, \mbox{\texttt{\mdseries\slshape chapter}} and \mbox{\texttt{\mdseries\slshape section}} are the respective titles. }

As an example, a full \textsf{AutoDoc} comment with all options could look like this:
\begin{Verbatim}[commandchars=|EF,fontsize=\small,frame=single,label=]
  #! @Description
  #! Computes the list of lists of degrees of ordinary characters
  #! associated to the $p$-blocks of the group $G$
  #! with $p$-modular character table <A>modtbl</A>
  #! and underlying ordinary character table `ordtbl`.
  #! @Returns a list
  #! @Arguments modtbl
  #! @Group CharacterDegreesOfBlocks
  #! @Label chardegblocks
  #! @ChapterInfo Blocks, Attributes
  DeclareAttribute( "CharacterDegreesOfBlocks",
          IsBrauerTable );
\end{Verbatim}
}

\section{\textcolor{Chapter }{Other documentation comments}}\logpage{[ 2, 2, 0 ]}
\hyperdef{L}{X8152FEF9844B1ACD}{}
{
  There are also some commands which can be used in \textsf{AutoDoc} comments that are not associated to any declaration. This is useful for
additional text in your documentation, examples, mathematical chapters, etc..
\subsection{\textcolor{Chapter }{\texttt{@Chapter \mbox{\texttt{\mdseries\slshape name}}}}}\label{@Chapter}
\logpage{[ 2, 2, 1 ]}
\hyperdef{L}{X823E613385D09F6F}{}
{
\index{"@Chapter@\texttt{"@Chapter}} \index{"@ChapterLabel@\texttt{"@ChapterLabel}} \index{"@ChapterTitle@\texttt{"@ChapterTitle}}  Sets the active chapter, all subsequent functions which do not have an
explicit chapter declared in their \textsf{AutoDoc} comment via \texttt{@ChapterInfo} will be added to this chapter. Also all text comments, i.e. lines that begin
with \#! without a command, and which do not follow after \texttt{@Description}, will be added to the chapter as regular text. Additionally, the chapters
label will be set to \texttt{Chapter{\textunderscore}}\mbox{\texttt{\mdseries\slshape name}}. Example:
\begin{Verbatim}[commandchars=|AB,fontsize=\small,frame=single,label=]
  #! @Chapter My chapter
  #!  This is my chapter.
  #!  I document my stuff in it.
\end{Verbatim}
The \texttt{@ChapterLabel} \mbox{\texttt{\mdseries\slshape label}} command can be used to set the label of the chapter to \texttt{Chapter{\textunderscore}}\mbox{\texttt{\mdseries\slshape label}} instead of \texttt{Chapter{\textunderscore}}\mbox{\texttt{\mdseries\slshape name}}. Additionally, the chapter will be stored as \texttt{{\textunderscore}Chapter{\textunderscore}}\mbox{\texttt{\mdseries\slshape label}}\texttt{.xml}. The \texttt{@ChapterTitle} \mbox{\texttt{\mdseries\slshape title}} command can be used to set a heading for the chapter that is different from \mbox{\texttt{\mdseries\slshape name}}. Note that the title does not affect the label. If you use all three
commands, i.e.,
\begin{Verbatim}[commandchars=|AB,fontsize=\small,frame=single,label=]
  #! @Chapter name
  #! @ChapterLabel label
  #! @ChapterTitle title
\end{Verbatim}
\texttt{title} is used for the headline, \texttt{label} for cross\texttt{\symbol{45}}referencing, and \texttt{name} for setting the same chapter as active chapter again. }

\subsection{\textcolor{Chapter }{\texttt{@Section \mbox{\texttt{\mdseries\slshape name}}}}}\label{@Section}
\logpage{[ 2, 2, 2 ]}
\hyperdef{L}{X78AA98BA7E0635D0}{}
{
\index{"@Section@\texttt{"@Section}} \index{"@SectionLabel@\texttt{"@SectionLabel}} \index{"@SectionTitle@\texttt{"@SectionTitle}}  Sets an active section like \texttt{@Chapter} sets an active chapter. The section automatically ends with the next \texttt{@Section} or \texttt{@Chapter} command.
\begin{Verbatim}[commandchars=|AB,fontsize=\small,frame=single,label=]
  #! @Section My first manual section
  #!  In this section I am going to document my first method.
\end{Verbatim}
The \texttt{@SectionLabel} \mbox{\texttt{\mdseries\slshape label}} command can be used to set the label of the section to \texttt{Section{\textunderscore}}\mbox{\texttt{\mdseries\slshape label}} instead of \texttt{Chapter{\textunderscore}chaptername{\textunderscore}Section{\textunderscore}}\mbox{\texttt{\mdseries\slshape name}}. The \texttt{@SectionTitle} \mbox{\texttt{\mdseries\slshape title}} command can be used to set a heading for the section that is different from \mbox{\texttt{\mdseries\slshape name}}. }

\subsection{\textcolor{Chapter }{\texttt{@Subsection \mbox{\texttt{\mdseries\slshape name}}}}}\label{@Subsection}
\logpage{[ 2, 2, 3 ]}
\hyperdef{L}{X7FD77434802A3580}{}
{
\index{"@Subsection@\texttt{"@Subsection}} \index{"@SubsectionLabel@\texttt{"@SubsectionLabel}} \index{"@SubsectionTitle@\texttt{"@SubsectionTitle}}  Sets an active subsection like \texttt{@Section} sets an active section. The subsection automatically ends with the next \texttt{@Subsection}, \texttt{@Section} or \texttt{@Chapter} command. It also ends with the next documented function. Indeed, internally
each function ``manpage'' is treated like a subsection.
\begin{Verbatim}[commandchars=|AB,fontsize=\small,frame=single,label=]
  #! @Subsection My first manual subsection
  #!  In this subsection I am going to document my first example.
\end{Verbatim}
The \texttt{@SubsectionLabel} \mbox{\texttt{\mdseries\slshape label}} command can be used to set the label of the subsection to \texttt{Subsection{\textunderscore}}\mbox{\texttt{\mdseries\slshape label}} instead of \texttt{Chapter{\textunderscore}chaptername{\textunderscore}Section{\textunderscore}sectionname{\textunderscore}Subsection{\textunderscore}}\mbox{\texttt{\mdseries\slshape name}}. The \texttt{@SubsectionTitle} \mbox{\texttt{\mdseries\slshape title}} command can be used to set a heading for the subsection that is different from \mbox{\texttt{\mdseries\slshape name}}. }

\subsection{\textcolor{Chapter }{\texttt{@BeginGroup \mbox{\texttt{\mdseries\slshape [grpname]}}}}}\label{@BeginGroup}
\logpage{[ 2, 2, 4 ]}
\hyperdef{L}{X7D3060C17EDBCED1}{}
{
\index{"@BeginGroup@\texttt{"@BeginGroup}}  Starts a group. All following documented declarations without an explicit \texttt{@Group} command are grouped together in the same group with the given name. If no name
is given, then a new nameless group is generated. The effect of this command
is ended when an \texttt{@EndGroup} command is reached.

See section \ref{Groups} for more information about groups. }

\subsection{\textcolor{Chapter }{\texttt{@EndGroup}}}\label{@EndGroup}
\logpage{[ 2, 2, 5 ]}
\hyperdef{L}{X7C17EB007FD42C87}{}
{
\index{"@EndGroup@\texttt{"@EndGroup}}  Ends the current group.
\begin{Verbatim}[commandchars=|CF,fontsize=\small,frame=single,label=]
  #! @BeginGroup MyGroup
  #!
  DeclareAttribute( "GroupedAttribute",
                    IsList );

  DeclareOperation( "NonGroupedOperation",
                    [ IsObject ] );

  #!
  DeclareOperation( "GroupedOperation",
                    [ IsList, IsRubbish ] );
  #! @EndGroup
\end{Verbatim}
}

\subsection{\textcolor{Chapter }{@GroupTitle \mbox{\texttt{\mdseries\slshape title}}}}\label{@GroupTitle}
\logpage{[ 2, 2, 6 ]}
\hyperdef{L}{X82FB96F37FAE8167}{}
{
\index{"@GroupTitle@\texttt{"@GroupTitle}}  Sets the subsection heading for the current group to \mbox{\texttt{\mdseries\slshape title}}. In the absence of any \texttt{@GroupTitle} command, the heading will be the name of the first entry in the group. See \ref{Groups} for more information. }

\subsection{\textcolor{Chapter }{\texttt{@Level \mbox{\texttt{\mdseries\slshape lvl}}}}}\label{@Level}
\logpage{[ 2, 2, 7 ]}
\hyperdef{L}{X7BF81EAF80D1A4B5}{}
{
\index{"@Level@\texttt{"@Level}}  Sets the current level of the documentation. All items created after this,
chapters, sections, and items, are given the level \mbox{\texttt{\mdseries\slshape lvl}}, until the \texttt{@ResetLevel} command resets the level to 0 or another level is set.

See section \ref{Level} for more information about levels. }

\subsection{\textcolor{Chapter }{\texttt{@ResetLevel}}}\label{@ResetLevel}
\logpage{[ 2, 2, 8 ]}
\hyperdef{L}{X7C6723D57F424215}{}
{
\index{"@ResetLevel@\texttt{"@ResetLevel}}  Resets the current level to 0.

}

\subsection{\textcolor{Chapter }{\texttt{@BeginExample} and \texttt{@EndExample}}}\label{@BeginExample}
\logpage{[ 2, 2, 9 ]}
\hyperdef{L}{X83D6DA3B83D3436C}{}
{
\index{"@BeginExample@\texttt{"@BeginExample}} \index{"@EndExample@\texttt{"@EndExample}}  \texttt{@BeginExample} marks the start of an example to be put into the manual. It differs from \textsf{GAPDoc}'s \texttt{{\textless}Example{\textgreater}} (see (\textbf{GAPDoc: Log})), in that it expects actual code (not in a comment) interspersed with
comments, to allow for examples files that can be both executed by \textsf{GAP}, and parsed by \textsf{AutoDoc}. To achieve this, \textsf{GAP} commands are not preceded by a comment, while output has to be preceded by an \textsf{AutoDoc} comment. The \texttt{gap{\textgreater}} prompt for the display in the manual is added by \textsf{AutoDoc}. \texttt{@EndExample} ends the example block.

To illustrate this command, consider this input:
\begin{Verbatim}[commandchars=|AC,fontsize=\small,frame=single,label=]
  #! @BeginExample
  S5 := SymmetricGroup(5);
  #! Sym( [ 1 .. 5 ] )
  Order(S5);
  #! 120
  #! @EndExample
\end{Verbatim}
This results in the following output:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@S5 := SymmetricGroup(5);|
  Sym( [ 1 .. 5 ] )
  !gapprompt@gap>| !gapinput@Order(S5);|
  120
\end{Verbatim}
The \textsf{AutoDoc} command \texttt{@Example} is an alias of \texttt{@BeginExample}. }

\subsection{\textcolor{Chapter }{\texttt{@BeginExampleSession} and \texttt{@EndExampleSession}}}\label{@BeginExampleSession}
\logpage{[ 2, 2, 10 ]}
\hyperdef{L}{X861E2E778510CAF7}{}
{
\index{"@BeginExampleSession@\texttt{"@BeginExampleSession}} \index{"@EndExampleSession@\texttt{"@EndExampleSession}}  \texttt{@BeginExampleSession} marks the start of an example to be put into the manual, while \texttt{@EndExampleSession} ends the example block. It is the direct analog of \textsf{GAPDoc}'s \texttt{{\textless}Example{\textgreater}} (see (\textbf{GAPDoc: Log})).

To illustrate this command, consider this input:
\begin{Verbatim}[commandchars=|AC,fontsize=\small,frame=single,label=]
  #! @BeginExampleSession
  #! gap> S5 := SymmetricGroup(5);
  #! Sym( [ 1 .. 5 ] )
  #! gap> Order(S5);
  #! 120
  #! @EndExampleSession
\end{Verbatim}
This results in the following output:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@S5 := SymmetricGroup(5);|
  Sym( [ 1 .. 5 ] )
  !gapprompt@gap>| !gapinput@Order(S5);|
  120
\end{Verbatim}
It inserts an example into the manual just as \texttt{@Example} would do, but all lines are commented and therefore not executed when the file
is read. All lines that should be part of the example displayed in the manual
have to start with an \textsf{AutoDoc} comment (\texttt{\#!}). The comment will be removed, and, if the following character is a space,
this space will also be removed. There is never more than one space removed.
To ensure examples are correctly colored in the manual, there should be
exactly one space between \texttt{\#!} and the \texttt{gap{\textgreater}} prompt. The \textsf{AutoDoc} command \texttt{@ExampleSession} is an alias of \texttt{@BeginExampleSession}. }

\subsection{\textcolor{Chapter }{\texttt{@BeginLog} and \texttt{@EndLog}}}\label{@BeginLog}
\logpage{[ 2, 2, 11 ]}
\hyperdef{L}{X81A2D44D834C0A17}{}
{
\index{"@BeginLog@\texttt{"@BeginLog}} \index{"@EndLog@\texttt{"@EndLog}}  Works just like the \texttt{@BeginExample} command, but the example will not be tested. See the \textsf{GAPDoc} manual for more information. The \textsf{AutoDoc} command \texttt{@Log} is an alias of \texttt{@BeginLog}. }

\subsection{\textcolor{Chapter }{\texttt{@BeginLogSession} and \texttt{@EndLogSession}}}\label{@BeginLogSession}
\logpage{[ 2, 2, 12 ]}
\hyperdef{L}{X7BADE876794FF309}{}
{
\index{"@BeginLogSession@\texttt{"@BeginLogSession}} \index{"@EndLogSession@\texttt{"@EndLogSession}}  Works just like the \texttt{@BeginExampleSession} command, but the example will not be tested if manual examples are run. It is
the direct analog of \textsf{GAPDoc}'s \texttt{{\textless}Log{\textgreater}} (see (\textbf{GAPDoc: Log})). The \textsf{AutoDoc} command \texttt{@LogSession} is an alias of \texttt{@BeginLogSession}. }

\subsection{\textcolor{Chapter }{\texttt{@DoNotReadRestOfFile}}}\label{@DoNotReadRestOfFile}
\logpage{[ 2, 2, 13 ]}
\hyperdef{L}{X78DC644E8519280C}{}
{
\index{"@DoNotReadRestOfFile@\texttt{"@DoNotReadRestOfFile}}  Prevents the rest of the file from being read by the parser. Useful for
unfinished or temporary files.
\begin{Verbatim}[commandchars=|AB,fontsize=\small,frame=single,label=]
  #! This will appear in the manual

  #! @DoNotReadRestOfFile

  #! This will not appear in the manual.
\end{Verbatim}
}

\subsection{\textcolor{Chapter }{\texttt{@BeginChunk \mbox{\texttt{\mdseries\slshape name}}}, \texttt{@EndChunk}, and \texttt{@InsertChunk \mbox{\texttt{\mdseries\slshape name}}}}}\label{@BeginChunk}
\logpage{[ 2, 2, 14 ]}
\hyperdef{L}{X83C01F9B7FA1C973}{}
{
\index{"@BeginChunk@\texttt{"@BeginChunk \mbox{\texttt{\mdseries\slshape name}}}} \index{"@EndChunk@\texttt{"@EndChunk}} \index{"@EndChunk@\texttt{"@InsertChunk \mbox{\texttt{\mdseries\slshape name}}}}  Text inside a \texttt{@BeginChunk} / \texttt{@EndChunk} part will not be inserted into the final documentation directly. Instead, the
text is stored in an internal buffer. That chunk of text can then later on be
inserted in any other place by using the \texttt{@InsertChunk \mbox{\texttt{\mdseries\slshape name}}} command. If you do not provide an \texttt{@EndChunk}, the chunk ends at the end of the file.
\begin{Verbatim}[commandchars=|AD,fontsize=\small,frame=single,label=]
  #! @BeginChunk MyChunk
  #! Hello, world.
  #! @EndChunk

  #! @InsertChunk MyChunk
  ## The text "Hello, world." is inserted right before this.
\end{Verbatim}
You can use this to define an example like this in one file:
\begin{Verbatim}[commandchars=|AD,fontsize=\small,frame=single,label=]
  #! @BeginChunk Example_Symmetric_Group
  #! @BeginExample
  S5 := SymmetricGroup(5);
  #! Sym( [ 1 .. 5 ] )
  Order(S5);
  #! 120
  #! @EndExample
  #! @EndChunk
\end{Verbatim}
And then later, insert the example in a different file, like this:
\begin{Verbatim}[commandchars=|AB,fontsize=\small,frame=single,label=]
  #! @InsertChunk Example_Symmetric_Group
\end{Verbatim}
}

\subsection{\textcolor{Chapter }{\texttt{@BeginCode \mbox{\texttt{\mdseries\slshape name}}}, @EndCode, and \texttt{@InsertCode \mbox{\texttt{\mdseries\slshape name}}}}}\label{@BeginCode}
\logpage{[ 2, 2, 15 ]}
\hyperdef{L}{X7D3671AF86B995B9}{}
{
\index{"@BeginCode@\texttt{"@BeginCode \mbox{\texttt{\mdseries\slshape name}}}} \index{"@EndCode@\texttt{"@EndCode}} \index{"@InsertCode@\texttt{"@InsertCode \mbox{\texttt{\mdseries\slshape name}}}}  Inserts the text between \texttt{@BeginCode} and \texttt{@EndCode} verbatim at the point where \texttt{@InsertCode} is called. This is useful to insert code excerpts directly into the manual.
\begin{Verbatim}[commandchars=|AD,fontsize=\small,frame=single,label=]
  #! @BeginCode Increment
  i := i + 1;
  #! @EndCode

  #! @InsertCode Increment
  ## Code is inserted here.
\end{Verbatim}
}

\subsection{\textcolor{Chapter }{\texttt{@LatexOnly \mbox{\texttt{\mdseries\slshape text}}}, \texttt{@BeginLatexOnly}, and \texttt{@EndLatexOnly}}}\label{@LatexOnly}
\logpage{[ 2, 2, 16 ]}
\hyperdef{L}{X8033B34F80A12A10}{}
{
\index{"@LatexOnly@\texttt{"@LatexOnly \mbox{\texttt{\mdseries\slshape text}}}} \index{"@BeginLatexOnly@\texttt{"@BeginLatexOnly}} \index{"@EndLatexOnly@\texttt{"@EndLatexOnly}}  Code inserted between \texttt{@BeginLatexOnly} and \texttt{@EndLatexOnly} or after \texttt{@LatexOnly} is only inserted in the PDF version of the manual or worksheet. It can hold
arbitrary {\LaTeX}\texttt{\symbol{45}}commands.
\begin{Verbatim}[commandchars=|AC,fontsize=\small,frame=single,label=]
  #! @BeginLatexOnly
  #! \include{picture.tex}
  #! @EndLatexOnly

  #! @LatexOnly \include{picture.tex}
\end{Verbatim}
}

\subsection{\textcolor{Chapter }{\texttt{@NotLatex \mbox{\texttt{\mdseries\slshape text}}}, \texttt{@BeginNotLatex}, and \texttt{@EndNotLatex}}}\label{@NotLatex}
\logpage{[ 2, 2, 17 ]}
\hyperdef{L}{X7EF303147F1BCC22}{}
{
\index{"@NotLatex@\texttt{"@NotLatex \mbox{\texttt{\mdseries\slshape text}}}} \index{"@BeginNotLatex@\texttt{"@BeginNotLatex}} \index{"@EndNotLatex@\texttt{"@EndNotLatex}}  Code inserted between \texttt{@BeginNotLatex} and \texttt{@EndNotLatex} or after \texttt{@NotLatex} is inserted in the HTML and text versions of the manual or worksheet, but not
in the PDF version.
\begin{Verbatim}[commandchars=|AC,fontsize=\small,frame=single,label=]
  #! @BeginNotLatex
  #! For further information see the PDF version of this manual.
  #! @EndNotLatex

  #! @NotLatex For further information see the PDF version of this manual.
\end{Verbatim}
}

}

\section{\textcolor{Chapter }{Title page commands}}\label{TitlepageCommands}
\logpage{[ 2, 3, 0 ]}
\hyperdef{L}{X841E3AD584F5385C}{}
{
  The following commands can be used to add the corresponding parts to the title
page of the document which generated by \textsf{AutoDoc} if scaffolding is enabled.
\begin{itemize}
\item  \texttt{@Title}
\item  \texttt{@Subtitle}
\item  \texttt{@Version}
\item  \texttt{@TitleComment}
\item  \texttt{@Author}
\item  \texttt{@Date}
\item  \texttt{@Address}
\item  \texttt{@Abstract}
\item  \texttt{@Copyright}
\item  \texttt{@Acknowledgements}
\item  \texttt{@Colophon}
\end{itemize}
Those add the following lines at the corresponding point of the title page.
Please note that many of those things can be (better) extracted from the \texttt{PackageInfo.g}. In case you set some of those, the extracted or in scaffold defined items
will be overwritten. While this is not very useful for documenting packages,
they are necessary for worksheets created with \texttt{AutoDocWorksheet} (\ref{AutoDocWorksheet}), since worksheets do not have a \texttt{PackageInfo.g} file from which this information could be extracted. }

\section{\textcolor{Chapter }{Plain text files}}\label{PlainText}
\logpage{[ 2, 4, 0 ]}
\hyperdef{L}{X828AE38F80CB02E7}{}
{
  Files that have the suffix \texttt{.autodoc} and are listed in the \texttt{autodoc.files} option of \texttt{AutoDoc} (\ref{AutoDoc}), resp. are contained in one of the directories listed in \texttt{autodoc.scan{\textunderscore}dirs}, are treated as \textsf{AutoDoc} plain text files. These work exactly like \textsf{AutoDoc} comments, except that lines do not need to (and in fact, should not) start
with \texttt{\#!}. }

\section{\textcolor{Chapter }{Grouping}}\label{Groups}
\logpage{[ 2, 5, 0 ]}
\hyperdef{L}{X7D7A38F87BC40C48}{}
{
  In \textsf{GAPDoc}, it is possible to make groups of manual items, i.e., when documenting a
function, operation, etc., it is possible to group them into suitable chunks.
This can be particularly useful if there are several definitions of an
operation with several different argument types, all doing more or less the
same to the arguments. Then their manual items can be grouped, sharing the
same description and return type information. You can give a heading to the
group in the manual with the \texttt{@GroupTitle} command; if that is not supplied, then the heading of the first manual item in
the group will be used as the heading.

Note that group names are globally unique throughout the whole manual. That
is, groups with the same name are in fact merged into a single group, even if
they were declared in different source files. Thus you can have multiple \texttt{@BeginGroup} / \texttt{@EndGroup} pairs using the same group name, in different places, and these all will refer
to the same group.

Moreover, this means that you can add items to a group via the \texttt{@Group} command in the \textsf{AutoDoc} comment of an arbitrary declaration, at any time.

The following code
\begin{Verbatim}[commandchars=|CH,fontsize=\small,frame=single,label=]
  #! @BeginGroup Group1
  #! @GroupTitle A family of operations

  #! @Description
  #!  First sentence.
  DeclareOperation( "FirstOperation", [ IsInt ] );

  #! @Description
  #!  Second sentence.
  DeclareOperation( "SecondOperation", [ IsInt, IsGroup ] );

  #! @EndGroup

  ## .. Stuff ..

  #! @Description
  #!  Third sentence.
  #! @Group Group1
  KeyDependentOperation( "ThirdOperation", IsGroup, IsInt, "prime );
\end{Verbatim}
produces the following:
\subsection{\textcolor{Chapter }{A family of operations}}\label{Group1}
\logpage{[ 2, 5, 1 ]}
\hyperdef{L}{X79BF060F8436C586}{}
{
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{FirstOperation({\mdseries\slshape arg})\index{FirstOperation@\texttt{FirstOperation}!for IsInt}
\label{FirstOperation:for IsInt}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SecondOperation({\mdseries\slshape arg1, arg2})\index{SecondOperation@\texttt{SecondOperation}!for IsInt, IsGroup}
\label{SecondOperation:for IsInt, IsGroup}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ThirdOperation({\mdseries\slshape arg1, arg2})\index{ThirdOperation@\texttt{ThirdOperation}!for IsGroup, IsInt}
\label{ThirdOperation:for IsGroup, IsInt}
}\hfill{\scriptsize (operation)}}\\

First sentence. Second sentence. Third sentence. }

}

\section{\textcolor{Chapter }{Level}}\label{Level}
\logpage{[ 2, 6, 0 ]}
\hyperdef{L}{X8209AFDE8209AFDE}{}
{
  Levels can be set to not write certain parts in the manual by default. Every
entry has by default the level 0. The command \texttt{@Level} can be used to set the level of the following part to a higher level, for
example 1, and prevent it from being printed to the manual by default.
However, if one sets the level to a higher value in the autodoc option of \textsf{AutoDoc}, the parts will be included in the manual at the specific place.
\begin{Verbatim}[commandchars=|AB,fontsize=\small,frame=single,label=]
  #! This text will be printed to the manual.
  #! @Level 1
  #! This text will be printed to the manual if created with level 1 or higher.
  #! @Level 2
  #! This text will be printed to the manual if created with level 2 or higher.
  #! @ResetLevel
  #! This text will be printed to the manual.
\end{Verbatim}
}

\section{\textcolor{Chapter }{Markdown\texttt{\symbol{45}}like formatting of text in \textsf{AutoDoc}}}\label{MarkdownExtension}
\logpage{[ 2, 7, 0 ]}
\hyperdef{L}{X79558A2F7FE187B4}{}
{
  \textsf{AutoDoc} has some convenient ways to insert special format into text, like math
formulas and lists. The syntax for them are inspired by Markdown and {\LaTeX}, but do not follow them strictly. Neither are all features of the Markdown
language supported. The following subsections describe what is possible.
\subsection{\textcolor{Chapter }{Lists}}\label{MarkdownExtensionList}
\logpage{[ 2, 7, 1 ]}
\hyperdef{L}{X7B256AE5780F140A}{}
{
  One can create lists of items by beginning a new line with *, +,
\texttt{\symbol{45}}, followed by one space. The first item starts the list.
When items are longer than one line, the following lines have to be indented
by at least two spaces. The list ends when a line which does not start a new
item is not indented by two spaces. Of course lists can be nested. Here is an
example:
\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=]
  #! The list starts in the next line
  #! * item 1
  #! * item 2
  #!   which is a bit longer
  #!   * and also contains a nested list
  #!   * with two items
  #! * item 3 of the outer list
  #! This does not belong to the list anymore.
\end{Verbatim}
This is the output:\\
The list starts in the next line
\begin{itemize}
\item  item 1
\item  item 2 which is a bit longer
\begin{itemize}
\item  and also contains a nested list
\item  with two items
\end{itemize}

\item  item 3 of the outer list
\end{itemize}
This does not belong to the list anymore.\\
The *, \texttt{\symbol{45}}, and + are fully interchangeable and can even be
used mixed, but this is not recommended. }

\subsection{\textcolor{Chapter }{Math modes}}\label{MarkdownExtensionMath}
\logpage{[ 2, 7, 2 ]}
\hyperdef{L}{X871412737A0E12E2}{}
{
  One can start an inline formula with a \$, and also end it with \$, just like
in {\LaTeX}. This will translate into \textsf{GAPDoc}s inline math environment. For display mode one can use \$\$, also like {\LaTeX}.
\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=]
  #! This is an inline formula: $1+1 = 2$.
  #! This is a display formula:
  #! $$ \sum_{i=1}^n i. $$
\end{Verbatim}
produces the following output:\\
This is an inline formula: $1+1 = 2$. This is a display formula:
\[ \sum_{i=1}^n i. \]
}

\subsection{\textcolor{Chapter }{Emphasize}}\label{MarkdownExtensionEmph}
\logpage{[ 2, 7, 3 ]}
\hyperdef{L}{X7ED0330479146EFC}{}
{
  One can emphasize text by using two asterisks (**) or two underscores
({\textunderscore}{\textunderscore}) at the beginning and the end of the text
which should be emphasized. Example:
\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=]
  #! **This** is very important.
  #! This is __also important__.
  #! **Naturally, more than one line
  #! can be important.**
\end{Verbatim}
This produces the following output:\\
\emph{This} is very important. This is \emph{also important}. \emph{Naturally, more than one line can be important.} }

\subsection{\textcolor{Chapter }{Inline code}}\label{MarkdownExtensionInlineCode}
\logpage{[ 2, 7, 4 ]}
\hyperdef{L}{X838CCDEB7E0ECEE2}{}
{
  One can mark inline code snippets by using backticks (`) at the beginning and
the end of the text which should be marked as code. Example:
\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=]
  #! Call function `foobar()` at the start.
\end{Verbatim}
This produces the following output:\\
Call function \texttt{foobar()} at the start. }

}

\section{\textcolor{Chapter }{Deprecated commands}}\label{Deprecated}
\logpage{[ 2, 8, 0 ]}
\hyperdef{L}{X78CA9E5C7F494C19}{}
{
  The following commands used to be supported, but are not anymore.
\begin{description}
\item[{\texttt{@EndSection}}] You can simply remove any use of this, \textsf{AutoDoc} ends sections automatically at the start of any new section or chapter.
\item[{\texttt{@EndSubsection}}] You can simply remove any use of this, \textsf{AutoDoc} ends subsections automatically at the start of any new subsection, section or
chapter.
\item[{\texttt{@BeginAutoDoc} and \texttt{@EndAutoDoc}}] It suffices to prepend each declaration that is meant to be appear in the
manual with a minimal \textsf{AutoDoc} comment \texttt{\#!}.
\item[{\texttt{@BeginSystem \mbox{\texttt{\mdseries\slshape name}}}, \texttt{@EndSystem}, and \texttt{@InsertSystem \mbox{\texttt{\mdseries\slshape name}}}}] Please use the chunk commands from subsection \ref{@BeginChunk} instead.
\item[{\texttt{@AutoDocPlainText} and \texttt{@EndAutoDocPlainText}}] Use \texttt{.autodoc} files or \textsf{AutoDoc} comments instead.
\end{description}
}

}


\chapter{\textcolor{Chapter }{AutoDoc worksheets}}\label{Chapter_AutoDoc_worksheets}
\logpage{[ 3, 0, 0 ]}
\hyperdef{L}{X80ED3C2A78146AD1}{}
{

\section{\textcolor{Chapter }{Worksheets}}\label{Chapter_AutoDoc_worksheets_Section_Worksheets}
\logpage{[ 3, 1, 0 ]}
\hyperdef{L}{X801D4A2F8292704C}{}
{


\subsection{\textcolor{Chapter }{AutoDocWorksheet}}
\logpage{[ 3, 1, 1 ]}\nobreak
\hyperdef{L}{X809FE4137C08B28D}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AutoDocWorksheet({\mdseries\slshape list{\textunderscore}of{\textunderscore}filenames: options})\index{AutoDocWorksheet@\texttt{AutoDocWorksheet}}
\label{AutoDocWorksheet}
}\hfill{\scriptsize (function)}}\\

The intention of these function is to create stand\texttt{\symbol{45}}alone
pdf and html files using AutoDoc without having them associated to a package.
It uses the same optional records as the \textsf{AutoDoc} command itself, but instead of a package name there should be a filename or a
list of filenames containing AutoDoc text from which the documents are
created. Please see the \textsf{AutoDoc} command for more information about this and have a look at \ref{Tut:AutoDocWorksheet} for a simple worksheet example. }

}

}


\chapter{\textcolor{Chapter }{AutoDoc}}\label{Chapter_AutoDoc}
\logpage{[ 4, 0, 0 ]}
\hyperdef{L}{X7CBD8AAF7DCEF352}{}
{

\section{\textcolor{Chapter }{The AutoDoc() function}}\label{Chapter_AutoDoc_Section_The_AutoDoc_function}
--> --------------------

--> maximum size reached

--> --------------------

quality94%

¤ Dauer der Verarbeitung: 0.34 Sekunden (vorverarbeitet) ¤

Wurzel

Suchen

Beweissystem der NASA

Beweissystem Isabelle

NIST Cobol Testsuite

Cephes Mathematical Library

Wiener Entwicklungsmethode

Haftungshinweis

Die Informationen auf dieser Webseite wurden nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit, noch Qualität der bereit gestellten Informationen zugesichert.

Bemerkung:

Die farbliche Syntaxdarstellung ist noch experimentell.