% 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  2026.05.11 \mbox{}}\\[1cm]
{ 11 May 2026 \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}}2026 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 }{What \textsf{AutoDoc} offers}}\label{Chapter_Overview}
\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X786190217AE14EBF}{}
{
  

 \textsf{AutoDoc} helps you create and maintain package manuals for \textsf{GAP}. It is built on top of \textsf{GAPDoc} and generates the XML input that \textsf{GAPDoc} consumes. So \textsf{AutoDoc} complements \textsf{GAPDoc} instead of replacing it. 

 The package is designed for a ``mix and match'' workflow: you can adopt only the parts that help you today, and add more over
time. 

 
\section{\textcolor{Chapter }{Core features}}\label{Section_Overview:Features}
\logpage{[ 1, 1, 0 ]}
\hyperdef{L}{X7A835D9779307F98}{}
{
  

 
\begin{itemize}
\item  Build package manuals via one reproducible command, usually \texttt{gap makedoc.g}. 
\item  Generate and maintain a title page from metadata in \texttt{PackageInfo.g}. 
\item  Generate and maintain a main XML file that includes your chapters. 
\item  Extract manual examples into \texttt{.tst} files via \texttt{extract{\textunderscore}examples := true}. 
\item  Document declarations directly in source files via \textsf{AutoDoc} comments beginning with \texttt{\#!}. 
\item  Organize chapter and section text either in source comments or in standalone \texttt{.autodoc} files. 
\item  Combine \textsf{AutoDoc} comments, classic \textsf{GAPDoc} source comments, and hand\texttt{\symbol{45}}written XML chapters in one
manual. 
\end{itemize}
 

 }

 
\section{\textcolor{Chapter }{Adopting \textsf{AutoDoc} incrementally}}\label{Section_Overview:MixAndMatch}
\logpage{[ 1, 2, 0 ]}
\hyperdef{L}{X8081E3BA7B3EC702}{}
{
  

 You do not have to switch everything at once. Typical adoption paths include: 
\begin{itemize}
\item  Use only \texttt{AutoDoc} (\ref{AutoDoc}) to rebuild an existing \textsf{GAPDoc} manual. 
\item  Enable only title\texttt{\symbol{45}}page generation, while keeping your
custom main XML. 
\item  Keep your existing title page but use generated entities such as \texttt{\&VERSION;}, \texttt{\&RELEASEYEAR;}, and \texttt{\&RELEASEDATE;}. 
\item  Add \textsf{AutoDoc} comments only for new code, and leave old documentation
as\texttt{\symbol{45}}is. 
\item  Keep existing XML chapters, or gradually add source comments and \texttt{.autodoc} files where they fit your preferred workflow. 
\item  Later, gradually move chapters or source documentation to your preferred
style. 
\end{itemize}
 

 This flexibility is central: \textsf{AutoDoc} should make your current setup better, without forcing a full rewrite first. 

 }

 
\section{\textcolor{Chapter }{Where to continue}}\label{Section_Overview:WhereNext}
\logpage{[ 1, 3, 0 ]}
\hyperdef{L}{X83D6D8B481C07CD8}{}
{
  

 For practical setup and migration workflows, continue with chapter \ref{Chapter_Tutorials}. For the command reference of documentation comments, including standalone \texttt{.autodoc} files, see chapter \ref{Chapter_Comments}. }

 }

   
\chapter{\textcolor{Chapter }{Getting started using \textsf{AutoDoc}}}\label{Chapter_Tutorials}
\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X7A0D7AA484F466E1}{}
{
  

 This chapter gives practical workflows for adding \textsf{AutoDoc} to a package. For a high\texttt{\symbol{45}}level feature overview and
adoption strategy, see chapter \ref{Chapter_Overview}. 

 
\section{\textcolor{Chapter }{Choose your workflow}}\label{Section_Tut:ChooseWorkflow}
\logpage{[ 2, 1, 0 ]}
\hyperdef{L}{X7BEF736283D2A7A9}{}
{
  

 You can use \textsf{AutoDoc} in several ways, and it is fine to combine them: 
\begin{itemize}
\item  Start a new package manual from scratch (Section \ref{Section_Tut:Scratch}). 
\item  Integrate \textsf{AutoDoc} into an existing \textsf{GAPDoc} manual (Section \ref{Section_Tut:IntegrateExisting}). 
\item  Use only selected features, such as title\texttt{\symbol{45}}page generation
or example extraction, while keeping everything else unchanged. 
\end{itemize}
 

 This incremental approach is encouraged: start with the smallest helpful step,
then adopt additional features when useful. }

 
\section{\textcolor{Chapter }{Creating a package manual from scratch}}\label{Section_Tut:Scratch}
\logpage{[ 2, 2, 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: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "AutoDoc" );
  AutoDoc( rec( scaffold := true ) );
\end{Verbatim}
 When called from a file such as \texttt{makedoc.g}, \textsf{AutoDoc} uses the directory containing that file as the package directory. Otherwise,
it falls back to the current directory. In either case it then reads the \texttt{PackageInfo.g} file from that package directory. It extracts information about the package
from it (such as its name and version, see Section \ref{Subsection_Tut:Scaffolds:Title}). It then creates two XML files \texttt{doc/{\textunderscore}main.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{Section_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{Section_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: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  gap makedoc.g
\end{Verbatim}
 

 If you also want regression tests from your manual examples, enable \texttt{extract{\textunderscore}examples := true}; this is explained in Section \ref{Subsection_Tut:IntegrateExisting:EverythingThere}. 

 }

 
\section{\textcolor{Chapter }{Documenting code with \textsf{AutoDoc}}}\label{Section_Tut:AdvancedAutoDoc}
\logpage{[ 2, 3, 0 ]}
\hyperdef{L}{X87A00EED866E22E8}{}
{
  

 \textsf{AutoDoc} supports several equally supported ways to organize your manual text. You can
put chapter and section material directly into \texttt{\#!} comments inside \texttt{.g}, \texttt{.gd}, or \texttt{.gi} files, you can put it into standalone \texttt{.autodoc} files, and you can mix either style with existing \textsf{GAPDoc} XML. Which arrangement is best is mostly a matter of taste and convenience.
The detailed command reference for these styles is in chapter \ref{Chapter_Comments}, especially Section \ref{Section_PlainText}. 

 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: 

 Important: the comment block must be immediately followed by the declaration
it documents. Do not place other code between the comment block and the \texttt{Declare...} statement. 

 
\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}
 

 In these comment lines, you can freely use normal \textsf{GAPDoc} XML markup (with the usual exceptions for lines starting with \texttt{@}, which are interpreted as \textsf{AutoDoc} commands). So, for instance, tags like \texttt{{\textless}Ref{\textgreater}}, \texttt{{\textless}A{\textgreater}}, \texttt{{\textless}K{\textgreater}}, \texttt{{\textless}List{\textgreater}}, etc. can be written directly in \texttt{\#!} comment text. 

 For chapter text, tutorial material, worked examples, and similar prose, some
authors prefer to keep the material next to their code using \texttt{\#! @Chapter}, \texttt{\#! @Section}, and related commands, while others prefer standalone \texttt{.autodoc} files. In an \texttt{.autodoc} file you write the same commands without the \texttt{\#!} prefix, and you list the file in \texttt{autodoc.files} or place it in a directory scanned via \texttt{autodoc.scan{\textunderscore}dirs}. AutoDoc itself still uses the source\texttt{\symbol{45}}comment style in
places, for example in \texttt{gap/Magic.gd}. 

 One caveat applies if you decide to keep prose in a standalone \texttt{.autodoc} file but want to interrupt it with the documentation of a declaration that is
written in source comments. Today that requires the chunk mechanism, and that
workflow is currently limited; see issue \texttt{\#60} in the AutoDoc issue tracker. 

 For a thorough description of what you can do with \textsf{AutoDoc} documentation comments, please refer to chapter \ref{Chapter_Comments}. 

  

  

 Suppose you have not been using \textsf{GAPDoc} before but instead used the process described in section \ref{Section_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 and standalone \texttt{.autodoc} files. 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=]
  &lt;#Include SYSTEM "_AutoDocMainFile.xml">
\end{Verbatim}
 in a suitable place. This means that you can mix \textsf{AutoDoc} documentation comments and \texttt{.autodoc} files 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 then 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{Section_Tut:IntegrateExisting}
\logpage{[ 2, 4, 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, 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}. 

 In particular, this setup works well if you want to keep your existing manual
structure and only adopt selected \textsf{AutoDoc} features first; for example automatic title\texttt{\symbol{45}}page data and
predefined entities such as \texttt{\&VERSION;}, \texttt{\&RELEASEYEAR;} and \texttt{\&RELEASEDATE;} (see Section \ref{Subsection_Tut:PackageInfo:Entities}). 

 
\subsection{\textcolor{Chapter }{Using \textsf{AutoDoc} on a complete \textsf{GAPDoc} manual}}\label{Subsection_Tut:IntegrateExisting:EverythingThere}
\logpage{[ 2, 4, 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}
 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}). 

 If you prefer to keep generated tests in a separate location, set \texttt{extract{\textunderscore}examples.subdir} to a path relative to the package root: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "AutoDoc" );
  AutoDoc( rec( extract_examples := rec( subdir := "tst/generated" ) ) );
\end{Verbatim}
 This writes the extracted examples into \texttt{tst/generated/} instead. 

 }

 
\subsection{\textcolor{Chapter }{Setting different \textsf{GAPDoc} options}}\label{Subsection_Tut:IntegrateExisting:GapDocOptions}
\logpage{[ 2, 4, 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}
 

 \textsf{AutoDoc} can scan directories for documentation input automatically. In fact there are
two separate scanning steps. The option \texttt{autodoc.scan{\textunderscore}dirs} controls where it looks for source comments beginning with \texttt{\#!} and for standalone \texttt{.autodoc} files. By default, it scans the package root directory and the subdirectories \texttt{gap}, \texttt{lib}, \texttt{examples} and \texttt{examples/doc}; the listed subdirectories are scanned recursively, while the package root
itself is only scanned at top level. If you keep that kind of input in other
directories, adjust \texttt{autodoc.scan{\textunderscore}dirs}. The following example instructs \textsf{AutoDoc} to only search in the subdirectory \texttt{package{\textunderscore}sources} of the package's root directory for those files. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "AutoDoc" );
  AutoDoc( rec( autodoc := rec( scan_dirs := [ "package_sources" ] ) ) );
\end{Verbatim}
 The separate option \texttt{gapdoc.scan{\textunderscore}dirs} serves a different purpose: it controls where \textsf{GAPDoc} comments are searched for. 

 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( autodoc := rec( files := [ "path/to/some/hidden/file.gd" ] ) ) );
\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}
 

 The same behavior is also available via the global option \texttt{relativePath}. This is particularly convenient in a short \texttt{makedoc.g} script, and it overrides \texttt{gapdoc.gap{\textunderscore}root{\textunderscore}relative{\textunderscore}path} if both are given. Since this is a GAP global option, you can also set it
outside the eventual \texttt{AutoDoc} (\ref{AutoDoc}) call and let it propagate through nested calls; see  (\textbf{Reference: Options Stack}) for more information about GAP's global options system: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "AutoDoc" );
  AutoDoc( rec( autodoc := true ) : relativePath := "../../.." );
\end{Verbatim}
 If you pass \texttt{relativePath := true}, then \textsf{AutoDoc} uses the default relative path \texttt{../../..}. 

 For example, if your \texttt{makedoc.g} reads the manual via \texttt{AutoDoc} (\ref{AutoDoc}), then the following command sets both \texttt{relativePath} and \texttt{nopdf} to \texttt{true} for that nested call: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  Read( "makedoc.g" : nopdf, relativePath );
\end{Verbatim}
 

 Finally, if you only want HTML and text output, you can suppress PDF
generation with the global option \texttt{nopdf}: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  LoadPackage( "AutoDoc" );
  AutoDoc( rec( autodoc := true ) : nopdf );
\end{Verbatim}
 This is useful if \texttt{pdflatex} is unavailable, or when you want a faster documentation rebuild while editing. 

 You can also request the same behavior from the shell by setting the
environment variable \texttt{NOPDF} before invoking \texttt{makedoc.g}. For example: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  NOPDF=1 gap makedoc.g
\end{Verbatim}
 If \texttt{NOPDF} is set, \textsf{AutoDoc} skips PDF generation even if no \texttt{nopdf} option is given in the GAP code. 

 }

 
\subsection{\textcolor{Chapter }{Checklist for converting an existing \textsf{GAPDoc} manual to use \textsf{AutoDoc}}}\label{Subsection_Tut:Checklist}
\logpage{[ 2, 4, 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/{\textunderscore}main.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{Section_Tut:Scaffolds}
\logpage{[ 2, 5, 0 ]}
\hyperdef{L}{X8524193D824CDE0D}{}
{
  

  

 
\subsection{\textcolor{Chapter }{Generating a title page}}\label{Subsection_Tut:Scaffolds:Title}
\logpage{[ 2, 5, 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{Subsection_Tut:Scaffolds:Main}
\logpage{[ 2, 5, 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{Subsection_Tut:PackageInfo}
\logpage{[ 2, 5, 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 record controls extra settings used by \textsf{AutoDoc} while generating the manual. In particular, \texttt{PkgInfo.AutoDoc.TitlePage} lets you add or override title\texttt{\symbol{45}}page elements coming from
package metadata. 

 Typical fields you may set there include \texttt{TitleComment}, \texttt{Abstract}, \texttt{Copyright}, \texttt{Acknowledgements} and \texttt{Colophon}. For example, in \texttt{PackageInfo.g}: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  SetPackageInfo( rec(
    ...
    AutoDoc := rec(
      TitlePage := rec(
        Copyright := "(C) 2026 Jane Doe",
        Acknowledgements := "Funded by Example Grant 1234."
      )
    )
  ) );
\end{Verbatim}
 This inserts \texttt{{\textless}Copyright{\textgreater}} and \texttt{{\textless}Acknowledgements{\textgreater}} blocks into the generated \texttt{title.xml}. 

 \texttt{PkgInfo.AutoDoc.TitlePage} has exactly the same meaning as \texttt{scaffold.TitlePage} in \texttt{AutoDoc} (\ref{AutoDoc}). The function documentation for \texttt{scaffold.TitlePage} points back to this subsection. 
\end{description}
 

 }

 
\subsection{\textcolor{Chapter }{Entities from \texttt{PackageInfo.g} and scaffold options}}\label{Subsection_Tut:PackageInfo:Entities}
\logpage{[ 2, 5, 4 ]}
\hyperdef{L}{X79EAEF277DD1FAE1}{}
{
  

 Besides title\texttt{\symbol{45}}page fields, you can define custom entities
in \texttt{AutoDoc.entities} inside \texttt{PackageInfo.g}. They are written to \texttt{doc/{\textunderscore}entities.xml}, so they can be used both by generated main files and by
hand\texttt{\symbol{45}}written main XML files. 

 In addition, \textsf{AutoDoc} predefines the entities \texttt{VERSION}, \texttt{RELEASEYEAR} and \texttt{RELEASEDATE}, derived from package metadata. This is useful if you keep a custom title
page or custom chapters and still want release information to stay
synchronized with \texttt{PackageInfo.g}. 

 You can specify scaffold\texttt{\symbol{45}}related settings in \texttt{PackageInfo.g} and in your \texttt{makedoc.g} call at the same time; both records are merged, and values from \texttt{makedoc.g} take precedence when both define the same key. 

 }

 }

 
\section{\textcolor{Chapter }{Worksheets}}\label{Section_Tut:WorksheetsPointer}
\logpage{[ 2, 6, 0 ]}
\hyperdef{L}{X801D4A2F8292704C}{}
{
  

 For stand\texttt{\symbol{45}}alone documents that are not tied to a package,
use \texttt{AutoDocWorksheet} (\ref{AutoDocWorksheet}). Its documentation and examples are in Section \ref{Section_AutoDocWorksheet} of chapter \ref{AutoDoc}. }

 }

   
\chapter{\textcolor{Chapter }{\textsf{AutoDoc} documentation comments}}\label{Chapter_Comments}
\logpage{[ 3, 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 declarations. 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}. 

 For declaration documentation, the associated declaration must appear
immediately after the \textsf{AutoDoc} comment block. In particular, do not insert other code (such as \texttt{if false then} or assignments) between the comment block and the \texttt{Declare...} statement. 

 This also works for \texttt{InstallMethod} and \texttt{InstallOtherMethod}. In that case, \textsf{AutoDoc} uses the installed method's name and filter list to create a manual entry for
the implemented item. 

 Inside of \textsf{AutoDoc} comments, \emph{\textsf{AutoDoc} commands} starting with \texttt{@} can be used to control the output \textsf{AutoDoc} produces. Any comment line that does \emph{not} start with an \textsf{AutoDoc} command is treated as regular documentation text and may contain (almost)
arbitrary \textsf{GAPDoc} XML markup, such as \texttt{{\textless}Ref{\textgreater}}, \texttt{{\textless}A{\textgreater}}, \texttt{{\textless}List{\textgreater}}, and similar tags. This lets you use the normal \textsf{GAPDoc} formatting toolbox directly inside \textsf{AutoDoc} comments. 

 For example: 
\begin{Verbatim}[commandchars=|BE,fontsize=\small,frame=single,label=]
  #! @Description
  #!  See <Ref Chap="Chapter_Tutorials"/> for setup details.
  #!  The argument <A>obj</A> must satisfy <K>IsObject</K>.
\end{Verbatim}
 

 As explained in chapter \ref{Chapter_Overview}, you can combine \textsf{AutoDoc} comments with hand\texttt{\symbol{45}}written XML and classic \textsf{GAPDoc} comments. For practical setup and migration workflows, see chapter \ref{Chapter_Tutorials}. 

 
\section{\textcolor{Chapter }{Documenting declarations}}\label{Chapter_Comments_Section_Documenting_declarations}
\logpage{[ 3, 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{Subsection_@Description}
\logpage{[ 3, 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 val}}}}}\label{Subsection_@Returns}
\logpage{[ 3, 1, 2 ]}
\hyperdef{L}{X7EFF79F47BE24F78}{}
{
  

 \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{Subsection_@Arguments}
\logpage{[ 3, 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''. 

 For \texttt{DeclareGlobalName}, using \texttt{@Arguments} or \texttt{@Returns} also makes \textsf{AutoDoc} document the item as a function. This is useful because \texttt{DeclareGlobalName} itself does not reveal whether the name denotes a function or a variable. 

 }

 
\subsection{\textcolor{Chapter }{\texttt{@ItemType \mbox{\texttt{\mdseries\slshape kind}}}}}\label{Subsection_@ItemType}
\logpage{[ 3, 1, 4 ]}
\hyperdef{L}{X852A9FCA7AB6EC4E}{}
{
  

 \index{"@ItemType@\texttt{"@ItemType \mbox{\texttt{\mdseries\slshape kind}}}} Overrides the kind of manual item created for the following declaration or
installed method. The supported values are \texttt{Attr}, \texttt{Cat}, \texttt{Coll}, \texttt{Constr}, \texttt{Fam}, \texttt{Filt}, \texttt{Func}, \texttt{InfoClass}, \texttt{Meth}, \texttt{Oper}, \texttt{Prop}, \texttt{Repr}, and \texttt{Var}. 

 The values \texttt{Cat}, \texttt{Coll}, and \texttt{Repr} are \textsf{AutoDoc}\texttt{\symbol{45}}specific aliases. They emit \texttt{Filt} entries with the corresponding \textsf{GAPDoc} filter type. 

 This is useful when the source code alone does not determine which manual item
kind should be emitted. For many declarations such as \texttt{DeclareAttribute} or \texttt{DeclareProperty}, \textsf{AutoDoc} already knows the intended type from the declaration itself. 

 It is useful for \texttt{DeclareGlobalName}, because that declaration can refer to either a function or a variable. \textsf{AutoDoc} defaults such entries to \texttt{Var}, but switches to \texttt{Func} as soon as \texttt{@Arguments} or \texttt{@Returns} indicates function\texttt{\symbol{45}}style documentation. You can still use \texttt{@ItemType} to override this explicitly. 

 It is useful for \texttt{DeclareSynonym}, because that declaration can document a function synonym or one of several
filter\texttt{\symbol{45}}like synonyms. Use \texttt{@ItemType Filt}, \texttt{Cat}, \texttt{Coll}, or \texttt{Repr} to control which kind of filter entry should be emitted. 

 For example: 

 
\begin{Verbatim}[commandchars=|AB,fontsize=\small,frame=single,label=]
  #! @ItemType Repr
  DeclareSynonym( "IsSomethingRep", IsComponentObjectRep );
\end{Verbatim}
 

 This makes \textsf{AutoDoc} emit a \texttt{{\textless}Filt Type="Representation" .../{\textgreater}} manual entry. 

 }

 
\subsection{\textcolor{Chapter }{\texttt{@Group \mbox{\texttt{\mdseries\slshape grpname}}}}}\label{Subsection_@Group}
\logpage{[ 3, 1, 5 ]}
\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{Section_Groups} for more information about groups. 

 }

 
\subsection{\textcolor{Chapter }{\texttt{@Label \mbox{\texttt{\mdseries\slshape label}}}}}\label{Subsection_@Label}
\logpage{[ 3, 1, 6 ]}
\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: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  <ManSection>
    <Prop Arg="arg" Name="AProperty" Label="testlabel"/>
   <Returns> <K>true</K> or <K>false</K>
  </Returns>
   <Description>
   </Description>
  </ManSection>
\end{Verbatim}
 while 
\begin{Verbatim}[commandchars=@|B,fontsize=\small,frame=single,label=]
  #!
  DeclareProperty( "AProperty",
                   IsObject );
\end{Verbatim}
 leads to this: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  <ManSection>
    <Prop Arg="arg" Name="AProperty" Label="for IsObject"/>
   <Returns> <K>true</K> or <K>false</K>
  </Returns>
   <Description>
   </Description>
  </ManSection>
\end{Verbatim}
 

 }

 
\subsection{\textcolor{Chapter }{\texttt{@ChapterInfo \mbox{\texttt{\mdseries\slshape chapter}}, \mbox{\texttt{\mdseries\slshape section}}}}}\label{Subsection_@ChapterInfo}
\logpage{[ 3, 1, 7 ]}
\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}}\label{Chapter_Comments_Section_Other_documentation_comments}
\logpage{[ 3, 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{Subsection_@Chapter}
\logpage{[ 3, 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{@Appendix \mbox{\texttt{\mdseries\slshape name}}}}}\label{Subsection_@Appendix}
\logpage{[ 3, 2, 2 ]}
\hyperdef{L}{X83163DA586882825}{}
{
  

 \index{"@Appendix@\texttt{"@Appendix}} This is analogous to \texttt{@Chapter}, but generates \texttt{Appendix} elements instead of \texttt{Chapter} elements. When scaffolding generates the main XML file, appendices created
this way are included automatically after any files listed in \texttt{scaffold.appendix}. 

 Example: 

 
\begin{Verbatim}[commandchars=!|B,fontsize=\small,frame=single,label=]
  @Appendix Supplementary material
  
  @Section Additional tables
\end{Verbatim}
 

 }

 
\subsection{\textcolor{Chapter }{\texttt{@Section \mbox{\texttt{\mdseries\slshape name}}}}}\label{Subsection_@Section}
\logpage{[ 3, 2, 3 ]}
\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_@Subsection}
\logpage{[ 3, 2, 4 ]}
\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{Subsection_@BeginGroup}
\logpage{[ 3, 2, 5 ]}
\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{Section_Groups} for more information about groups. 

 }

 
\subsection{\textcolor{Chapter }{\texttt{@EndGroup}}}\label{Subsection_@EndGroup}
\logpage{[ 3, 2, 6 ]}
\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{Subsection_@GroupTitle}
\logpage{[ 3, 2, 7 ]}
\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{Section_Groups} for more information. 

 }

 
\subsection{\textcolor{Chapter }{\texttt{@BeginExample} and \texttt{@EndExample}}}\label{Subsection_@BeginExample}
\logpage{[ 3, 2, 8 ]}
\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}. If you enable \texttt{extract{\textunderscore}examples := true} when calling \texttt{AutoDoc} (\ref{AutoDoc}), these examples can also be turned into \texttt{.tst} files (see Section \ref{Subsection_Tut:IntegrateExisting:EverythingThere}). 

 }

 
\subsection{\textcolor{Chapter }{\texttt{@BeginExampleSession} and \texttt{@EndExampleSession}}}\label{Subsection_@BeginExampleSession}
\logpage{[ 3, 2, 9 ]}
\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{Subsection_@BeginLog}
\logpage{[ 3, 2, 10 ]}
\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{Subsection_@BeginLogSession}
\logpage{[ 3, 2, 11 ]}
\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{Subsection_@DoNotReadRestOfFile}
\logpage{[ 3, 2, 12 ]}
\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{Subsection_@BeginChunk}
\logpage{[ 3, 2, 13 ]}
\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{Subsection_@BeginCode}
\logpage{[ 3, 2, 14 ]}
\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{Subsection_@LatexOnly}
\logpage{[ 3, 2, 15 ]}
\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{Subsection_@NotLatex}
\logpage{[ 3, 2, 16 ]}
\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}
 

 }

 
\subsection{\textcolor{Chapter }{\texttt{@Index \mbox{\texttt{\mdseries\slshape key}} [\mbox{\texttt{\mdseries\slshape entry text}}]}}}\label{Subsection_@Index}
\logpage{[ 3, 2, 17 ]}
\hyperdef{L}{X82FD2EEB788E76F1}{}
{
  

 \index{"@Index@\texttt{"@Index \mbox{\texttt{\mdseries\slshape key}} [\mbox{\texttt{\mdseries\slshape entry text}}]}} Adds an index entry to the current documentation text. The command \texttt{@Index key entry text} generates \texttt{{\textless}Index Key="key"{\textgreater}entry
text{\textless}/Index{\textgreater}}. If no entry text is provided, then the entry text is empty. To use keys
containing spaces, wrap the key in double quotes, e.g. \texttt{@Index "my key" entry text}. The entry text is processed like normal documentation text, so
markdown\texttt{\symbol{45}}like inline code such as \texttt{true} is supported. 

 }

 }

 
\section{\textcolor{Chapter }{Title page commands}}\label{Section_TitlepageCommands}
\logpage{[ 3, 3, 0 ]}
\hyperdef{L}{X841E3AD584F5385C}{}
{
  

 The following commands can be used to add corresponding parts to the title
page of a document generated by \textsf{AutoDoc}. 
\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}
 Many of these values can (and for package manuals typically should) be
extracted from \texttt{PackageInfo.g}. If you set them explicitly in comments, they override extracted or
scaffold\texttt{\symbol{45}}defined values. This is usually most useful 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{Section_PlainText}
\logpage{[ 3, 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} or one of their subdirectories, are treated as standalone \textsf{AutoDoc} input files. They are meant for manual text that does not belong next to a
single declaration: chapters, sections, tutorials, worked examples, index
entries, chunks, title\texttt{\symbol{45}}page metadata, and similar
prose\texttt{\symbol{45}}heavy material. 

 Conceptually, a \texttt{.autodoc} file uses the same parser as \textsf{AutoDoc} comments, but without the comment marker. In a \texttt{.autodoc} file, lines do not need to start with \texttt{\#!} and in fact usually should not. This makes \texttt{.autodoc} files one convenient way to replace hand\texttt{\symbol{45}}written XML
chapters when you prefer \textsf{AutoDoc}'s command syntax and Markdown\texttt{\symbol{45}}like text features. However,
it is not the only supported style: chapter and section commands inside source
comments remain fully supported, and \textsf{AutoDoc} itself still uses that style in files such as \texttt{gap/Magic.gd}. For the surrounding workflow, see Chapter \ref{Chapter_Tutorials}. 

 The most important difference from declaration comments is that a plain text
file does \emph{not} document a declaration by adjacency. There is no following \texttt{Declare...} or \texttt{InstallMethod} statement for \textsf{AutoDoc} to inspect. So commands whose meaning depends on such a declaration only make
sense in source comments immediately before that declaration. 

 In practice, this gives the following rule of thumb. 

 
\begin{itemize}
\item  Use source comments beginning with \texttt{\#!} to document declarations. This is the mode for \texttt{@Description}, \texttt{@Returns}, \texttt{@Arguments}, \texttt{@Label}, \texttt{@Group}, and \texttt{@ChapterInfo}. 
\item  Use either \texttt{.autodoc} files or source comments for standalone manual structure and prose. Commands
such as \texttt{@Chapter}, \texttt{@Section}, \texttt{@Subsection}, grouping commands, examples and logs, chunks and code insertion, \texttt{@Index}, title\texttt{\symbol{45}}page commands, Markdown\texttt{\symbol{45}}style
headings, fenced code blocks, and ordinary \textsf{GAPDoc} XML markup work in both styles. 
\end{itemize}
 

 As a concrete example, the following file can serve as a complete chapter
written in \texttt{.autodoc} format. 

 
\begin{Verbatim}[commandchars=!|D,fontsize=\small,frame=single,label=]
  @Chapter Test
  @Section First Section
  @Subsection First Subsection
  
  This text belongs directly to the manual chapter.
  It can use XML tags such as <A>arg</A> or <Ref .../>.
  
  @BeginExampleSession
  !gapprompt|gap>D !gapinput|S5 := SymmetricGroup(5);D
  Sym( [ 1 .. 5 ] )
  !gapprompt|gap>D !gapinput|Size(S5);D
  120
  @EndExampleSession
  
  @Index "Worksheet Autoplain" Plain worksheet index entry with `true`
\end{Verbatim}
 

 This is essentially the style used in the worksheet fixture \texttt{tst/worksheets/autoplain.sheet/plain.autodoc}. 

 The same structural commands can also be used inside source comments, for
example: 

 
\begin{Verbatim}[commandchars=|BE,fontsize=\small,frame=single,label=]
  #! @Chapter Reference
  #! @Section The AutoDoc() function
  #! Some introductory text for this section.
\end{Verbatim}
 

 This source\texttt{\symbol{45}}comment style is still fully supported and is
used in \texttt{gap/Magic.gd}. 

 The mixed\texttt{\symbol{45}}workflow case is equally common. Suppose an
existing manual still has a hand\texttt{\symbol{45}}written main XML file and
perhaps some hand\texttt{\symbol{45}}written XML chapters. Then you can keep
those files, include \texttt{{\textunderscore}AutoDocMainFile.xml} from the main XML file as described in Chapter \ref{Chapter_Tutorials}, and add one or more \texttt{.autodoc} files via \texttt{autodoc.files} or \texttt{autodoc.scan{\textunderscore}dirs}. Those files can provide tutorial chapters or appendices, while declaration
documentation continues to live in source comments and older XML chapters
remain unchanged. 

 One caveat is worth keeping in mind. If you want a standalone \texttt{.autodoc} file to pause and resume around declaration documentation that is written in
source comments, the current workaround is to use chunks. That interleaving
workflow is currently limited; see issue \texttt{\#60} in the AutoDoc issue tracker. 

 So, while \texttt{.autodoc} files and source comments share most of the same text syntax, they can be
combined freely. The main distinction is simply that
declaration\texttt{\symbol{45}}bound commands attach metadata to a following
declaration, while standalone manual text can live wherever you find it most
convenient. 

 }

 
\section{\textcolor{Chapter }{Grouping}}\label{Section_Groups}
\logpage{[ 3, 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: 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  <ManSection Label="Group1">
  <Heading>A family of operations</Heading>
    <Oper Arg="arg" Name="FirstOperation" Label="for IsInt"/>
    <Oper Arg="arg1,arg2" Name="SecondOperation" Label="for IsInt, IsGroup"/>
    <Oper Arg="arg1,arg2" Name="ThirdOperation" Label="for IsGroup, IsInt"/>
   <Description>
  First sentence.
  Second sentence.
  Third sentence.
   </Description>
  </ManSection>
\end{Verbatim}
 

 }

 
\section{\textcolor{Chapter }{Markdown\texttt{\symbol{45}}like formatting of text in \textsf{AutoDoc}}}\label{Section_MarkdownExtension}
\logpage{[ 3, 6, 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{Subsection_MarkdownExtensionList}
\logpage{[ 3, 6, 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{Subsection_MarkdownExtensionMath}
\logpage{[ 3, 6, 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{Subsection_MarkdownExtensionEmph}
\logpage{[ 3, 6, 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{Subsection_MarkdownExtensionInlineCode}
\logpage{[ 3, 6, 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. 

 }

 
\subsection{\textcolor{Chapter }{Fenced code blocks}}\label{Subsection_MarkdownExtensionFencedCode}
\logpage{[ 3, 6, 5 ]}
\hyperdef{L}{X7C0629B183765575}{}
{
  

 One can insert verbatim code blocks by placing the code between lines
containing at least three backticks or at least three tildes. The opening
fence may optionally be followed by an info string. The values \texttt{@listing}, \texttt{@example}, and \texttt{@log} select the corresponding GAPDoc element; any other value is currently ignored.
If nothing is specified the default is to generate \texttt{{\textless}Listing{\textgreater}}. Example: 

 
\begin{Verbatim}[commandchars=|AB,fontsize=\small,frame=single,label=]
  #! ```@listing
  #! if x = 2 then
  #!   Print("1 + 1 = 2 holds, all is good\n");
  #! fi;
  #! ```
  #! ~~~@example
  #! gap> [ 1 .. 3 ] ^ 2;
  #! [ 1, 4, 9 ]
  #! ~~~
  #! ```@log
  #! #I  some log message
  #! ```
\end{Verbatim}
 

 This produces the following output:\\
 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  if x = 2 then
    Print("1 + 1 = 2 holds, all is good\n");
  fi;
\end{Verbatim}
 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@[ 1 .. 3 ] ^ 2;|
  [ 1, 4, 9 ]
\end{Verbatim}
 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  #I  some log message
\end{Verbatim}
 

 }

 }

 
\section{\textcolor{Chapter }{Deprecated commands}}\label{Section_Deprecated}
\logpage{[ 3, 7, 0 ]}
\hyperdef{L}{X78CA9E5C7F494C19}{}
{
  

 The following commands used to be supported, but are not supported 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 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{Subsection_@BeginChunk} instead.
\item[{\texttt{@AutoDocPlainText} and \texttt{@EndAutoDocPlainText}}] Use \texttt{.autodoc} files or \textsf{AutoDoc} comments instead.
\end{description}
 }

 }

   
\chapter{\textcolor{Chapter }{Reference}}\label{Chapter_Reference}
\logpage{[ 4, 0, 0 ]}
\hyperdef{L}{X782AAE4E86411FF4}{}
{
  
\section{\textcolor{Chapter }{AutoDoc worksheets}}\label{Section_AutoDocWorksheet}
\logpage{[ 4, 1, 0 ]}
\hyperdef{L}{X80ED3C2A78146AD1}{}
{
  

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


 The purpose of this function is to create stand\texttt{\symbol{45}}alone PDF
and HTML files using \textsf{AutoDoc} without associating them with a package. 

 Instead of a package directory, you pass one filename or a list of filenames
containing \textsf{AutoDoc} text from which the document is created. Settings are supplied via an optional
record using the same entries as the \mbox{\texttt{\mdseries\slshape optrec}} argument of \texttt{AutoDoc} (\ref{AutoDoc}). Alternatively, you may omit \mbox{\texttt{\mdseries\slshape filenames}} and specify the files via \texttt{optrec.autodoc.files}. 

 A simple worksheet file can define title\texttt{\symbol{45}}page information
and chapter content directly in the source file, including example blocks. If
this is stored in \texttt{worksheet.g}, you can generate documentation via 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
   AutoDocWorksheet( "worksheet.g" );
\end{Verbatim}
 This creates documentation in a \texttt{doc} subdirectory of the current directory. 

 Since worksheets do not have a \texttt{PackageInfo.g}, title\texttt{\symbol{45}}page fields are specified directly in the worksheet
file. 

 For backwards compatibility, worksheet calls still accept GAP global options
for specifying the option\texttt{\symbol{45}}record entries such as \texttt{dir}, \texttt{scaffold}, \texttt{autodoc}, \texttt{gapdoc}, and \texttt{extract{\textunderscore}examples}. However, this feature is deprecated. }

 }

 
\section{\textcolor{Chapter }{The AutoDoc() function}}\label{Chapter_Reference_Section_The_AutoDoc()_function}
\logpage{[ 4, 2, 0 ]}
\hyperdef{L}{X863584DB8497D8BA}{}
{
  

\subsection{\textcolor{Chapter }{AutoDoc}}
\logpage{[ 4, 2, 1 ]}\nobreak
\hyperdef{L}{X7CBD8AAF7DCEF352}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AutoDoc({\mdseries\slshape [pkgdir][,] [optrec]})\index{AutoDoc@\texttt{AutoDoc}}
\label{AutoDoc}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing 



 This is the main function of the \textsf{AutoDoc} package. It can perform any combination of the following tasks: 
\begin{enumerate}
\item  It can (re)generate a scaffold for your package manual. That is, it can
produce two XML files in \textsf{GAPDoc} format to be used as part of your manual: First, a file named \texttt{doc/{\textunderscore}main.xml} which is used as main XML file for the package manual, i.e. this file sets the
XML doctype and defines various XML entities, includes other XML files (both
those generated by \textsf{AutoDoc} as well as additional files created by other means), tells \textsf{GAPDoc} to generate a table of contents and an index, and more. Secondly, it creates a
file \texttt{doc/title.xml} containing a title page for your documentation, with information about your
package (name, description, version), its authors and more, based on the data
in your \texttt{PackageInfo.g}. 
\item  It can scan your package for \textsf{AutoDoc} based documentation, using documentation comments and commands. This produces
additional XML files to be used as part of the package manual. 
\item  It can use \textsf{GAPDoc} to generate PDF, text and HTML (with MathJax enabled) documentation from the \textsf{GAPDoc} XML files it generated as well as additional such files provided by you. For
this, it invokes \texttt{MakeGAPDocDoc} (\textbf{GAPDoc: MakeGAPDocDoc}) to convert the XML sources, and it also instructs \textsf{GAPDoc} to copy supplementary files (such as CSS style files) into your doc directory
(see \texttt{CopyHTMLStyleFiles} (\textbf{GAPDoc: CopyHTMLStyleFiles})). 
\end{enumerate}
 These tasks can be enabled independently, so you can use as much or as little
of \textsf{AutoDoc} as your package currently needs. For more information and some examples,
please refer to Chapter \ref{Chapter_Tutorials}. 

 The parameters have the following meanings: 
\begin{description}
\item[{\mbox{\texttt{\mdseries\slshape pkgdir}}}]  This optional parameter is used to determine the package directory in which \textsf{AutoDoc} will operate, and to find the metadata concerning the package being
documented. If given, it should be an \texttt{IsDirectory} object. If the argument is omitted, then \textsf{AutoDoc} checks if it was called from a \texttt{makedoc.g} file or similar, and if so, uses the directory this is contained in. Otherwise
the current directory is used. In both cases, the specified directory must
contain a \texttt{PackageInfo.g} file, and \textsf{AutoDoc} extracts all needed metadata from that. The \texttt{IsDirectory} form is for example useful if you have multiple versions of the package around
and want to make sure the documentation of the correct version is built. 

 For backwards compatibility, it is also possible to pass a package name as
this argument, which then is resolved to the package directory of the first
instance of this package \textsf{GAP} knows about. However, this is deprecated, as it is unreliable in the presence
of multiple copies of a package. 

 Note that when using \texttt{AutoDocWorksheet} (see \ref{Section_AutoDocWorksheet}), there is no parameter corresponding to \mbox{\texttt{\mdseries\slshape pkgdir}} and so the ``package directory'' is always the current directory, and there is no metadata. 
\item[{\mbox{\texttt{\mdseries\slshape optrec}}}]  \mbox{\texttt{\mdseries\slshape optrec}} can be a record with some additional options. The following are currently
supported: 
\begin{description}
\item[{\mbox{\texttt{\mdseries\slshape dir}}}]  This should either be a string, in which case it must be a path \emph{relative} to the specified package directory, or a \texttt{Directory()} object. (Thus, the only way to designate an absolute directory is with a \texttt{Directory()} object.) This option specifies where the package documentation (e.g. the \textsf{GAPDoc} XML or the manual PDF, etc.) files are stored and/or will be generated. \\
 \emph{Default value: \texttt{"doc/"}.} 
\item[{\mbox{\texttt{\mdseries\slshape scaffold}}}]  This controls whether and how to generate scaffold XML files for the package
documentation. 

 The value should be either \texttt{true}, \texttt{false} or a record. If it is a record or \texttt{true} (the latter is equivalent to specifying an empty record), then this feature is
enabled. It is also enabled if \mbox{\texttt{\mdseries\slshape opt.scaffold}} is missing but the package's info record in \texttt{PackageInfo.g} has an \texttt{AutoDoc} entry. In all other cases (in particular if \mbox{\texttt{\mdseries\slshape opt.scaffold}} is \texttt{false}), scaffolding is disabled. 

 If scaffolding is enabled, and \mbox{\texttt{\mdseries\slshape PackageInfo.AutoDoc}} exists, then it is assumed to be a record, and its contents are used as
default values for the scaffold settings. 

 

 If \mbox{\texttt{\mdseries\slshape opt.scaffold}} is a record, it may contain the following entries. 

 
\begin{description}
\item[{\mbox{\texttt{\mdseries\slshape includes}}}]  A list of XML files to be included in the body of the main XML file. If you
specify this list and also are using \textsf{AutoDoc} to document your operations with \textsf{AutoDoc} comments, you can add \texttt{{\textunderscore}AutoDocMainFile.xml} to this list to control at which point the documentation produced by \textsf{AutoDoc} is inserted. If you do not do this, it will be added after the last of your
own XML files. 
\item[{\mbox{\texttt{\mdseries\slshape index}}}]  By default, the scaffold creates an index. If you do not want an index, set
this to \texttt{false}. 
\item[{\mbox{\texttt{\mdseries\slshape appendix}}}]  This entry is similar to \mbox{\texttt{\mdseries\slshape opt.scaffold.includes}} but is used to specify files to include after the main body of the manual,
i.e. typically appendices written directly in \textsf{GAPDoc} XML. Appendices created with \texttt{@Appendix} are included automatically after these files when scaffolding generates the
main XML file. 
\item[{\mbox{\texttt{\mdseries\slshape bib}}}]  The name of a bibliography file, in BibTeX or XML format. If this key is not
set, but there is a file \texttt{doc/PACKAGENAME.bib} then it is assumed that you want to use this as your bibliography. 
\item[{\mbox{\texttt{\mdseries\slshape bibstyle}}}]  Overrides the bibliography style used for LaTeX output. This is written as the \texttt{Style} attribute of the generated \texttt{{\textless}Bibliography .../{\textgreater}} element, so valid values are the bibliography style names understood by \textsf{GAPDoc} and BibTeX, such as \texttt{alpha}, \texttt{alphaurl}, or \texttt{plain}. 
\item[{\mbox{\texttt{\mdseries\slshape entities}}}]  A record whose keys are taken as entity names, set to the corresponding
(string) values. For example, if you pass the record ``SomePackage'', 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
               rec( SomePackage := "<Package>SomePackage</Package>",
                    RELEASEYEAR := "2015" )
\end{Verbatim}
 then the following entity definitions are added to the XML preamble: 
\begin{Verbatim}[commandchars=@|B,fontsize=\small,frame=single,label=]
  <!ENTITY SomePackage '<Package>SomePackage</Package>'>
               <!ENTITY RELEASEYEAR '2015'>
\end{Verbatim}
 This allows you to write ``\&SomePackage;'' and ``\&RELEASEYEAR;'' in your documentation, which will be replaced by respective values specified
in the entities definition. 

 Note that \textsf{AutoDoc} predefines several entities: 
\begin{description}
\item[{\mbox{\texttt{\mdseries\slshape VERSION}}}] Set to the \texttt{Version} field of your package info record.
\item[{\mbox{\texttt{\mdseries\slshape RELEASEYEAR}}}] Set to a string containing the release year, as derived from the \texttt{Date} field of your package info record.
\item[{\mbox{\texttt{\mdseries\slshape RELEASEDATE}}}] Derived from the \texttt{Date} field of your package info record.
\item[{\mbox{\texttt{\mdseries\slshape SomePackage}}}]  The precise name of this entity is derived from the \texttt{PackageName} field of your package info record. Note that it is case sensitive. The content
is defined as suggested by the example above. 
\end{description}
 
\item[{\mbox{\texttt{\mdseries\slshape TitlePage}}}]  A record with extra title\texttt{\symbol{45}}page fields for the generated
manual. Field names are interpreted as title\texttt{\symbol{45}}page XML
element names, and their values are written as element content. For example,
you can set a custom acknowledgements block with 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
               rec( Acknowledgements := "Many thanks to ..." )
\end{Verbatim}
 If this is set in \texttt{PackageInfo.g} as \texttt{PkgInfo.AutoDoc.TitlePage}, it has the same meaning as this option; see subsection \ref{Subsection_Tut:PackageInfo} in chapter \ref{Chapter_Tutorials} for details and an example. 

 For the list of valid title\texttt{\symbol{45}}page elements, see the \textsf{GAPDoc} manual, specifically section  (\textbf{GAPDoc: TitlePage}). 
\item[{\mbox{\texttt{\mdseries\slshape MainPage}}}]  If scaffolding is enabled, by default a main XML file is generated (this is
the file which contains the XML doctype and more). If you do not want this
(e.g. because you have a handwritten main XML file), but still want \textsf{AutoDoc} to generate a title page for you, you can set this option to \texttt{false} 
\item[{\mbox{\texttt{\mdseries\slshape document{\textunderscore}class}}}]  Sets the document class of the resulting PDF. The value can either be a string
which has to be the name of the new document class, a list containing this
string, or a list of two strings. Then the first one has to be the document
class name, the second one the option string ( contained in [ ] ) in {\LaTeX}. 
\item[{\mbox{\texttt{\mdseries\slshape latex{\textunderscore}header{\textunderscore}file}}}]  Replaces the standard header from \textsf{GAPDoc} completely with the header in this {\LaTeX} file. Please be careful here, and look at \textsf{GAPDoc}'s \texttt{latexheader.tex} file for an example. 
\end{description}
 
\item[{\mbox{\texttt{\mdseries\slshape autodoc}}}]  This controls whether and how to generate additional XML documentation files
by scanning for \textsf{AutoDoc} documentation comments. 

 The value should be either \texttt{true}, \texttt{false} or a record. If it is a record or \texttt{true} (the latter is equivalent to specifying an empty record), then this feature is
enabled. It is also enabled if \mbox{\texttt{\mdseries\slshape opt.autodoc}} is missing but the package depends (directly) on the \textsf{AutoDoc} package. In all other cases (in particular if \mbox{\texttt{\mdseries\slshape opt.autodoc}} is \texttt{false}), this feature is disabled. 

 

 If \mbox{\texttt{\mdseries\slshape opt.autodoc}} is a record, it may contain the following entries. 

 
\begin{description}
\item[{\mbox{\texttt{\mdseries\slshape files}}}]  A list of files (given by paths relative to the package directory) to be
scanned for \textsf{AutoDoc} documentation comments. Usually it is more convenient to use \mbox{\texttt{\mdseries\slshape autodoc.scan{\textunderscore}dirs}}, see below. 
\item[{\mbox{\texttt{\mdseries\slshape scan{\textunderscore}dirs}}}]  A list of subdirectories of the package directory (given as relative paths)
which \textsf{AutoDoc} then scans recursively for .gi, .gd, .g, and .autodoc files; all of these
files are then scanned for \textsf{AutoDoc} documentation comments. The special entries \texttt{"."} and \texttt{""} still only scan the package root itself. This controls where \textsf{AutoDoc} looks for source comments beginning with \texttt{\#!} and for standalone \texttt{.autodoc} files. It does not affect where \textsf{GAPDoc} looks for GAPDoc comments; that is controlled separately by \mbox{\texttt{\mdseries\slshape gapdoc.scan{\textunderscore}dirs}}. \\
 \emph{Default value: \texttt{[ ".", "gap", "lib", "examples", "examples/doc" ]}.} 
\item[{\mbox{\texttt{\mdseries\slshape level}}}]  This defines the level of the created documentation. The default value is 0.
When parts of the manual are declared with a higher value they will not be
printed into the manual. 
\end{description}
 
\item[{\mbox{\texttt{\mdseries\slshape gapdoc}}}]  This controls whether and how to invoke \textsf{GAPDoc} to create HTML, PDF and text files from your various XML files. 

 The value should be either \texttt{true}, \texttt{false} or a record. If it is a record or \texttt{true} (the latter is equivalent to specifying an empty record), then this feature is
enabled. It is also enabled if \mbox{\texttt{\mdseries\slshape opt.gapdoc}} is missing. In all other cases (in particular if \mbox{\texttt{\mdseries\slshape opt.gapdoc}} is \texttt{false}), this feature is disabled. 

 

 If \mbox{\texttt{\mdseries\slshape opt.gapdoc}} is a record, it may contain the following entries. 

 
\begin{description}
\item[{\mbox{\texttt{\mdseries\slshape main}}}]  The name of the main XML file of the package manual. This exists primarily to
support packages with existing manual which use a filename here which differs
from the default. In particular, specifying this is unnecessary when using
scaffolding. \\
 \emph{Default value: \texttt{{\textunderscore}main.xml} when scaffolding is enabled for package manuals, otherwise \texttt{PACKAGENAME.xml}.} 
\item[{\mbox{\texttt{\mdseries\slshape files}}}]  A list of files (given by paths relative to the package directory) to be
scanned for \textsf{GAPDoc} documentation comments. Usually it is more convenient to use \mbox{\texttt{\mdseries\slshape gapdoc.scan{\textunderscore}dirs}}, see below. 
\item[{\mbox{\texttt{\mdseries\slshape scan{\textunderscore}dirs}}}]  A list of subdirectories of the package directory (given as relative paths)
which \textsf{AutoDoc} then scans recursively for .gi, .gd and .g files; all of these files are then
scanned for \textsf{GAPDoc} documentation comments. The special entries \texttt{"."} and \texttt{""} still only scan the package root itself. This controls only where \textsf{GAPDoc} comments are searched for. It does not affect where \textsf{AutoDoc} looks for source comments beginning with \texttt{\#!} or for \texttt{.autodoc} files; use \mbox{\texttt{\mdseries\slshape autodoc.scan{\textunderscore}dirs}} for that. \\
 \emph{Default value: \texttt{[ ".", "gap", "lib", "examples", "examples/doc" ]}.} 
\item[{\mbox{\texttt{\mdseries\slshape LaTeXOptions}}}]  Must be a record with entries which can be understood by \texttt{SetGapDocLaTeXOptions} (\textbf{GAPDoc: SetGapDocLaTeXOptions}). Each entry can be a string, which will be given to \textsf{GAPDoc} directly, or a list containing of two entries: The first one must be the
string "file", the second one a filename. This file will be read and then its
content is passed to \textsf{GAPDoc} as option with the name of the entry. 
\item[{\mbox{\texttt{\mdseries\slshape gap{\textunderscore}root{\textunderscore}relative{\textunderscore}path}}}]  Either a boolean, or a string containing a relative path. By default (if this
option is not set, or is set to \texttt{false}), references in the generated documentation referring to external
documentation (such as the \textsf{GAP} manual) are encoded using absolute paths. This is fine as long as the
documentation stays on only a single computer, but is problematic when
preparing documentation that should be used on multiple computers, e.g., when
creating a distribution archive of a \textsf{GAP} package.\\
 Thus, if a relative path is provided via this option (or if it is set to \texttt{true}, in which case the relative path \texttt{../../..} is used), then \textsf{AutoDoc} and \textsf{GAPDoc} attempt to replace all absolute paths in references to \textsf{GAP} manuals by paths based on this relative path.

 

 On a technical level, \textsf{AutoDoc} passes the relative path to the \mbox{\texttt{\mdseries\slshape gaproot}} parameter of \texttt{MakeGAPDocDoc} (\textbf{GAPDoc: MakeGAPDocDoc})

 
\end{description}
 
\item[{\mbox{\texttt{\mdseries\slshape extract{\textunderscore}examples}}}]  Either \texttt{true} or a record. If set to \texttt{true}, then all manual examples are extracted and placed into files \texttt{tst/PACKAGENAME01.tst}, \texttt{tst/PACKAGENAME02.tst}, ... and so on, with one file for each chapter. For chapters with no
examples, no file is created.

 If set to a record, it may contain the following entries: 
\begin{description}
\item[{subdir}]  A string or \texttt{Directory()} object selecting where the generated \texttt{.tst} files are written. The default is \texttt{tst}. If a string is given, it is interpreted relative to the package directory,
so values such as \texttt{tst/generated} are supported. 
\item[{units}]  This controls how examples are grouped into files. Recognized values are
"Chapter" (default), "Section", "Subsection" or "Single". Depending on the
value, one file is created for each chapter, each section, each subsection or
each example. For all other values only a single file is created. 

 On a technical level, \textsf{AutoDoc} passes the value to the \mbox{\texttt{\mdseries\slshape units}} parameter of \texttt{ExtractExamples} (\textbf{GAPDoc: ExtractExamples}). 
\item[{skip{\textunderscore}empty{\textunderscore}in{\textunderscore}numbering}]  If set to \texttt{true} (the default), the generated files use filenames with strictly sequential
numbering; that means that if chapter 1 (or whatever units are being used)
contains no examples but chapter 2 does, then the examples for chapter 2 are
put into the file \texttt{tst/PACKAGENAME01.tst}. If this option is set to \texttt{false}, then the chapter numbers are used to generate the filenames; so the examples
for chapter 2 would be put into the file \texttt{tst/PACKAGENAME02.tst}. 
\end{description}
 
\end{description}
 
\end{description}
 

 The function also checks the following GAP global options, i.e. options
supplied via GAP's value\texttt{\symbol{45}}option syntax and visible through
nested calls. These are not entries of \mbox{\texttt{\mdseries\slshape optrec}}. See  (\textbf{Reference: Options Stack}) for more information about GAP's global options system. 
\begin{description}
\item[{\mbox{\texttt{\mdseries\slshape nopdf}}}]  If this global option is set to \texttt{true}, then \textsf{AutoDoc} tells \textsf{GAPDoc} not to build the PDF version of the manual. HTML and text output are still
generated. 

 This is useful on systems without a working \texttt{pdflatex} installation, or when you only need the non\texttt{\symbol{45}}PDF outputs
while iterating on the manual. 

 For example: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
       AutoDoc( rec( autodoc := true ) : nopdf );
\end{Verbatim}
 Also, if the environment variable \texttt{NOPDF} is set, then \textsf{AutoDoc} behaves as if the global option \mbox{\texttt{\mdseries\slshape nopdf}} had been enabled. 
\item[{\mbox{\texttt{\mdseries\slshape relativePath}}}]  This has the same effect as \mbox{\texttt{\mdseries\slshape gapdoc.gap{\textunderscore}root{\textunderscore}relative{\textunderscore}path}}, but as a GAP global option. It takes precedence over that record entry if
both are specified. 

 If \mbox{\texttt{\mdseries\slshape relativePath}} is \texttt{true}, then the default relative path \texttt{../../..} is used. If it is a string, then that string is used as the relative path from
the documentation directory to the GAP root. 

 For example: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
       AutoDoc( rec( autodoc := true ) : relativePath := "../../.." );
\end{Verbatim}
 
\end{description}
 In particular, a call such as 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
   Read( "makedoc.g" : nopdf, relativePath );
\end{Verbatim}
 sets both global options to \texttt{true}, and they remain visible to the \texttt{AutoDoc} call inside \texttt{makedoc.g}. 

 }

 

\subsection{\textcolor{Chapter }{InfoAutoDoc}}
\logpage{[ 4, 2, 2 ]}\nobreak
\hyperdef{L}{X81F946A785BA3D6E}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{InfoAutoDoc\index{InfoAutoDoc@\texttt{InfoAutoDoc}}
\label{InfoAutoDoc}
}\hfill{\scriptsize (info class)}}\\


 Info class for the \textsf{AutoDoc} package. Set this to 0 to suppress info messages, 1 to allow most messages,
and 2 to allow all messages including those that contain file paths. 

 This can be set by calling, for example, \texttt{SetInfoLevel(InfoAutoDoc, 0)}. Default value is 1. }

 }

 }

 \def\bibname{References\logpage{[ "Bib", 0, 0 ]}
\hyperdef{L}{X7A6F98FD85F02BFE}{}
}

\bibliographystyle{alpha}
\bibliography{bib.xml}

\addcontentsline{toc}{chapter}{References}

\def\indexname{Index\logpage{[ "Ind", 0, 0 ]}
\hyperdef{L}{X83A0356F839C696F}{}
}

\cleardoublepage
\phantomsection
\addcontentsline{toc}{chapter}{Index}


\printindex

\immediate\write\pagenrlog{["Ind", 0, 0], \arabic{page},}
\newpage
\immediate\write\pagenrlog{["End"], \arabic{page}];}
\immediate\closeout\pagenrlog
\end{document}
