AutoDoc-2025.10.16/ 0000755 0001751 0001751 00000000000 15074117054 013060 5 ustar runner runner AutoDoc-2025.10.16/doc/ 0000755 0001751 0001751 00000000000 15074117054 013625 5 ustar runner runner AutoDoc-2025.10.16/doc/manual.lab 0000644 0001751 0001751 00000016710 15074117054 015567 0 ustar runner runner \GAPDocLabFile{autodoc}
\makelabel{autodoc:Title page}{}{X7D2C85EC87DD46E5}
\makelabel{autodoc:Abstract}{}{X7AA6C5737B711C89}
\makelabel{autodoc:Copyright}{}{X81488B807F2A1CF1}
\makelabel{autodoc:Acknowledgements}{}{X82A988D47DFAFCFA}
\makelabel{autodoc:Table of Contents}{}{X8537FEB07AF2BEC8}
\makelabel{autodoc:Getting started using AutoDoc}{1}{X7A0D7AA484F466E1}
\makelabel{autodoc:Creating a package manual from scratch}{1.1}{X7BFBC6907B26AA95}
\makelabel{autodoc:Documenting code with AutoDoc}{1.2}{X87A00EED866E22E8}
\makelabel{autodoc:Using AutoDoc in an existing GAPDoc manual}{1.3}{X7FA614637B807F4D}
\makelabel{autodoc:Using AutoDoc on a complete GAPDoc manual}{1.3.1}{X7F3CEB097AF47C1E}
\makelabel{autodoc:Setting different GAPDoc options}{1.3.2}{X7D0DDF2284F2D24A}
\makelabel{autodoc:Checklist for converting an existing GAPDoc manual to use AutoDoc}{1.3.3}{X83448D91868D7994}
\makelabel{autodoc:Scaffolds}{1.4}{X8524193D824CDE0D}
\makelabel{autodoc:Generating a title page}{1.4.1}{X7CF22DE28478316F}
\makelabel{autodoc:Generating the main XML file}{1.4.2}{X7CD72CC780874FD5}
\makelabel{autodoc:What data is used from PackageInfo.g?}{1.4.3}{X799956EA85D3FC15}
\makelabel{autodoc:AutoDoc worksheets}{1.5}{X80ED3C2A78146AD1}
\makelabel{autodoc:AutoDoc documentation comments}{2}{X87668C487B1A2094}
\makelabel{autodoc:Documenting declarations}{2.1}{X871482CE838C68F6}
\makelabel{autodoc:@Description descr}{2.1.1}{X7F1D85188262A827}
\makelabel{autodoc:@Returns retval}{2.1.2}{X7DCAB2F87E8FAE90}
\makelabel{autodoc:@Arguments args}{2.1.3}{X81DAA454857F7971}
\makelabel{autodoc:@Group grpname}{2.1.4}{X8677FE8F80C00B14}
\makelabel{autodoc:@Label label}{2.1.5}{X7B0E20A27D64DF6F}
\makelabel{autodoc:@ChapterInfo chapter, section}{2.1.8}{X78938EE37A532FFA}
\makelabel{autodoc:Other documentation comments}{2.2}{X8152FEF9844B1ACD}
\makelabel{autodoc:@Chapter name}{2.2.1}{X823E613385D09F6F}
\makelabel{autodoc:@Section name}{2.2.2}{X78AA98BA7E0635D0}
\makelabel{autodoc:@Subsection name}{2.2.3}{X7FD77434802A3580}
\makelabel{autodoc:@BeginGroup [grpname]}{2.2.4}{X7D3060C17EDBCED1}
\makelabel{autodoc:@EndGroup}{2.2.5}{X7C17EB007FD42C87}
\makelabel{autodoc:@GroupTitle title}{2.2.6}{X82FB96F37FAE8167}
\makelabel{autodoc:@Level lvl}{2.2.7}{X7BF81EAF80D1A4B5}
\makelabel{autodoc:@ResetLevel}{2.2.8}{X7C6723D57F424215}
\makelabel{autodoc:@BeginExample and @EndExample}{2.2.9}{X83D6DA3B83D3436C}
\makelabel{autodoc:@BeginExampleSession and @EndExampleSession}{2.2.10}{X861E2E778510CAF7}
\makelabel{autodoc:@BeginLog and @EndLog}{2.2.11}{X81A2D44D834C0A17}
\makelabel{autodoc:@BeginLogSession and @EndLogSession}{2.2.12}{X7BADE876794FF309}
\makelabel{autodoc:@DoNotReadRestOfFile}{2.2.13}{X78DC644E8519280C}
\makelabel{autodoc:@BeginChunk name, @EndChunk, and @InsertChunk name}{2.2.14}{X83C01F9B7FA1C973}
\makelabel{autodoc:@BeginCode name, @EndCode, and @InsertCode name}{2.2.15}{X7D3671AF86B995B9}
\makelabel{autodoc:@LatexOnly text, @BeginLatexOnly, and @EndLatexOnly}{2.2.16}{X8033B34F80A12A10}
\makelabel{autodoc:@NotLatex text, @BeginNotLatex, and @EndNotLatex}{2.2.17}{X7EF303147F1BCC22}
\makelabel{autodoc:Title page commands}{2.3}{X841E3AD584F5385C}
\makelabel{autodoc:Plain text files}{2.4}{X828AE38F80CB02E7}
\makelabel{autodoc:Grouping}{2.5}{X7D7A38F87BC40C48}
\makelabel{autodoc:A family of operations}{2.5.1}{X79BF060F8436C586}
\makelabel{autodoc:Level}{2.6}{X8209AFDE8209AFDE}
\makelabel{autodoc:Markdown-like formatting of text in AutoDoc}{2.7}{X79558A2F7FE187B4}
\makelabel{autodoc:Lists}{2.7.1}{X7B256AE5780F140A}
\makelabel{autodoc:Math modes}{2.7.2}{X871412737A0E12E2}
\makelabel{autodoc:Emphasize}{2.7.3}{X7ED0330479146EFC}
\makelabel{autodoc:Inline code}{2.7.4}{X838CCDEB7E0ECEE2}
\makelabel{autodoc:Deprecated commands}{2.8}{X78CA9E5C7F494C19}
\makelabel{autodoc:AutoDoc worksheets}{3}{X80ED3C2A78146AD1}
\makelabel{autodoc:Worksheets}{3.1}{X801D4A2F8292704C}
\makelabel{autodoc:AutoDoc}{4}{X7CBD8AAF7DCEF352}
\makelabel{autodoc:The AutoDoc() function}{4.1}{X863584DB8497D8BA}
\makelabel{autodoc:Examples}{4.2}{X7A489A5D79DA9E5C}
\makelabel{autodoc:Bibliography}{Bib}{X7A6F98FD85F02BFE}
\makelabel{autodoc:References}{Bib}{X7A6F98FD85F02BFE}
\makelabel{autodoc:Index}{Ind}{X83A0356F839C696F}
\makelabel{autodoc:makedoc.g}{1.1}{X7BFBC6907B26AA95}
\makelabel{autodoc:}{1.3.3}{X83448D91868D7994}
\makelabel{autodoc:}{1.3.3}{X83448D91868D7994}
\makelabel{autodoc:}{1.3.3}{X83448D91868D7994}
\makelabel{autodoc:}{1.3.3}{X83448D91868D7994}
\makelabel{autodoc:}{1.3.3}{X83448D91868D7994}
\makelabel{autodoc:}{1.3.3}{X83448D91868D7994}
\makelabel{autodoc:}{1.3.3}{X83448D91868D7994}
\makelabel{autodoc:@Description descr}{2.1.1}{X7F1D85188262A827}
\makelabel{autodoc:@Returns retval}{2.1.2}{X7DCAB2F87E8FAE90}
\makelabel{autodoc:@Arguments args}{2.1.3}{X81DAA454857F7971}
\makelabel{autodoc:@Group grpname}{2.1.4}{X8677FE8F80C00B14}
\makelabel{autodoc:@Label label}{2.1.5}{X7B0E20A27D64DF6F}
\makelabel{autodoc:AProperty testlabel}{2.1.6}{X83B63B847B5199CF}
\makelabel{autodoc:AProperty for IsObject}{2.1.7}{X78A9022A7D5CB20E}
\makelabel{autodoc:@ChapterInfo}{2.1.8}{X78938EE37A532FFA}
\makelabel{autodoc:@Chapter}{2.2.1}{X823E613385D09F6F}
\makelabel{autodoc:@ChapterLabel}{2.2.1}{X823E613385D09F6F}
\makelabel{autodoc:@ChapterTitle}{2.2.1}{X823E613385D09F6F}
\makelabel{autodoc:@Section}{2.2.2}{X78AA98BA7E0635D0}
\makelabel{autodoc:@SectionLabel}{2.2.2}{X78AA98BA7E0635D0}
\makelabel{autodoc:@SectionTitle}{2.2.2}{X78AA98BA7E0635D0}
\makelabel{autodoc:@Subsection}{2.2.3}{X7FD77434802A3580}
\makelabel{autodoc:@SubsectionLabel}{2.2.3}{X7FD77434802A3580}
\makelabel{autodoc:@SubsectionTitle}{2.2.3}{X7FD77434802A3580}
\makelabel{autodoc:@BeginGroup}{2.2.4}{X7D3060C17EDBCED1}
\makelabel{autodoc:@EndGroup}{2.2.5}{X7C17EB007FD42C87}
\makelabel{autodoc:@GroupTitle}{2.2.6}{X82FB96F37FAE8167}
\makelabel{autodoc:@Level}{2.2.7}{X7BF81EAF80D1A4B5}
\makelabel{autodoc:@ResetLevel}{2.2.8}{X7C6723D57F424215}
\makelabel{autodoc:@BeginExample}{2.2.9}{X83D6DA3B83D3436C}
\makelabel{autodoc:@EndExample}{2.2.9}{X83D6DA3B83D3436C}
\makelabel{autodoc:@BeginExampleSession}{2.2.10}{X861E2E778510CAF7}
\makelabel{autodoc:@EndExampleSession}{2.2.10}{X861E2E778510CAF7}
\makelabel{autodoc:@BeginLog}{2.2.11}{X81A2D44D834C0A17}
\makelabel{autodoc:@EndLog}{2.2.11}{X81A2D44D834C0A17}
\makelabel{autodoc:@BeginLogSession}{2.2.12}{X7BADE876794FF309}
\makelabel{autodoc:@EndLogSession}{2.2.12}{X7BADE876794FF309}
\makelabel{autodoc:@DoNotReadRestOfFile}{2.2.13}{X78DC644E8519280C}
\makelabel{autodoc:@BeginChunk name}{2.2.14}{X83C01F9B7FA1C973}
\makelabel{autodoc:@EndChunk}{2.2.14}{X83C01F9B7FA1C973}
\makelabel{autodoc:@InsertChunk name}{2.2.14}{X83C01F9B7FA1C973}
\makelabel{autodoc:@BeginCode name}{2.2.15}{X7D3671AF86B995B9}
\makelabel{autodoc:@EndCode}{2.2.15}{X7D3671AF86B995B9}
\makelabel{autodoc:@InsertCode name}{2.2.15}{X7D3671AF86B995B9}
\makelabel{autodoc:@LatexOnly text}{2.2.16}{X8033B34F80A12A10}
\makelabel{autodoc:@BeginLatexOnly}{2.2.16}{X8033B34F80A12A10}
\makelabel{autodoc:@EndLatexOnly}{2.2.16}{X8033B34F80A12A10}
\makelabel{autodoc:@NotLatex text}{2.2.17}{X7EF303147F1BCC22}
\makelabel{autodoc:@BeginNotLatex}{2.2.17}{X7EF303147F1BCC22}
\makelabel{autodoc:@EndNotLatex}{2.2.17}{X7EF303147F1BCC22}
\makelabel{autodoc:FirstOperation for IsInt}{2.5.1}{X79BF060F8436C586}
\makelabel{autodoc:SecondOperation for IsInt, IsGroup}{2.5.1}{X79BF060F8436C586}
\makelabel{autodoc:ThirdOperation for IsGroup, IsInt}{2.5.1}{X79BF060F8436C586}
\makelabel{autodoc:AutoDocWorksheet}{3.1.1}{X809FE4137C08B28D}
\makelabel{autodoc:AutoDoc}{4.1.1}{X7CBD8AAF7DCEF352}
\makelabel{autodoc:InfoAutoDoc}{4.1.2}{X81F946A785BA3D6E}
AutoDoc-2025.10.16/doc/chap4.txt 0000644 0001751 0001751 00000047506 15074117054 015401 0 ustar runner runner
[1X4 [33X[0;0YAutoDoc[133X[101X
[1X4.1 [33X[0;0YThe AutoDoc() function[133X[101X
[1X4.1-1 AutoDoc[101X
[33X[1;0Y[29X[2XAutoDoc[102X( [[3XpackageOrDirectory[103X][,] [[3Xoptrec[103X] ) [32X function[133X
[6XReturns:[106X [33X[0;10Ynothing[133X
[33X[0;0YThis is the main function of the [5XAutoDoc[105X package. It can perform any
combination of the following tasks:[133X
[31X1[131X [33X[0;6YIt can (re)generate a scaffold for your package manual. That is, it
can produce two XML files in [5XGAPDoc[105X format to be used as part of your
manual: First, a file named [11Xdoc/PACKAGENAME.xml[111X (with your package's
name substituted) 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 [5XAutoDoc[105X as
well as additional files created by other means), tells [5XGAPDoc[105X to
generate a table of contents and an index, and more. Secondly, it
creates a file [11Xdoc/title.xml[111X 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
[11XPackageInfo.g[111X.[133X
[31X2[131X [33X[0;6YIt can scan your package for [5XAutoDoc[105X based documentation (by using
[5XAutoDoc[105X tags and the Autodoc command. This will produce further XML
files to be used as part of the package manual.[133X
[31X3[131X [33X[0;6YIt can use [5XGAPDoc[105X to generate PDF, text and HTML (with MathJaX
enabled) documentation from the [5XGAPDoc[105X XML files it generated as well
as additional such files provided by you. For this, it invokes
[2XMakeGAPDocDoc[102X ([14XGAPDoc: MakeGAPDocDoc[114X) to convert the XML sources, and
it also instructs [5XGAPDoc[105X to copy supplementary files (such as CSS
style files) into your doc directory (see [2XCopyHTMLStyleFiles[102X ([14XGAPDoc:
CopyHTMLStyleFiles[114X)).[133X
[33X[0;0YFor more information and some examples, please refer to Chapter [14X1[114X.[133X
[33X[0;0YThe parameters have the following meanings:[133X
[8X[3XpackageOrDirectory[103X[8X[108X
[33X[0;6YThe purpose of this parameter is twofold: to determine the package
directory in which [5XAutoDoc[105X will operate, and to find the metadata
concerning the package being documented. The parameter is either a
string, an [10XIsDirectory[110X object, or omitted. If it is a string, [5XAutoDoc[105X
interprets it as the name of a package, uses the metadata of the first
package known to [5XGAP[105X with that name, and uses the [10XInstallationPath[110X
specified in that metadata as the package directory. If
[3XpackageOrDirectory[103X is an [10XIsDirectory[110X object, this is used as package
directory; if the argument is omitted, then the current directory is
used. In the last two cases, the specified directory must contain a
[11XPackageInfo.g[111X file, and [5XAutoDoc[105X extracts all needed metadata from
that. The [10XIsDirectory[110X 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.[133X
[33X[0;6YNote that when using [10XAutoDocWorksheet[110X (see [14X3.1[114X), there is no parameter
corresponding to [3XpackageOrDirectory[103X and so the [21Xpackage directory[121X is
always the current directory, and there is no metadata.[133X
[8X[3Xoptrec[103X[8X[108X
[33X[0;6Y[3Xoptrec[103X can be a record with some additional options. The following are
currently supported:[133X
[8X[3Xdir[103X[8X[108X
[33X[0;12YThis should either be a string, in which case it must be a path
[13Xrelative[113X to the specified package directory, or a [10XDirectory()[110X
object. (Thus, the only way to designate an absolute directory
is with a [10XDirectory()[110X object.) This option specifies where the
package documentation (e.g. the [5XGAPDoc[105X XML or the manual PDF,
etc.) files are stored and/or will be generated.[133X
[33X[0;12Y[13XDefault value: [10X"doc/"[110X.[113X[133X
[8X[3Xscaffold[103X[8X[108X
[33X[0;12YThis controls whether and how to generate scaffold XML files for
the package documentation.[133X
[33X[0;12YThe value should be either [9Xtrue[109X, [9Xfalse[109X or a record. If it is a
record or [9Xtrue[109X (the latter is equivalent to specifying an empty
record), then this feature is enabled. It is also enabled if
[3Xopt.scaffold[103X is missing but the package's info record in
[11XPackageInfo.g[111X has an [10XAutoDoc[110X entry. In all other cases (in
particular if [3Xopt.scaffold[103X is [9Xfalse[109X), scaffolding is disabled.[133X
[33X[0;12YIf scaffolding is enabled, and [3XPackageInfo.AutoDoc[103X exists, then
it is assumed to be a record, and its contents are used as
default values for the scaffold settings.[133X
[33X[0;12YIf [3Xopt.scaffold[103X is a record, it may contain the following
entries.[133X
[8X[3Xincludes[103X[8X[108X
[33X[0;18YA list of XML files to be included in the body of the main
XML file. If you specify this list and also are using
[5XAutoDoc[105X to document your operations with [5XAutoDoc[105X comments,
you can add [11X_AutoDocMainFile.xml[111X to this list to control
at which point the documentation produced by [5XAutoDoc[105X is
inserted. If you do not do this, it will be added after
the last of your own XML files.[133X
[8X[3Xindex[103X[8X[108X
[33X[0;18YBy default, the scaffold creates an index. If you do not
want an index, set this to [9Xfalse[109X.[133X
[8X[3Xappendix[103X[8X[108X
[33X[0;18YThis entry is similar to [3Xopt.scaffold.includes[103X but is used
to specify files to include after the main body of the
manual, i.e. typically appendices.[133X
[8X[3Xbib[103X[8X[108X
[33X[0;18YThe name of a bibliography file, in BibTeX or XML format.
If this key is not set, but there is a file
[11Xdoc/PACKAGENAME.bib[111X then it is assumed that you want to
use this as your bibliography.[133X
[8X[3Xentities[103X[8X[108X
[33X[0;18YA record whose keys are taken as entity names, set to the
corresponding (string) values. For example, if you pass
the record [21XSomePackage[121X,[133X
[4X [32X[104X
[4X rec( SomePackage := "SomePackage",[104X
[4X RELEASEYEAR := "2015" )[104X
[4X[32X[104X
[33X[0;18Ythen the following entity definitions are added to the XML
preamble:[133X
[4X [32X[104X
[4XSomePackage'>[104X
[4X [104X
[4X[32X[104X
[33X[0;18YThis allows you to write [21X&SomePackage;[121X and [21X&RELEASEYEAR;[121X
in your documentation, which will be replaced by
respective values specified in the entities definition.[133X
[8X[3XTitlePage[103X[8X[108X
[33X[0;18YA record whose entries are used to embellish the generated
title page for the package manual with extra information,
such as a copyright statement or acknowledgments. To this
end, the names of the record components are used as XML
element names, and the values of the components are
outputted as content of these XML elements. For example,
you could pass the following record to set a custom
acknowledgements text:[133X
[4X [32X[104X
[4X rec( Acknowledgements := "Many thanks to ..." )[104X
[4X[32X[104X
[33X[0;18YFor a list of valid entries in the title page, please
refer to the [5XGAPDoc[105X manual, specifically section [14X'GAPDoc:
TitlePage'[114X.[133X
[8X[3XMainPage[103X[8X[108X
[33X[0;18YIf 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 [5XAutoDoc[105X to
generate a title page for you, you can set this option to
[9Xfalse[109X[133X
[8X[3Xdocument_class[103X[8X[108X
[33X[0;18YSets 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.[133X
[8X[3Xlatex_header_file[103X[8X[108X
[33X[0;18YReplaces the standard header from [5XGAPDoc[105X completely with
the header in this LaTeX file. Please be careful here, and
look at [5XGAPDoc[105X's [11Xlatexheader.tex[111X file for an example.[133X
[8X[3Xautodoc[103X[8X[108X
[33X[0;12YThis controls whether and how to generate additional XML
documentation files by scanning for [5XAutoDoc[105X documentation
comments.[133X
[33X[0;12YThe value should be either [9Xtrue[109X, [9Xfalse[109X or a record. If it is a
record or [9Xtrue[109X (the latter is equivalent to specifying an empty
record), then this feature is enabled. It is also enabled if
[3Xopt.autodoc[103X is missing but the package depends (directly) on the
[5XAutoDoc[105X package. In all other cases (in particular if
[3Xopt.autodoc[103X is [9Xfalse[109X), this feature is disabled.[133X
[33X[0;12YIf [3Xopt.autodoc[103X is a record, it may contain the following
entries.[133X
[8X[3Xfiles[103X[8X[108X
[33X[0;18YA list of files (given by paths relative to the package
directory) to be scanned for [5XAutoDoc[105X documentation
comments. Usually it is more convenient to use
[3Xautodoc.scan_dirs[103X, see below.[133X
[8X[3Xscan_dirs[103X[8X[108X
[33X[0;18YA list of subdirectories of the package directory (given
as relative paths) which [5XAutoDoc[105X then scans for .gi, .gd,
.g, and .autodoc files; all of these files are then
scanned for [5XAutoDoc[105X documentation comments.[133X
[33X[0;18Y[13XDefault value: [10X[ ".", "gap", "lib", "examples",
"examples/doc" ][110X.[113X[133X
[8X[3Xlevel[103X[8X[108X
[33X[0;18YThis 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.[133X
[8X[3Xgapdoc[103X[8X[108X
[33X[0;12YThis controls whether and how to invoke [5XGAPDoc[105X to create HTML,
PDF and text files from your various XML files.[133X
[33X[0;12YThe value should be either [9Xtrue[109X, [9Xfalse[109X or a record. If it is a
record or [9Xtrue[109X (the latter is equivalent to specifying an empty
record), then this feature is enabled. It is also enabled if
[3Xopt.gapdoc[103X is missing. In all other cases (in particular if
[3Xopt.gapdoc[103X is [9Xfalse[109X), this feature is disabled.[133X
[33X[0;12YIf [3Xopt.gapdoc[103X is a record, it may contain the following entries.[133X
[8X[3Xmain[103X[8X[108X
[33X[0;18YThe 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.[133X
[33X[0;18Y[13XDefault value: [10XPACKAGENAME.xml[110X[113X.[133X
[8X[3Xfiles[103X[8X[108X
[33X[0;18YA list of files (given by paths relative to the package
directory) to be scanned for [5XGAPDoc[105X documentation
comments. Usually it is more convenient to use
[3Xgapdoc.scan_dirs[103X, see below.[133X
[8X[3Xscan_dirs[103X[8X[108X
[33X[0;18YA list of subdirectories of the package directory (given
as relative paths) which [5XAutoDoc[105X then scans for .gi, .gd
and .g files; all of these files are then scanned for
[5XGAPDoc[105X documentation comments.[133X
[33X[0;18Y[13XDefault value: [10X[ ".", "gap", "lib", "examples",
"examples/doc" ][110X.[113X[133X
[8X[3XLaTeXOptions[103X[8X[108X
[33X[0;18YMust be a record with entries which can be understood by
[2XSetGapDocLaTeXOptions[102X ([14XGAPDoc: SetGapDocLaTeXOptions[114X).
Each entry can be a string, which will be given to [5XGAPDoc[105X
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
[5XGAPDoc[105X as option with the name of the entry.[133X
[8X[3Xgap_root_relative_path[103X[8X[108X
[33X[0;18YEither a boolean, or a string containing a relative path.
By default (if this option is not set, or is set to
[9Xfalse[109X), references in the generated documentation
referring to external documentation (such as the [5XGAP[105X
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 [5XGAP[105X package.[133X
[33X[0;18YThus, if a relative path is provided via this option (or
if it is set to [9Xtrue[109X, in which case the relative path
[11X../../..[111X is used), then [5XAutoDoc[105X and [5XGAPDoc[105X attempt to
replace all absolute paths in references to [5XGAP[105X manuals by
paths based on this relative path.[133X
[33X[0;18YOn a technical level, [5XAutoDoc[105X passes the relative path to
the [3Xgaproot[103X parameter of [2XMakeGAPDocDoc[102X ([14XGAPDoc:
MakeGAPDocDoc[114X)[133X
[8X[3Xextract_examples[103X[8X[108X
[33X[0;12YEither [9Xtrue[109X or a record. If set to [9Xtrue[109X, then all manual
examples are extracted and placed into files
[11Xtst/PACKAGENAME01.tst[111X, [11Xtst/PACKAGENAME02.tst[111X, ... and so on,
with one file for each chapter. For chapters with no examples,
no file is created.[133X
[33X[0;12YAs a record, the entry can have the following entries itself, to
specify some options.[133X
[8Xunits[108X
[33X[0;18YThis 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.[133X
[33X[0;18YOn a technical level, [5XAutoDoc[105X passes the value to the
[3Xunits[103X parameter of [2XExtractExamples[102X ([14XGAPDoc:
ExtractExamples[114X).[133X
[8Xskip_empty_in_numbering[108X
[33X[0;18YIf set to [9Xtrue[109X (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 [11Xtst/PACKAGENAME01.tst[111X.
If this option is set to [9Xfalse[109X, then the chapter numbers
are used to generate the filenames; so the examples for
chapter 2 would be put into the file
[11Xtst/PACKAGENAME02.tst[111X.[133X
[1X4.1-2 InfoAutoDoc[101X
[33X[1;0Y[29X[2XInfoAutoDoc[102X [32X info class[133X
[33X[0;0YInfo class for the [5XAutoDoc[105X 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.[133X
[33X[0;0YThis can be set by calling, for example, [10XSetInfoLevel(InfoPackageManager,
0)[110X. Default value 1.[133X
[1X4.2 [33X[0;0YExamples[133X[101X
[33X[0;0YSome basic examples for using [10XAutoDoc[110X were already shown in Chapter [14X1[114X.[133X
AutoDoc-2025.10.16/doc/chap3.html 0000644 0001751 0001751 00000007017 15074117054 015516 0 ustar runner runner
GAP (AutoDoc) - Chapter 3: AutoDoc worksheets
The intention of these function is to create stand-alone pdf and html files using AutoDoc without having them associated to a package. It uses the same optional records as the AutoDoc command itself, but instead of a package name there should be a filename or a list of filenames containing AutoDoc text from which the documents are created. Please see the AutoDoc command for more information about this and have a look at 1.5 for a simple worksheet example.
AutoDoc-2025.10.16/doc/clean 0000755 0001751 0001751 00000000242 15074117054 014633 0 ustar runner runner #!/bin/sh
rm -f *.{aux,lab,log,dvi,ps,pdf,bbl,ilg,ind,idx,out,html,tex,pnr,txt,blg,toc,six,brf,css,js} _Chapter*.xml title.xml _AutoDocMainFile.xml AutoDoc.xml
AutoDoc-2025.10.16/doc/Tutorials.xml 0000644 0001751 0001751 00000057015 15074117054 016345 0 ustar runner runner Getting started using &AutoDoc;
&AutoDoc; is a ⪆ package which is meant to aid ⪆ package
authors in creating and maintaining the documentation of their packages.
In this capacity it builds upon the &GAPDoc; package (see
https://www.gap-system.org/Packages/gapdoc.html).
As such, it is not a replacement for &GAPDoc;, but rather complements it.
In this chapter we describe how to get started using &AutoDoc; for your
package. First, we explain in Section how to write a
new package manual from scratch.
Then we show in Section how you might
benefit from &AutoDoc; even if you already have a complete manual written
using &GAPDoc;.
In Section , we explain how you may use &AutoDoc;
to generate a title page and the main XML file for your manual.
Finally, Section , explains what
&AutoDoc; worksheets are and how to use them.
Creating a package manual from scratch
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 command like this,
while running ⪆ from within your package's directory (the
one containing the PackageInfo.g file):
LoadPackage( "AutoDoc" );
AutoDoc( rec( scaffold := true ) );
This first reads the PackageInfo.g file from the current
directory. It extracts information about the package from it
(such as its name and version, see Section ).
It then creates two XML files doc/NAME_OF_YOUR_PACKAGE.xml and
doc/title.xml inside the package directory. Finally, it runs
&GAPDoc; on them to produce a nice initial PDF and HTML version of your
fresh manual.
To ensure that the ⪆ help system picks up your package manual, you
should also add something like the following to your
PackageInfo.g:
PackageDoc := rec(
BookName := ~.PackageName,
ArchiveURLSubset := ["doc"],
HTMLStart := "doc/chap0.html",
PDFFile := "doc/manual.pdf",
SixFile := "doc/manual.six",
LongTitle := ~.Subtitle,
),
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 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-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 that for you, more research on artificial intelligence
is required).
To add more content, you have several options: You could add further &GAPDoc;
XML files containing extra chapters, sections and so on. Or you could use
classic &GAPDoc; source comments. For details on either, please refer to
, as well as Section
of this manual on how to teach the
command to include this extra documentation.
Or you could use the special documentation facilities &AutoDoc; provides
(see Section ).
You will probably want to re-run the command
frequently, e.g. whenever you modified your documentation or your
PackageInfo.g. To make this more convenient and reproducible, we
recommend putting its invocation into a file makedoc.g in your package
makedoc.g
directory, with content based on the following example:
LoadPackage( "AutoDoc" );
AutoDoc( rec( autodoc := true ) );
QUIT;
Then you can regenerate the package manual from the command line with the
following command, executed from within in the package directory:
gap makedoc.g
Documenting code with &AutoDoc;
To get one of your global functions, operations, attributes
etc. to appear in the package manual, simply insert an &AutoDoc; comment
of the form #! directly in front of it. For example:
#!
DeclareOperation( "ToricVariety", [ IsConvexObject ] );
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:
conv.
DeclareOperation( "ToricVariety", [ IsConvexObject ] );
]]>
For a thorough description of what you can do with &AutoDoc;
documentation comments, please refer to chapter .
Suppose you have not been using &GAPDoc; before but instead used the process
described in section to create your manual.
Then the following ⪆ command will regenerate the manual and automatically
include all newly documented functions, operations etc.:
LoadPackage( "AutoDoc" );
AutoDoc( rec( scaffold := true,
autodoc := true ) );
If you are not using the scaffolding feature, e.g. because you already
have an existing &GAPDoc; based manual, then you can still use &AutoDoc;
documentation comments. Just make sure to first edit the main XML
file of your documentation, and insert the line
<#Include SYSTEM "_AutoDocMainFile.xml">
in a suitable place. This means that you can mix &AutoDoc; documentation
comment freely with your existing documentation; you can even still make
use of any existing &GAPDoc; documentation comments in your code.
The following command should be useful for you in this case; it
still scans the package code for &AutoDoc; documentation comments
and the runs &GAPDoc; to produce HTML and PDF output, but does not
touch your documentation XML files otherwise.
LoadPackage( "AutoDoc" );
AutoDoc( rec( autodoc := true ) );
Using &AutoDoc; in an existing &GAPDoc; manual
Even if you already have an existing &GAPDoc; manual, it might be
interesting for you to use &AutoDoc; for two purposes:
First off, with &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 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 &AutoDoc; for
this purpose only, e.g. &io; and orb.
Using &AutoDoc; on a complete &GAPDoc; manual
Suppose you already have a complete XML manual, with some main and title
XML files and some documentation for operations distributed over
all your .g, .gd, and .gi files.
Suppose the main XML file is named PACKAGENAME.xml and is in the
/doc subdirectory of your package. Then you can rebuild your manual
by executing the following two &GAP; commands from a &GAP; session started
in the root directory of your package:
LoadPackage( "AutoDoc" );
AutoDoc( );
In contrast, the RingsForHomalg package currently uses
essentially the following code in its makedoc.g file to achieve the same result:
LoadPackage( "GAPDoc" );
SetGapDocLaTeXOptions( "utf8" );
bib := ParseBibFiles( "doc/RingsForHomalg.bib" );
WriteBibXMLextFile( "doc/RingsForHomalgBib.xml", bib );
list := [
"../gap/RingsForHomalg.gd",
"../gap/RingsForHomalg.gi",
"../gap/Singular.gi",
"../gap/SingularBasic.gi",
"../examples/RingConstructionsExternalGAP.g",
"../examples/RingConstructionsSingular.g",
"../examples/RingConstructionsMAGMA.g",
"../examples/RingConstructionsMacaulay2.g",
"../examples/RingConstructionsSage.g",
"../examples/RingConstructionsMaple.g",
];
MakeGAPDocDoc( "doc", "RingsForHomalg", list, "RingsForHomalg" );
GAPDocManualLab( "RingsForHomalg" );
Note that in particular, you do not have to worry about keeping a list of your
implementation files up-to-date.
But there is more. &AutoDoc; can create .tst files from the
examples in your manual to test your package. This can be achieved via
LoadPackage( "AutoDoc" );
AutoDoc( rec( extract_examples := true ) );
Now files PACKAGENAME01.tst, PACKAGENAME02.tst and so appear in the
tst/ subdirectory of your package, and can be tested as usual using
respectively .
Setting different &GAPDoc; options
Sometimes, the default values for the &GAPDoc; command used by &AutoDoc;
may not be suitable for your manual.
Suppose your main XML file is not named PACKAGENAME.xml, but rather something else, e.g. main.xml.
Then you can tell &AutoDoc; to use this file as the main XML file via
LoadPackage( "AutoDoc" );
AutoDoc( rec( gapdoc := rec( main := "main" ) ) );
As explained above, by default &AutoDoc; scans all .g, .gd and .gi files
it can find inside of your package root directory, and in the subdirectories gap,
lib, examples and examples/doc as well.
If you keep source files with documentation in other directories,
you can adjust the list of directories AutoDoc scans via the scan_dirs option.
The following example illustrates this by instructing &AutoDoc; to only search in the subdirectory package_sources
of the packages root directory.
LoadPackage( "AutoDoc" );
AutoDoc( rec( gapdoc := rec( scan_dirs := [ "package_sources" ] ) ) );
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:
LoadPackage( "AutoDoc" );
AutoDoc( rec( gapdoc := rec( files := [ "path/to/some/hidden/file.gds" ] ) ) );
Giving such a file does not prevent the standard scan_dirs from being scanned for
other files.
Next, &GAPDoc; supports the documentation to be built with relative paths.
This means, links to manuals of other packages or the &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 &GAP; installation around later.
Suppose you are starting &GAP; in the root path of your package as always,
and the standard call of will then build the documentation in the doc subdirectory of your package.
From this directory, the gap root directory has the relative path ../../...
Then you can enable the relative paths by
LoadPackage( "AutoDoc" );
AutoDoc( rec( gapdoc := rec( gap_root_relative_path := "../../.." ) ) );
or, since ../../.. is the standard option for gap_root_relative_path, by
LoadPackage( "AutoDoc" );
AutoDoc( rec( gapdoc := rec( gap_root_relative_path := true ) ) );
Checklist for converting an existing &GAPDoc; manual to use &AutoDoc;
Here is a checklist for authors of a package &PackageName;,
which already has a &GAPDoc; based manual, who wish to use &AutoDoc;
to build the manual from now on.
We assume that the manual is currently built by reading a file
makedoc.g and that the main .xml file
is named manual.xml.
The files PackageInfo.g, makedoc.g,
doc/title.xml and doc/PackageName.xml
(if it exists) will be altered by this procedure,
so it may be wise to keep backup copies.
You should have copies of the &AutoDoc; files PackageInfo.g
and makedoc.g to hand when reading these instructions.
Copy AutoDoc/makedoc.g to PackageName/makedoc.g.
Edit PackageName/makedoc.g as follows.
Change the header comment to match other files in your package.
After LoadPackage("AutoDoc");
add LoadPackage("PackageName");.
In the AutoDoc record delete autodoc := true;.
In the scaffold record change the includes list
to be the list of your .xml files that are contained in
manual.xml.
If you do not have a bibliography you may delete the
bib := "bib.xml", field in the scaffold.
Otherwise, edit the file name if you have a different file.
If you only have a .bib file
(manual.bib or bib.xml.bib say)
you should rename this file PackageName.bib.
In the LaTeXOptions record,
which is in the gapdoc record, enter any
&LaTeX; newcommands previously in manual.xml.
(If there are none you may safely delete this record.)
To illustrate this option, the &AutoDoc; file makedoc.g
defines the command \bbZ
by \newcommand{\bbZ}{\mathbb{Z}},
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.
Now edit PackageName/PackageInfo.g as follows.
Delete any PKGVERSIONDATA chunk that may be there.
One reason for converting your manual to use &AutoDoc; is to stop
using entities such as PACKAGENAMEVERSION.
Copy the AutoDoc record from AutoDoc/PackageInfo.g
to the end of your file (just before the final "));".
Replace the Copyright, Abstract and
Acknowledgements fields of the TitlePage
record with the corresponding material from your manual.xml.
(If you do not have an abstract, then delete the
Abstract field, etc.)
In the entities record enter any entities
previously stored in your manual.xml.
(Again, if you have none, you may safely delete this record.)
To illustrate this option the &AutoDoc; file PackageInfo.g
defines entities for the names of packages &io; and &PackageName;.
If you are using a GitHub repository, as well as running
"git add" on files makedoc.g,
PackageInfo.g and doc/PackageName.bib,
you should run "git rm -f" on files doc/manual.xml,
and doc/title.xml.
You should now be ready to run &GAP; and Read("makedoc.g");
in your package root directory.
ScaffoldsGenerating a title page
For most (if not all) &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 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. &GAPDoc; can help to a degree with
this via entities. Thus, you will sometimes see code like this in PackageInfo.g
files:
##
##
##
## <#/GAPDoc>
]]>
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 &AutoDoc; to generate a title page for your manual based on the
information in your PackageInfo.g. The following commands do just that
(in addition to building your manual), by generating a file called
doc/title.xml.
LoadPackage( "AutoDoc" );
AutoDoc( rec( scaffold := rec( MainPage := false ) ) );
Note that this only outputs doc/title.xml but does not
touch any other files of your documentation. In particular, you need
to explicitly include doc/title.xml from your main XML file.
However, you can also tell &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 &AutoDoc;
not to generate a main page.
Generating the main XML file
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 &AutoDoc; documentation comments.
LoadPackage( "AutoDoc" );
AutoDoc( rec( scaffold := true ) );
You can instruct &AutoDoc; to include additional XML files by giving it
a list of filenames, as in the following example:
LoadPackage( "AutoDoc" );
AutoDoc(rec(
scaffold := rec(
includes := [ "somefile.xml", "anotherfile.xml" ]
)
));
For more information, please consult the documentation
of the function.
What data is used from PackageInfo.g?
&AutoDoc; can use data from PackageInfo.g in order to
generate a title page. Specifically, the following components
of the package info record are taken into account:
PackageName
This is used to set the <Title> element of the
title page.
Subtitle
This is used to set the <Subtitle> element of the
title page.
Version
This is used to set the <Version> element of the
title page, with the string Version prepended.
Date
This is used to set the <Date> element of the
title page.
Persons
This is used to generate <Author> elements in the
generated title page.
PackageDoc
This is a record (or a list of records) which is used to tell the
&GAP; help system about the package manual. Currently &AutoDoc;
extracts the value of the PackageDoc.BookName component
and then passes that on to &GAPDoc; when creating the HTML, PDF
and text versions of the manual.
AutoDoc
This is a record which can be used to control the scaffolding performed by
&AutoDoc;, specifically to provide extra information for the title page. For
example, you can set AutoDoc.TitlePage.Copyright to a string which will
then be inserted on the generated title page. Using this method you can
customize the following title page elements: TitleComment,
Abstract, Copyright, Acknowledgements and Colophon.
Note that AutoDoc.TitlePage behaves exactly the same
as the scaffold.TitlePage parameter of the
function.
AutoDoc worksheets
&AutoDoc; worksheets can be used to create HTML and PDF documents using AutoDoc syntax and possibly
including &GAP; examples and implementations without having them associated to a package.
A file for a worksheet could look like this:
#! @Title My first worksheet
#! @Author Charlie Brown
#! @Chapter Some groups
#! @BeginExample
S3 := SymmetricGroup( 3 );;
S4 := SymmetricGroup( 4 );;
#! @EndExample
Now, one can create a PDF and HTML document, like a package documentation out of it. Suppose the document above
is saved as worksheet.g. Then, when &GAP; is started in the directory of this file, the command
AutoDocWorksheet( "worksheet.g" );
will create a subdirectory called doc of the current directory in which it will create the documentation.
There are several options to configure the output of the worksheet command, which are identical to the
options of the command. It is even possible to test the examples in the worksheet using the
extract_examples option of the command.
Since the worksheets do not have a PackageInfo.g to extract information, all possible tags that &GAPDoc; supports for
the title page can be set into the document. A fully typed title page can look like this:
#! @Title My first worksheet
#! @Subtitle Some small examples
#! @Author Charlie Brown
#! @Version 0.1
#! @TitleComment Some worksheet
#! @Date 01/01/2016
#! @Address TU Kaiserslautern
#! @Abstract
#! A worksheet showing some small examples about groups.
#! @Copyright 2016 Charlie Brown
#! @Acknowledgements Woodstock
#! @Colophon Some colophon
#! @Chapter Some groups
#! @BeginExample
S3 := SymmetricGroup( 3 );;
S4 := SymmetricGroup( 4 );;
#! @EndExample
AutoDoc-2025.10.16/doc/bib.xml.bib 0000644 0001751 0001751 00000001256 15074117054 015642 0 ustar runner runner
@manual{ GAPDoc,
author = {L{\"u}beck, F. and Neunh{\"o}ffer, M.},
title = {{GAPDoc (Version 1.5.1)}},
organization = {RWTH Aachen},
year = {2012},
note = {GAP package, \href
{http://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc/index.html}
{\texttt{http://www.math.rwth\texttt{\symbol{45}}aachen.de/}\discretionary
{}{}{}\texttt{\texttt{\symbol{126}}Frank.Luebeck/}\discretionary
{}{}{}\texttt{GAPDoc/}\discretionary
{}{}{}\texttt{index.html}}},
printedkey = {LN12}
}
AutoDoc-2025.10.16/doc/ragged.css 0000644 0001751 0001751 00000000231 15074117054 015564 0 ustar runner runner /* times.css Frank Lübeck */
/* Change default CSS to use Times font. */
body {
text-align: left;
}
AutoDoc-2025.10.16/doc/chooser.html 0000644 0001751 0001751 00000007456 15074117054 016171 0 ustar runner runner
GAPDoc Style Chooser
AutoDoc-2025.10.16/doc/_Chapter_AutoDoc_worksheets.xml 0000644 0001751 0001751 00000001643 15074117054 021774 0 ustar runner runner
AutoDoc worksheetsWorksheets
The intention of these function is to create stand-alone pdf and html files
using AutoDoc without having them associated to a package.
It uses the same optional records as the &AutoDoc; command itself, but instead of
a package name there should be a filename or a list of filenames containing AutoDoc
text from which the documents are created. Please see the &AutoDoc; command for more
information about this and have a look at for a simple worksheet example.
AutoDoc-2025.10.16/doc/chapBib.html 0000644 0001751 0001751 00000004721 15074117054 016047 0 ustar runner runner
GAP (AutoDoc) - References
You can document declarations of global functions and variables, operations, attributes etc. by inserting AutoDoc comments into your sources before these declaration. An AutoDoc comment always starts with #!. This is also the smallest possible AutoDoc command. If you want your declaration documented, just write #! at the line before the documentation. For example:
#!
DeclareOperation( "AnOperation",
[ IsList ] );
This will produce a manual entry for the operation AnOperation.
Inside of AutoDoc comments, AutoDoc commands starting with @ can be used to control the output AutoDoc produces.
2.1 Documenting declarations
In the bare form above, the manual entry for 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 AutoDoc comment before the declaration. Currently, the following commands are provided:
2.1-1 @Description descr
Adds the text in the following lines of the AutoDoc to the description of the declaration in the manual. Lines are until the next AutoDoc command or until the declaration is reached.
2.1-2 @Returns ret_val
The string ret_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.
2.1-3 @Arguments args
The string 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 GAP options are used, this can be followed by a colon : and one or more assignments, like n[, r]: tries := 100.
2.1-4 @Group grpname
Adds the following method to a group with the given name. See section 2.5 for more information about groups.
2.1-5 @Label 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 DeclareOperation, DeclareAttribute, etc.), a default label is generated from this filter list.
Adds the entry to the given chapter and section. Here, chapter and section are the respective titles.
As an example, a full AutoDoc comment with all options could look like this:
#! @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 );
2.2 Other documentation comments
There are also some commands which can be used in AutoDoc comments that are not associated to any declaration. This is useful for additional text in your documentation, examples, mathematical chapters, etc..
2.2-1 @Chapter name
Sets the active chapter, all subsequent functions which do not have an explicit chapter declared in their AutoDoc comment via @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 @Description, will be added to the chapter as regular text. Additionally, the chapters label will be set to Chapter_name. Example:
#! @Chapter My chapter
#! This is my chapter.
#! I document my stuff in it.
The @ChapterLabellabel command can be used to set the label of the chapter to Chapter_label instead of Chapter_name. Additionally, the chapter will be stored as _Chapter_label.xml. The @ChapterTitletitle command can be used to set a heading for the chapter that is different from name. Note that the title does not affect the label. If you use all three commands, i.e.,
#! @Chapter name
#! @ChapterLabel label
#! @ChapterTitle title
title is used for the headline, label for cross-referencing, and name for setting the same chapter as active chapter again.
2.2-2 @Section name
Sets an active section like @Chapter sets an active chapter. The section automatically ends with the next @Section or @Chapter command.
#! @Section My first manual section
#! In this section I am going to document my first method.
The @SectionLabellabel command can be used to set the label of the section to Section_label instead of Chapter_chaptername_Section_name. The @SectionTitletitle command can be used to set a heading for the section that is different from name.
2.2-3 @Subsection name
Sets an active subsection like @Section sets an active section. The subsection automatically ends with the next @Subsection, @Section or @Chapter command. It also ends with the next documented function. Indeed, internally each function manpage is treated like a subsection.
#! @Subsection My first manual subsection
#! In this subsection I am going to document my first example.
The @SubsectionLabellabel command can be used to set the label of the subsection to Subsection_label instead of Chapter_chaptername_Section_sectionname_Subsection_name. The @SubsectionTitletitle command can be used to set a heading for the subsection that is different from name.
2.2-4 @BeginGroup [grpname]
Starts a group. All following documented declarations without an explicit @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 @EndGroup command is reached.
See section 2.5 for more information about groups.
Sets the subsection heading for the current group to title. In the absence of any @GroupTitle command, the heading will be the name of the first entry in the group. See 2.5 for more information.
2.2-7 @Level lvl
Sets the current level of the documentation. All items created after this, chapters, sections, and items, are given the level lvl, until the @ResetLevel command resets the level to 0 or another level is set.
See section 2.6 for more information about levels.
2.2-8 @ResetLevel
Resets the current level to 0.
2.2-9 @BeginExample and @EndExample
@BeginExample marks the start of an example to be put into the manual. It differs from GAPDoc's <Example> (see 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 GAP, and parsed by AutoDoc. To achieve this, GAP commands are not preceded by a comment, while output has to be preceded by an AutoDoc comment. The gap> prompt for the display in the manual is added by AutoDoc. @EndExample ends the example block.
The AutoDoc command @Example is an alias of @BeginExample.
2.2-10 @BeginExampleSession and @EndExampleSession
@BeginExampleSession marks the start of an example to be put into the manual, while @EndExampleSession ends the example block. It is the direct analog of GAPDoc's <Example> (see GAPDoc: Log).
It inserts an example into the manual just as @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 AutoDoc comment (#!). 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 #! and the gap> prompt. The AutoDoc command @ExampleSession is an alias of @BeginExampleSession.
2.2-11 @BeginLog and @EndLog
Works just like the @BeginExample command, but the example will not be tested. See the GAPDoc manual for more information. The AutoDoc command @Log is an alias of @BeginLog.
2.2-12 @BeginLogSession and @EndLogSession
Works just like the @BeginExampleSession command, but the example will not be tested if manual examples are run. It is the direct analog of GAPDoc's <Log> (see GAPDoc: Log). The AutoDoc command @LogSession is an alias of @BeginLogSession.
2.2-13 @DoNotReadRestOfFile
Prevents the rest of the file from being read by the parser. Useful for unfinished or temporary files.
#! This will appear in the manual
#! @DoNotReadRestOfFile
#! This will not appear in the manual.
2.2-14 @BeginChunk name, @EndChunk, and @InsertChunk name
Text inside a @BeginChunk / @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 @InsertChunk name command. If you do not provide an @EndChunk, the chunk ends at the end of the file.
#! @BeginChunk MyChunk
#! Hello, world.
#! @EndChunk
#! @InsertChunk MyChunk
## The text "Hello, world." is inserted right before this.
You can use this to define an example like this in one file:
And then later, insert the example in a different file, like this:
#! @InsertChunk Example_Symmetric_Group
2.2-15 @BeginCode name, @EndCode, and @InsertCode name
Inserts the text between @BeginCode and @EndCode verbatim at the point where @InsertCode is called. This is useful to insert code excerpts directly into the manual.
#! @BeginCode Increment
i := i + 1;
#! @EndCode
#! @InsertCode Increment
## Code is inserted here.
2.2-16 @LatexOnly text, @BeginLatexOnly, and @EndLatexOnly
Code inserted between @BeginLatexOnly and @EndLatexOnly or after @LatexOnly is only inserted in the PDF version of the manual or worksheet. It can hold arbitrary LaTeX-commands.
2.2-17 @NotLatex text, @BeginNotLatex, and @EndNotLatex
Code inserted between @BeginNotLatex and @EndNotLatex or after @NotLatex is inserted in the HTML and text versions of the manual or worksheet, but not in the PDF version.
#! @BeginNotLatex
#! For further information see the PDF version of this manual.
#! @EndNotLatex
#! @NotLatex For further information see the PDF version of this manual.
2.3 Title page commands
The following commands can be used to add the corresponding parts to the title page of the document which generated by AutoDoc if scaffolding is enabled.
@Title
@Subtitle
@Version
@TitleComment
@Author
@Date
@Address
@Abstract
@Copyright
@Acknowledgements
@Colophon
Those add the following lines at the corresponding point of the title page. Please note that many of those things can be (better) extracted from the PackageInfo.g. In case you set some of those, the extracted or in scaffold defined items will be overwritten. While this is not very useful for documenting packages, they are necessary for worksheets created with AutoDocWorksheet (3.1-1), since worksheets do not have a PackageInfo.g file from which this information could be extracted.
2.4 Plain text files
Files that have the suffix .autodoc and are listed in the autodoc.files option of AutoDoc (4.1-1), resp. are contained in one of the directories listed in autodoc.scan_dirs, are treated as AutoDoc plain text files. These work exactly like AutoDoc comments, except that lines do not need to (and in fact, should not) start with #!.
2.5 Grouping
In 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 @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 @BeginGroup / @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 @Group command in the AutoDoc comment of an arbitrary declaration, at any time.
The following code
#! @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 );
produces the following:
2.5-1 A family of operations
‣ FirstOperation( arg )
( operation )
‣ SecondOperation( arg1, arg2 )
( operation )
‣ ThirdOperation( arg1, arg2 )
( operation )
First sentence. Second sentence. Third sentence.
2.6 Level
Levels can be set to not write certain parts in the manual by default. Every entry has by default the level 0. The command @Level can be used to set the level of the following part to a higher level, for example 1, and prevent it from being printed to the manual by default. However, if one sets the level to a higher value in the autodoc option of AutoDoc, the parts will be included in the manual at the specific place.
#! This text will be printed to the manual.
#! @Level 1
#! This text will be printed to the manual if created with level 1 or higher.
#! @Level 2
#! This text will be printed to the manual if created with level 2 or higher.
#! @ResetLevel
#! This text will be printed to the manual.
2.7 Markdown-like formatting of text in AutoDoc
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.
2.7-1 Lists
One can create lists of items by beginning a new line with *, +, -, 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:
#! 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.
This is the output: 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. The *, -, and + are fully interchangeable and can even be used mixed, but this is not recommended.
2.7-2 Math modes
One can start an inline formula with a $, and also end it with $, just like in LaTeX. This will translate into GAPDocs inline math environment. For display mode one can use $$, also like LaTeX.
#! This is an inline formula: $1+1 = 2$.
#! This is a display formula:
#! $$ \sum_{i=1}^n i. $$
produces the following output: This is an inline formula: \(1+1 = 2\). This is a display formula:
\[ \sum_{i=1}^n i. \]
2.7-3 Emphasize
One can emphasize text by using two asterisks (**) or two underscores (__) at the beginning and the end of the text which should be emphasized. Example:
#! **This** is very important.
#! This is __also important__.
#! **Naturally, more than one line
#! can be important.**
This produces the following output: This is very important. This is also important. Naturally, more than one line can be important.
2.7-4 Inline code
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:
#! Call function `foobar()` at the start.
This produces the following output: Call function foobar() at the start.
2.8 Deprecated commands
The following commands used to be supported, but are not anymore.
@EndSection
You can simply remove any use of this, AutoDoc ends sections automatically at the start of any new section or chapter.
@EndSubsection
You can simply remove any use of this, AutoDoc ends subsections automatically at the start of any new subsection, section or chapter.
@BeginAutoDoc and @EndAutoDoc
It suffices to prepend each declaration that is meant to be appear in the manual with a minimal AutoDoc comment #!.
@BeginSystem name, @EndSystem, and @InsertSystem name
Please use the chunk commands from subsection 2.2-14 instead.
AutoDoc-2025.10.16/doc/_Chapter_AutoDoc.xml 0000644 0001751 0001751 00000042124 15074117054 017515 0 ustar runner runner
AutoDocThe AutoDoc() functionnothing
This is the main function of the &AutoDoc; package. It can perform
any combination of the following tasks:
It can (re)generate a scaffold for your package manual.
That is, it can produce two XML files in &GAPDoc; format to be used as part
of your manual: First, a file named doc/PACKAGENAME.xml
(with your package's name substituted) 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 &AutoDoc; as well
as additional files created by other means), tells &GAPDoc;
to generate a table of contents and an index, and more.
Secondly, it creates a file 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 PackageInfo.g.
It can scan your package for &AutoDoc; based documentation (by using &AutoDoc;
tags and the Autodoc command.
This will
produce further XML files to be used as part of the package manual.
It can use &GAPDoc; to generate PDF, text and HTML (with
MathJaX enabled) documentation from the &GAPDoc; XML files it
generated as well as additional such files provided by you. For
this, it invokes
to convert the XML sources, and it also instructs &GAPDoc; to copy
supplementary files (such as CSS style files) into your doc directory
(see ).
For more information and some examples, please refer to Chapter .
The parameters have the following meanings:
packageOrDirectory
The purpose of this parameter is twofold: to determine the package
directory in which &AutoDoc; will operate, and to find the metadata
concerning the package being documented. The parameter is either a
string, an IsDirectory object, or omitted.
If it is a string, &AutoDoc; interprets it as the name of a
package, uses the metadata of the first package known to &GAP;
with that name, and uses the InstallationPath specified in that
metadata as the package directory. If packageOrDirectory is
an IsDirectory object, this is used as package directory;
if the argument is omitted, then the current directory is used.
In the last two cases, the specified directory must contain a
PackageInfo.g file, and &AutoDoc; extracts all needed metadata
from that. The 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.
Note that when using AutoDocWorksheet (see
), there is
no parameter corresponding to packageOrDirectory and so the
package directory is always the current directory, and
there is no metadata.
optrecoptrec can be a record with some additional options.
The following are currently supported:
dir
This should either be a string, in which case it must be a path
relative to the specified package directory, or a
Directory() object. (Thus, the only way to designate an
absolute directory is with a Directory() object.) This
option specifies where the package documentation
(e.g. the &GAPDoc; XML or the manual PDF, etc.) files are stored
and/or will be generated.
Default value: "doc/".scaffold
This controls whether and how to generate scaffold XML files
for the package documentation.
The value should be either true, false or a
record. If it is a record or true (the latter is
equivalent to specifying an empty record), then this feature is
enabled. It is also enabled if opt.scaffold is missing but the
package's info record in PackageInfo.g has an AutoDoc entry.
In all other cases (in particular if opt.scaffold is
false), scaffolding is disabled.
If scaffolding is enabled, and PackageInfo.AutoDoc exists, then it is
assumed to be a record, and its contents are used as default values for
the scaffold settings.
If opt.scaffold is a record, it may contain the following entries.
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 &AutoDoc; to document
your operations with &AutoDoc; comments,
you can add _AutoDocMainFile.xml to this list
to control at which point the documentation produced by &AutoDoc;
is inserted. If you do not do this, it will be added after the last
of your own XML files.
index
By default, the scaffold creates an index. If you do not want an index,
set this to false.
appendix
This entry is similar to opt.scaffold.includes but is used
to specify files to include after the main body of the manual,
i.e. typically appendices.
bib
The name of a bibliography file, in BibTeX or XML format.
If this key is not set, but there is a file doc/PACKAGENAME.bib
then it is assumed that you want to use this as your bibliography.
entities
A record whose keys are taken as entity names, set to the corresponding
(string) values. For example, if you pass the record SomePackage,
SomePackage",
RELEASEYEAR := "2015" )]]>
then the following entity definitions are added to the XML preamble:
SomePackage'>
]]>
This allows you to write &SomePackage; and &RELEASEYEAR;
in your documentation, which will be replaced by respective values specified
in the entities definition.
TitlePage
A record whose entries are used to embellish the generated title page
for the package manual with extra information, such as a copyright
statement or acknowledgments. To this end, the names of the record
components are used as XML element names, and the values of the
components are outputted as content of these XML elements. For
example, you could pass the following record to set a custom
acknowledgements text:
For a list of valid entries in the title page, please refer to the
&GAPDoc; manual, specifically section .
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 &AutoDoc; to generate a title page for you, you can set this
option to falsedocument_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;.
latex_header_file
Replaces the standard header from &GAPDoc; completely with the header in this &LaTeX; file.
Please be careful here, and look at &GAPDoc;'s latexheader.tex file for an example.
autodoc
This controls whether and how to generate additional XML documentation files
by scanning for &AutoDoc; documentation comments.
The value should be either true, false or a
record. If it is a record or true (the latter is
equivalent to specifying an empty record), then this feature is
enabled. It is also enabled if opt.autodoc is missing but the
package depends (directly) on the &AutoDoc; package.
In all other cases (in particular if opt.autodoc is
false), this feature is disabled.
If opt.autodoc is a record, it may contain the following entries.
files
A list of files (given by paths relative to the package directory)
to be scanned for &AutoDoc; documentation comments.
Usually it is more convenient to use autodoc.scan_dirs, see below.
scan_dirs
A list of subdirectories of the package directory (given as relative paths)
which &AutoDoc; then scans for .gi, .gd, .g, and .autodoc files; all of these files
are then scanned for &AutoDoc; documentation comments.
Default value: [ ".", "gap", "lib", "examples", "examples/doc" ].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.
gapdoc
This controls whether and how to invoke &GAPDoc; to create HTML, PDF and text
files from your various XML files.
The value should be either true, false or a
record. If it is a record or true (the latter is
equivalent to specifying an empty record), then this feature is
enabled. It is also enabled if opt.gapdoc is missing.
In all other cases (in particular if opt.gapdoc is
false), this feature is disabled.
If opt.gapdoc is a record, it may contain the following entries.
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.
Default value: PACKAGENAME.xml.
files
A list of files (given by paths relative to the package directory)
to be scanned for &GAPDoc; documentation comments.
Usually it is more convenient to use gapdoc.scan_dirs, see below.
scan_dirs
A list of subdirectories of the package directory (given as relative paths)
which &AutoDoc; then scans for .gi, .gd and .g files; all of these files
are then scanned for &GAPDoc; documentation comments.
Default value: [ ".", "gap", "lib", "examples", "examples/doc" ].LaTeXOptions
Must be a record with entries which can be understood by
. Each entry can be a
string, which will be given to &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 &GAPDoc;
as option with the name of the entry.
gap_root_relative_path
Either a boolean, or a string containing a relative path.
By default (if this option is not set, or is set to false),
references in the generated documentation referring to external documentation
(such as the &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 &GAP; package.
Thus, if a relative path is provided via this option (or if it is set to true,
in which case the relative path ../../.. is used), then &AutoDoc;
and &GAPDoc; attempt to replace all absolute paths in references to &GAP;
manuals by paths based on this relative path.
On a technical level, &AutoDoc; passes the relative path to the
gaproot parameter of extract_examples
Either true or a record.
If set to true, then all manual examples are extracted and placed
into files tst/PACKAGENAME01.tst, tst/PACKAGENAME02.tst, ...
and so on, with one file for each chapter. For chapters with no examples,
no file is created.
As a record, the entry can have the following entries itself, to specify some options.
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, &AutoDoc; passes the value to the
units parameter of .
skip_empty_in_numbering
If set to 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 tst/PACKAGENAME01.tst. If this
option is set to false, then the chapter numbers are
used to generate the filenames; so the examples for chapter 2
would be put into the file tst/PACKAGENAME02.tst.
Info class for the 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,
SetInfoLevel(InfoPackageManager, 0). Default value 1.
Examples
Some basic examples for using AutoDoc were already shown in
Chapter .
AutoDoc-2025.10.16/doc/chap0_mj.html 0000644 0001751 0001751 00000040302 15074117054 016173 0 ustar runner runner
GAP (AutoDoc) - Contents
AutoDoc-2025.10.16/doc/chapBib.txt 0000644 0001751 0001751 00000000467 15074117054 015725 0 ustar runner runner
[1XReferences[101X
[[20XLN12[120X] [16XLübeck, F. and Neunhöffer, M.[116X, [17XGAPDoc (Version 1.5.1)[117X, RWTH Aachen
(2012), ( GAP package,
http://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc/index.html ).
[32X
AutoDoc-2025.10.16/doc/AutoDoc.tex 0000644 0001751 0001751 00000241204 15074117054 015710 0 ustar runner runner % generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[a4paper,11pt]{report}
\usepackage{a4wide}
\newcommand{\bbZ}{\mathbb{Z}}
\usepackage[top=37mm,bottom=37mm,left=27mm,right=27mm]{geometry}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage[utf8]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{color}
\definecolor{FireBrick}{rgb}{0.5812,0.0074,0.0083}
\definecolor{RoyalBlue}{rgb}{0.0236,0.0894,0.6179}
\definecolor{RoyalGreen}{rgb}{0.0236,0.6179,0.0894}
\definecolor{RoyalRed}{rgb}{0.6179,0.0236,0.0894}
\definecolor{LightBlue}{rgb}{0.8544,0.9511,1.0000}
\definecolor{Black}{rgb}{0.0,0.0,0.0}
\definecolor{linkColor}{rgb}{0.0,0.0,0.554}
\definecolor{citeColor}{rgb}{0.0,0.0,0.554}
\definecolor{fileColor}{rgb}{0.0,0.0,0.554}
\definecolor{urlColor}{rgb}{0.0,0.0,0.554}
\definecolor{promptColor}{rgb}{0.0,0.0,0.589}
\definecolor{brkpromptColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapinputColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapoutputColor}{rgb}{0.0,0.0,0.0}
%% for a long time these were red and blue by default,
%% now black, but keep variables to overwrite
\definecolor{FuncColor}{rgb}{0.0,0.0,0.0}
%% strange name because of pdflatex bug:
\definecolor{Chapter }{rgb}{0.0,0.0,0.0}
\definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064}
\usepackage{fancyvrb}
\usepackage{mathptmx,helvet}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage[
pdftex=true,
bookmarks=true,
a4paper=true,
pdftitle={Written with GAPDoc},
pdfcreator={LaTeX with hyperref package / GAPDoc},
colorlinks=true,
backref=page,
breaklinks=true,
linkcolor=linkColor,
citecolor=citeColor,
filecolor=fileColor,
urlcolor=urlColor,
pdfpagemode={UseNone},
]{hyperref}
\newcommand{\maintitlesize}{\fontsize{50}{55}\selectfont}
% write page numbers to a .pnr log file for online help
\newwrite\pagenrlog
\immediate\openout\pagenrlog =\jobname.pnr
\immediate\write\pagenrlog{PAGENRS := [}
\newcommand{\logpage}[1]{\protect\write\pagenrlog{#1, \thepage,}}
%% were never documented, give conflicts with some additional packages
\newcommand{\GAP}{\textsf{GAP}}
%% nicer description environments, allows long labels
\usepackage{enumitem}
\setdescription{style=nextline}
%% depth of toc
\setcounter{tocdepth}{1}
%% command for ColorPrompt style examples
\newcommand{\gapprompt}[1]{\color{promptColor}{\bfseries #1}}
\newcommand{\gapbrkprompt}[1]{\color{brkpromptColor}{\bfseries #1}}
\newcommand{\gapinput}[1]{\color{gapinputColor}{#1}}
\begin{document}
\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\mbox{}\vfill
\begin{center}{\maintitlesize \textbf{ AutoDoc \mbox{}}}\\
\vfill
\hypersetup{pdftitle= AutoDoc }
\markright{\scriptsize \mbox{}\hfill AutoDoc \hfill\mbox{}}
{\Huge \textbf{ Generate documentation from \textsf{GAP} source code \mbox{}}}\\
\vfill
{\Huge 2025.10.16 \mbox{}}\\[1cm]
{ 16 October 2025 \mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\Large \textbf{ Sebastian Gutsche\\
\mbox{}}}\\
{\Large \textbf{ Max Horn\\
\mbox{}}}\\
\hypersetup{pdfauthor= Sebastian Gutsche\\
; Max Horn\\
}
\end{center}\vfill
\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{ Sebastian Gutsche\\
} Email: \href{mailto://gutsche@mathematik.uni-siegen.de} {\texttt{gutsche@mathematik.uni\texttt{\symbol{45}}siegen.de}}\\
Homepage: \href{https://algebra.mathematik.uni-siegen.de/gutsche/} {\texttt{https://algebra.mathematik.uni\texttt{\symbol{45}}siegen.de/gutsche/}}\\
Address: \begin{minipage}[t]{8cm}\noindent
Department Mathematik\\
Universit{\"a}t Siegen\\
Walter\texttt{\symbol{45}}Flex\texttt{\symbol{45}}Stra{\ss}e 3\\
57072 Siegen\\
Germany\\
\end{minipage}
}\\
{\mbox{}\\
\small \noindent \textbf{ Max Horn\\
} Email: \href{mailto://mhorn@rptu.de} {\texttt{mhorn@rptu.de}}\\
Homepage: \href{https://www.quendi.de/math} {\texttt{https://www.quendi.de/math}}\\
Address: \begin{minipage}[t]{8cm}\noindent
Fachbereich Mathematik\\
RPTU Kaiserslautern\texttt{\symbol{45}}Landau\\
Gottlieb\texttt{\symbol{45}}Daimler\texttt{\symbol{45}}Stra{\ss}e 48\\
67663 Kaiserslautern\\
Germany\\
\end{minipage}
}\\
\end{titlepage}
\newpage\setcounter{page}{2}
{\small
\section*{Abstract}
\logpage{[ 0, 0, 1 ]}
\textsf{AutoDoc} is a \textsf{GAP} package whose purpose is to aid \textsf{GAP} package authors in creating and maintaining the documentation of their
packages. \mbox{}}\\[1cm]
{\small
\section*{Copyright}
\logpage{[ 0, 0, 2 ]}
{\copyright} 2012\texttt{\symbol{45}}2022 by Sebastian Gutsche and Max Horn
This package may be distributed under the terms and conditions of the GNU
Public License Version 2 or (at your option) any later version. \mbox{}}\\[1cm]
{\small
\section*{Acknowledgements}
\logpage{[ 0, 0, 3 ]}
This documentation was prepared using the \textsf{GAPDoc} package \cite{GAPDoc}.
\mbox{}}\\[1cm]
\newpage
\def\contentsname{Contents\logpage{[ 0, 0, 4 ]}}
\tableofcontents
\newpage
\chapter{\textcolor{Chapter }{Getting started using \textsf{AutoDoc}}}\label{Tutorials}
\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X7A0D7AA484F466E1}{}
{
\textsf{AutoDoc} is a \textsf{GAP} package which is meant to aid \textsf{GAP} package authors in creating and maintaining the documentation of their
packages. In this capacity it builds upon the \textsf{GAPDoc} package (see \href{https://www.gap-system.org/Packages/gapdoc.html} {\texttt{https://www.gap\texttt{\symbol{45}}system.org/Packages/gapdoc.html}}). As such, it is not a replacement for \textsf{GAPDoc}, but rather complements it.
In this chapter we describe how to get started using \textsf{AutoDoc} for your package. First, we explain in Section \ref{Tut:Scratch} how to write a new package manual from scratch.
Then we show in Section \ref{Tut:IntegrateExisting} how you might benefit from \textsf{AutoDoc} even if you already have a complete manual written using \textsf{GAPDoc}.
In Section \ref{Tut:Scaffolds}, we explain how you may use \textsf{AutoDoc} to generate a title page and the main XML file for your manual.
Finally, Section \ref{Tut:AutoDocWorksheet}, explains what \textsf{AutoDoc} worksheets are and how to use them.
\section{\textcolor{Chapter }{Creating a package manual from scratch}}\label{Tut:Scratch}
\logpage{[ 1, 1, 0 ]}
\hyperdef{L}{X7BFBC6907B26AA95}{}
{
Suppose your package is already up and running, but so far has no manual. Then
you can rapidly generate a ``scaffold'' for a package manual using the \texttt{AutoDoc} (\ref{AutoDoc}) command like this, while running \textsf{GAP} from within your package's directory (the one containing the \texttt{PackageInfo.g} file):
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
LoadPackage( "AutoDoc" );
AutoDoc( rec( scaffold := true ) );
\end{Verbatim}
This first reads the \texttt{PackageInfo.g} file from the current directory. It extracts information about the package
from it (such as its name and version, see Section \ref{Tut:Scaffolds:Title}). It then creates two XML files \texttt{doc/NAME{\textunderscore}OF{\textunderscore}YOUR{\textunderscore}PACKAGE.xml} and \texttt{doc/title.xml} inside the package directory. Finally, it runs \textsf{GAPDoc} on them to produce a nice initial PDF and HTML version of your fresh manual.
To ensure that the \textsf{GAP} help system picks up your package manual, you should also add something like
the following to your \texttt{PackageInfo.g}:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
PackageDoc := rec(
BookName := ~.PackageName,
ArchiveURLSubset := ["doc"],
HTMLStart := "doc/chap0.html",
PDFFile := "doc/manual.pdf",
SixFile := "doc/manual.six",
LongTitle := ~.Subtitle,
),
\end{Verbatim}
Congratulations, your package now has a minimal working manual. Of course it
will be mostly empty for now, but it already should contain some useful
information, based on the data in your \texttt{PackageInfo.g}. This includes your package's name, version and description as well as
information about its authors. And if you ever change the package data, (e.g.
because your email address changed), just re\texttt{\symbol{45}}run the above
command to regenerate the two main XML files with the latest information.
Next of course you need to provide actual content (unfortunately, we were not
yet able to automate \emph{that} for you, more research on artificial intelligence is required). To add more
content, you have several options: You could add further \textsf{GAPDoc} XML files containing extra chapters, sections and so on. Or you could use
classic \textsf{GAPDoc} source comments. For details on either, please refer to (\textbf{GAPDoc: Distributing a Document into Several Files}), as well as Section \ref{Tut:IntegrateExisting} of this manual on how to teach the \texttt{AutoDoc} (\ref{AutoDoc}) command to include this extra documentation. Or you could use the special
documentation facilities \textsf{AutoDoc} provides (see Section \ref{Tut:AdvancedAutoDoc}).
You will probably want to re\texttt{\symbol{45}}run the \texttt{AutoDoc} (\ref{AutoDoc}) command frequently, e.g. whenever you modified your documentation or your \texttt{PackageInfo.g}. To make this more convenient and reproducible, we recommend putting its
invocation into a file \texttt{makedoc.g} in your package \index{makedoc.g@\texttt{makedoc.g}} directory, with content based on the following example:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
LoadPackage( "AutoDoc" );
AutoDoc( rec( autodoc := true ) );
QUIT;
\end{Verbatim}
Then you can regenerate the package manual from the command line with the
following command, executed from within in the package directory:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
gap makedoc.g
\end{Verbatim}
}
\section{\textcolor{Chapter }{Documenting code with \textsf{AutoDoc}}}\label{Tut:AdvancedAutoDoc}
\logpage{[ 1, 2, 0 ]}
\hyperdef{L}{X87A00EED866E22E8}{}
{
To get one of your global functions, operations, attributes etc. to appear in
the package manual, simply insert an \textsf{AutoDoc} comment of the form \texttt{\#!} directly in front of it. For example:
\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=]
#!
DeclareOperation( "ToricVariety", [ IsConvexObject ] );
\end{Verbatim}
This tiny change is already sufficient to ensure that the operation appears in
the manual. In general, you will want to add further information about the
operation, such as in the following example:
\begin{Verbatim}[commandchars=|BE,fontsize=\small,frame=single,label=]
#! @Arguments conv
#! @Returns a toric variety
#! @Description
#! Creates a toric variety out
#! of the convex object conv.
DeclareOperation( "ToricVariety", [ IsConvexObject ] );
\end{Verbatim}
For a thorough description of what you can do with \textsf{AutoDoc} documentation comments, please refer to chapter \ref{Comments}.
Suppose you have not been using \textsf{GAPDoc} before but instead used the process described in section \ref{Tut:Scratch} to create your manual. Then the following \textsf{GAP} command will regenerate the manual and automatically include all newly
documented functions, operations etc.:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
LoadPackage( "AutoDoc" );
AutoDoc( rec( scaffold := true,
autodoc := true ) );
\end{Verbatim}
If you are not using the scaffolding feature, e.g. because you already have an
existing \textsf{GAPDoc} based manual, then you can still use \textsf{AutoDoc} documentation comments. Just make sure to first edit the main XML file of your
documentation, and insert the line
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
<#Include SYSTEM "_AutoDocMainFile.xml">
\end{Verbatim}
in a suitable place. This means that you can mix \textsf{AutoDoc} documentation comment freely with your existing documentation; you can even
still make use of any existing \textsf{GAPDoc} documentation comments in your code. The following command should be useful
for you in this case; it still scans the package code for \textsf{AutoDoc} documentation comments and the runs \textsf{GAPDoc} to produce HTML and PDF output, but does not touch your documentation XML
files otherwise.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
LoadPackage( "AutoDoc" );
AutoDoc( rec( autodoc := true ) );
\end{Verbatim}
}
\section{\textcolor{Chapter }{Using \textsf{AutoDoc} in an existing \textsf{GAPDoc} manual}}\label{Tut:IntegrateExisting}
\logpage{[ 1, 3, 0 ]}
\hyperdef{L}{X7FA614637B807F4D}{}
{
Even if you already have an existing \textsf{GAPDoc} manual, it might be interesting for you to use \textsf{AutoDoc} for two purposes:
First off, with \textsf{AutoDoc} it is very convenient to regenerate your documentation.
Secondly, the scaffolding feature which generates a title page with all the
metadata of your package in a uniform way is very handy. The somewhat tedious
process of keeping your title page in sync with your \texttt{PackageInfo.g} is fully automated this way (including the correct version, release data,
author information and so on).
There are various examples of packages using \textsf{AutoDoc} for this purpose only, e.g. \textsf{io} and \textsf{orb}.
\subsection{\textcolor{Chapter }{Using \textsf{AutoDoc} on a complete \textsf{GAPDoc} manual}}\label{Tut:IntegrateExisting:EverythingThere}
\logpage{[ 1, 3, 1 ]}
\hyperdef{L}{X7F3CEB097AF47C1E}{}
{
Suppose you already have a complete XML manual, with some main and title XML
files and some documentation for operations distributed over all your \texttt{.g}, \texttt{.gd}, and \texttt{.gi} files. Suppose the main XML file is named \texttt{PACKAGENAME.xml} and is in the \texttt{/doc} subdirectory of your package. Then you can rebuild your manual by executing
the following two \textsf{GAP} commands from a \textsf{GAP} session started in the root directory of your package:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
LoadPackage( "AutoDoc" );
AutoDoc( );
\end{Verbatim}
In contrast, the \textsf{RingsForHomalg} package currently uses essentially the following code in its \texttt{makedoc.g} file to achieve the same result:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
LoadPackage( "GAPDoc" );
SetGapDocLaTeXOptions( "utf8" );
bib := ParseBibFiles( "doc/RingsForHomalg.bib" );
WriteBibXMLextFile( "doc/RingsForHomalgBib.xml", bib );
list := [
"../gap/RingsForHomalg.gd",
"../gap/RingsForHomalg.gi",
"../gap/Singular.gi",
"../gap/SingularBasic.gi",
"../examples/RingConstructionsExternalGAP.g",
"../examples/RingConstructionsSingular.g",
"../examples/RingConstructionsMAGMA.g",
"../examples/RingConstructionsMacaulay2.g",
"../examples/RingConstructionsSage.g",
"../examples/RingConstructionsMaple.g",
];
MakeGAPDocDoc( "doc", "RingsForHomalg", list, "RingsForHomalg" );
GAPDocManualLab( "RingsForHomalg" );
\end{Verbatim}
Note that in particular, you do not have to worry about keeping a list of your
implementation files up\texttt{\symbol{45}}to\texttt{\symbol{45}}date.
But there is more. \textsf{AutoDoc} can create \texttt{.tst} files from the examples in your manual to test your package. This can be
achieved via
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
LoadPackage( "AutoDoc" );
AutoDoc( rec( extract_examples := true ) );
\end{Verbatim}
Now files \texttt{PACKAGENAME01.tst}, \texttt{PACKAGENAME02.tst} and so appear in the \texttt{tst/} subdirectory of your package, and can be tested as usual using \texttt{Test} (\textbf{Reference: Test}) respectively \texttt{TestDirectory} (\textbf{Reference: TestDirectory}). }
\subsection{\textcolor{Chapter }{Setting different \textsf{GAPDoc} options}}\label{Tut:IntegrateExisting:GapDocOptions}
\logpage{[ 1, 3, 2 ]}
\hyperdef{L}{X7D0DDF2284F2D24A}{}
{
Sometimes, the default values for the \textsf{GAPDoc} command used by \textsf{AutoDoc} may not be suitable for your manual.
Suppose your main XML file is \emph{not} named \texttt{PACKAGENAME.xml}, but rather something else, e.g. \texttt{main.xml}. Then you can tell \textsf{AutoDoc} to use this file as the main XML file via
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
LoadPackage( "AutoDoc" );
AutoDoc( rec( gapdoc := rec( main := "main" ) ) );
\end{Verbatim}
As explained above, by default \textsf{AutoDoc} scans all \texttt{.g}, \texttt{.gd} and \texttt{.gi} files it can find inside of your package root directory, and in the
subdirectories \texttt{gap}, \texttt{lib}, \texttt{examples} and \texttt{examples/doc} as well. If you keep source files with documentation in other directories, you
can adjust the list of directories AutoDoc scans via the \texttt{scan{\textunderscore}dirs} option. The following example illustrates this by instructing \textsf{AutoDoc} to only search in the subdirectory \texttt{package{\textunderscore}sources} of the packages root directory.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
LoadPackage( "AutoDoc" );
AutoDoc( rec( gapdoc := rec( scan_dirs := [ "package_sources" ] ) ) );
\end{Verbatim}
You can also specify an explicit list of files containing documentation, which
will be searched in addition to any files located within the scan directories:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
LoadPackage( "AutoDoc" );
AutoDoc( rec( gapdoc := rec( files := [ "path/to/some/hidden/file.gds" ] ) ) );
\end{Verbatim}
Giving such a file does not prevent the standard \texttt{scan{\textunderscore}dirs} from being scanned for other files.
Next, \textsf{GAPDoc} supports the documentation to be built with relative paths. This means, links
to manuals of other packages or the \textsf{GAP} library will not be absolute, but relative from your documentation. This can
be particularly useful if you want to build a release tarball or move your \textsf{GAP} installation around later. Suppose you are starting \textsf{GAP} in the root path of your package as always, and the standard call of \texttt{AutoDoc} (\ref{AutoDoc}) will then build the documentation in the \texttt{doc} subdirectory of your package. From this directory, the gap root directory has
the relative path \texttt{../../..}. Then you can enable the relative paths by
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
LoadPackage( "AutoDoc" );
AutoDoc( rec( gapdoc := rec( gap_root_relative_path := "../../.." ) ) );
\end{Verbatim}
or, since \texttt{../../..} is the standard option for \texttt{gap{\textunderscore}root{\textunderscore}relative{\textunderscore}path}, by
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
LoadPackage( "AutoDoc" );
AutoDoc( rec( gapdoc := rec( gap_root_relative_path := true ) ) );
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{ Checklist for converting an existing \textsf{GAPDoc} manual to use \textsf{AutoDoc} }}\label{Tut:Checklist}
\logpage{[ 1, 3, 3 ]}
\hyperdef{L}{X83448D91868D7994}{}
{
Here is a checklist for authors of a package \textsf{PackageName}, \emph{which already has a \textsf{GAPDoc} based manual}, who wish to use \textsf{AutoDoc} to build the manual from now on. We assume that the manual is currently built
by reading a file \texttt{makedoc.g} and that the main \texttt{.xml} file is named \texttt{manual.xml}.
The files \texttt{PackageInfo.g}, \texttt{makedoc.g}, \texttt{doc/title.xml} and \texttt{doc/PackageName.xml} (if it exists) will be altered by this procedure, so it may be wise to keep
backup copies.
You should have copies of the \textsf{AutoDoc} files \texttt{PackageInfo.g} and \texttt{makedoc.g} to hand when reading these instructions.
\begin{itemize}
\item Copy \texttt{AutoDoc/makedoc.g} to \texttt{PackageName/makedoc.g}.
\item Edit \texttt{PackageName/makedoc.g} as follows.
\begin{itemize}
\item Change the header comment to match other files in your package.
\item After \texttt{LoadPackage("AutoDoc");} add \texttt{LoadPackage("PackageName");}.
\item In the \texttt{AutoDoc} record delete \texttt{autodoc := true;}.
\item \index{Scaffold record in makedoc.g@} In the \texttt{scaffold} record change the \texttt{includes} list to be the list of your \texttt{.xml} files that are contained in \texttt{manual.xml}.
\item \index{Bibliography field in makedoc.g@} If you do not have a bibliography you may delete the \texttt{bib := "bib.xml",} field in the scaffold. Otherwise, edit the file name if you have a different
file. If you only have a \texttt{.bib} file (\texttt{manual.bib} or \texttt{bib.xml.bib} say) you should rename this file \texttt{PackageName.bib}.
\item \index{LaTeXOptions record in makedoc.g@} In the \texttt{LaTeXOptions} record, which is in the \texttt{gapdoc} record, enter any {\LaTeX} \texttt{newcommands} previously in \texttt{manual.xml}. (If there are none you may safely delete this record.) To illustrate this
option, the \textsf{AutoDoc} file \texttt{makedoc.g} defines the command \texttt{\texttt{\symbol{92}}bbZ} by \texttt{\texttt{\symbol{92}}newcommand\texttt{\symbol{123}}\texttt{\symbol{92}}bbZ\texttt{\symbol{125}}\texttt{\symbol{123}}\texttt{\symbol{92}}mathbb\texttt{\symbol{123}}Z\texttt{\symbol{125}}\texttt{\symbol{125}}}, which may be used to produce the {\LaTeX} formula $f : \bbZ^2 \to \bbZ$. However, note that this only works in the PDF version of the file.
\end{itemize}
\item Now edit \texttt{PackageName/PackageInfo.g} as follows.
\begin{itemize}
\item Delete any \texttt{PKGVERSIONDATA} chunk that may be there. One reason for converting your manual to use \textsf{AutoDoc} is to stop using entities such as \texttt{PACKAGENAMEVERSION}.
\item Copy the \texttt{AutoDoc} record from \texttt{AutoDoc/PackageInfo.g} to the end of your file (just before the final \texttt{"));"}.
\item \index{Copyright field in PackageInfo.g@} \index{Abstract field in PackageInfo.g@} \index{Acknowledgements field in PackageInfo.g@} Replace the \texttt{Copyright}, \texttt{Abstract} and \texttt{Acknowledgements} fields of the \texttt{TitlePage} record with the corresponding material from your \texttt{manual.xml}. (If you do not have an abstract, then delete the \texttt{Abstract} field, etc.)
\item \index{Entities record in makedoc.g@} In the \texttt{entities} record enter any entities previously stored in your \texttt{manual.xml}. (Again, if you have none, you may safely delete this record.) To illustrate
this option the \textsf{AutoDoc} file \texttt{PackageInfo.g} defines entities for the names of packages \textsf{io} and \textsf{PackageName}.
\end{itemize}
\item If you are using a GitHub repository, as well as running "\texttt{git add}" on files \texttt{makedoc.g}, \texttt{PackageInfo.g} and \texttt{doc/PackageName.bib}, you should run "\texttt{git rm \texttt{\symbol{45}}f}" on files \texttt{doc/manual.xml}, and \texttt{doc/title.xml}.
\end{itemize}
You should now be ready to run \textsf{GAP} and \texttt{Read("makedoc.g");} in your package root directory. }
}
\section{\textcolor{Chapter }{Scaffolds}}\label{Tut:Scaffolds}
\logpage{[ 1, 4, 0 ]}
\hyperdef{L}{X8524193D824CDE0D}{}
{
\subsection{\textcolor{Chapter }{Generating a title page}}\label{Tut:Scaffolds:Title}
\logpage{[ 1, 4, 1 ]}
\hyperdef{L}{X7CF22DE28478316F}{}
{
For most (if not all) \textsf{GAP} packages, the title page of the package manual lists information such as the
release date, version, names and contact details of the authors, and so on.
All this data is also contained in your \texttt{PackageInfo.g}, and whenever you make a change to that file, there is a risk that you forget
to update your manual to match. And even if you don't forget it, you of course
have to spend some time to adjust the manual. \textsf{GAPDoc} can help to a degree with this via entities. Thus, you will sometimes see code
like this in \texttt{PackageInfo.g} files:
\begin{Verbatim}[commandchars=@|B,fontsize=\small,frame=single,label=]
Version := "1.2.3",
Date := "20/01/2015",
## <#GAPDoc Label="PKGVERSIONDATA">
##
##
##
## <#/GAPDoc>
\end{Verbatim}
However, it is still easy to forget both of these versions. And it doesn't
solve the problem of updating package authors addresses. Neither of these is a
big issue, of course, but there have been plenty examples in the past where
people forget either of these two things, and it can be slightly embarrassing.
It may even require you to make a new release just to fix the issue, which in
our opinion is a sad waste of your valuable time.
So instead of worrying about manually synchronising these things, you can
instruct \textsf{AutoDoc} to generate a title page for your manual based on the information in your \texttt{PackageInfo.g}. The following commands do just that (in addition to building your manual),
by generating a file called \texttt{doc/title.xml}.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
LoadPackage( "AutoDoc" );
AutoDoc( rec( scaffold := rec( MainPage := false ) ) );
\end{Verbatim}
Note that this only outputs \texttt{doc/title.xml} but does not touch any other files of your documentation. In particular, you
need to explicitly include \texttt{doc/title.xml} from your main XML file.
However, you can also tell \textsf{AutoDoc} to maintain the main XML file for you, in which case this is automatic. In
fact, this is the default if you enable scaffolding; the above example command
explicitly told \textsf{AutoDoc} not to generate a main page. }
\subsection{\textcolor{Chapter }{Generating the main XML file}}\label{Tut:Scaffolds:Main}
\logpage{[ 1, 4, 2 ]}
\hyperdef{L}{X7CD72CC780874FD5}{}
{
The following generates a main XML file for your documentation in addition to
the title page. The main XML file includes the title page by default, as well
as any documentation generated from \textsf{AutoDoc} documentation comments.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
LoadPackage( "AutoDoc" );
AutoDoc( rec( scaffold := true ) );
\end{Verbatim}
You can instruct \textsf{AutoDoc} to include additional XML files by giving it a list of filenames, as in the
following example:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
LoadPackage( "AutoDoc" );
AutoDoc(rec(
scaffold := rec(
includes := [ "somefile.xml", "anotherfile.xml" ]
)
));
\end{Verbatim}
For more information, please consult the documentation of the \texttt{AutoDoc} (\ref{AutoDoc}) function. }
\subsection{\textcolor{Chapter }{What data is used from \texttt{PackageInfo.g}?}}\label{Tut:PackageInfo}
\logpage{[ 1, 4, 3 ]}
\hyperdef{L}{X799956EA85D3FC15}{}
{
\textsf{AutoDoc} can use data from \texttt{PackageInfo.g} in order to generate a title page. Specifically, the following components of
the package info record are taken into account:
\begin{description}
\item[{PackageName}] This is used to set the \texttt{{\textless}Title{\textgreater}} element of the title page.
\item[{Subtitle}] This is used to set the \texttt{{\textless}Subtitle{\textgreater}} element of the title page.
\item[{Version}] This is used to set the \texttt{{\textless}Version{\textgreater}} element of the title page, with the string ``Version '' prepended.
\item[{Date}] This is used to set the \texttt{{\textless}Date{\textgreater}} element of the title page.
\item[{Persons}] This is used to generate \texttt{{\textless}Author{\textgreater}} elements in the generated title page.
\item[{PackageDoc}] This is a record (or a list of records) which is used to tell the \textsf{GAP} help system about the package manual. Currently \textsf{AutoDoc} extracts the value of the \texttt{PackageDoc.BookName} component and then passes that on to \textsf{GAPDoc} when creating the HTML, PDF and text versions of the manual.
\item[{AutoDoc}] This is a record which can be used to control the scaffolding performed by \textsf{AutoDoc}, specifically to provide extra information for the title page. For example,
you can set \texttt{AutoDoc.TitlePage.Copyright} to a string which will then be inserted on the generated title page. Using
this method you can customize the following title page elements: \texttt{TitleComment}, \texttt{Abstract}, \texttt{Copyright}, \texttt{Acknowledgements} and \texttt{Colophon}.
Note that \texttt{AutoDoc.TitlePage} behaves exactly the same as the \texttt{scaffold.TitlePage} parameter of the \texttt{AutoDoc} (\ref{AutoDoc}) function.
\end{description}
}
}
\section{\textcolor{Chapter }{AutoDoc worksheets}}\label{Tut:AutoDocWorksheet}
\logpage{[ 1, 5, 0 ]}
\hyperdef{L}{X80ED3C2A78146AD1}{}
{
\textsf{AutoDoc} worksheets can be used to create HTML and PDF documents using AutoDoc syntax
and possibly including \textsf{GAP} examples and implementations without having them associated to a package. A
file for a worksheet could look like this:
\begin{Verbatim}[commandchars=|DF,fontsize=\small,frame=single,label=]
#! @Title My first worksheet
#! @Author Charlie Brown
#! @Chapter Some groups
#! @BeginExample
S3 := SymmetricGroup( 3 );;
S4 := SymmetricGroup( 4 );;
#! @EndExample
\end{Verbatim}
Now, one can create a PDF and HTML document, like a package documentation out
of it. Suppose the document above is saved as \texttt{worksheet.g}. Then, when \textsf{GAP} is started in the directory of this file, the command
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
AutoDocWorksheet( "worksheet.g" );
\end{Verbatim}
will create a subdirectory called \texttt{doc} of the current directory in which it will create the documentation. There are
several options to configure the output of the worksheet command, which are
identical to the options of the \texttt{AutoDoc} (\ref{AutoDoc}) command. It is even possible to test the examples in the worksheet using the \texttt{extract{\textunderscore}examples} option of the \texttt{AutoDoc} (\ref{AutoDoc}) command.
Since the worksheets do not have a \texttt{PackageInfo.g} to extract information, all possible tags that \textsf{GAPDoc} supports for the title page can be set into the document. A fully typed title
page can look like this:
\begin{Verbatim}[commandchars=|FH,fontsize=\small,frame=single,label=]
#! @Title My first worksheet
#! @Subtitle Some small examples
#! @Author Charlie Brown
#! @Version 0.1
#! @TitleComment Some worksheet
#! @Date 01/01/2016
#! @Address TU Kaiserslautern
#! @Abstract
#! A worksheet showing some small examples about groups.
#! @Copyright 2016 Charlie Brown
#! @Acknowledgements Woodstock
#! @Colophon Some colophon
#! @Chapter Some groups
#! @BeginExample
S3 := SymmetricGroup( 3 );;
S4 := SymmetricGroup( 4 );;
#! @EndExample
\end{Verbatim}
}
}
\chapter{\textcolor{Chapter }{\textsf{AutoDoc} documentation comments}}\label{Comments}
\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X87668C487B1A2094}{}
{
You can document declarations of global functions and variables, operations,
attributes etc. by inserting \emph{\textsf{AutoDoc}} comments into your sources before these declaration. An \textsf{AutoDoc} comment always starts with \texttt{\#!}. This is also the smallest possible \textsf{AutoDoc} command. If you want your declaration documented, just write \texttt{\#!} at the line before the documentation. For example:
\begin{Verbatim}[commandchars=@|B,fontsize=\small,frame=single,label=]
#!
DeclareOperation( "AnOperation",
[ IsList ] );
\end{Verbatim}
This will produce a manual entry for the operation \texttt{AnOperation}.
Inside of \textsf{AutoDoc} comments, \emph{\textsf{AutoDoc} commands} starting with \texttt{@} can be used to control the output \textsf{AutoDoc} produces.
\section{\textcolor{Chapter }{Documenting declarations}}\logpage{[ 2, 1, 0 ]}
\hyperdef{L}{X871482CE838C68F6}{}
{
In the bare form above, the manual entry for \texttt{AnOperation} will not contain much more than the name of the operation. In order to change
this, there are several commands you can put into the \textsf{AutoDoc} comment before the declaration. Currently, the following commands are
provided:
\subsection{\textcolor{Chapter }{\texttt{@Description \mbox{\texttt{\mdseries\slshape descr}}}}}\label{@Description}
\logpage{[ 2, 1, 1 ]}
\hyperdef{L}{X7F1D85188262A827}{}
{
\index{"@Description@\texttt{"@Description \mbox{\texttt{\mdseries\slshape descr}}}} Adds the text in the following lines of the \textsf{AutoDoc} to the description of the declaration in the manual. Lines are until the next \textsf{AutoDoc} command or until the declaration is reached. }
\subsection{\textcolor{Chapter }{\texttt{@Returns \mbox{\texttt{\mdseries\slshape ret{\textunderscore}val}}}}}\label{@Returns}
\logpage{[ 2, 1, 2 ]}
\hyperdef{L}{X7DCAB2F87E8FAE90}{}
{
\index{"@Returns@\texttt{"@Returns \mbox{\texttt{\mdseries\slshape ret{\textunderscore}val}}}} The string \mbox{\texttt{\mdseries\slshape ret{\textunderscore}val}} is added to the documentation, with the text ``Returns: '' put in front of it. This should usually give a brief hint about the type or
meaning of the value returned by the documented function. }
\subsection{\textcolor{Chapter }{\texttt{@Arguments \mbox{\texttt{\mdseries\slshape args}}}}}\label{@Arguments}
\logpage{[ 2, 1, 3 ]}
\hyperdef{L}{X81DAA454857F7971}{}
{
\index{"@Arguments@\texttt{"@Arguments \mbox{\texttt{\mdseries\slshape args}}}} The string \mbox{\texttt{\mdseries\slshape args}} contains a description of the arguments the function expects, including
optional parts, which are denoted by square brackets. The argument names can
be separated by whitespace, commas or square brackets for the optional
arguments, like ``grp[, elm]'' or ``xx[y[z] ]''. If \textsf{GAP} options are used, this can be followed by a colon : and one or more
assignments, like ``n[, r]: tries := 100''. }
\subsection{\textcolor{Chapter }{\texttt{@Group \mbox{\texttt{\mdseries\slshape grpname}}}}}\label{@Group}
\logpage{[ 2, 1, 4 ]}
\hyperdef{L}{X8677FE8F80C00B14}{}
{
\index{"@Group@\texttt{"@Group \mbox{\texttt{\mdseries\slshape grpname}}}} Adds the following method to a group with the given name. See section \ref{Groups} for more information about groups. }
\subsection{\textcolor{Chapter }{\texttt{@Label \mbox{\texttt{\mdseries\slshape label}}}}}\label{@Label}
\logpage{[ 2, 1, 5 ]}
\hyperdef{L}{X7B0E20A27D64DF6F}{}
{
\index{"@Label@\texttt{"@Label \mbox{\texttt{\mdseries\slshape label}}}} Adds label to the function as label. If this is not specified, then for
declarations that involve a list of input filters (as is the case for \texttt{DeclareOperation}, \texttt{DeclareAttribute}, etc.), a default label is generated from this filter list. }
\begin{Verbatim}[commandchars=|BC,fontsize=\small,frame=single,label=]
#! @Label testlabel
DeclareProperty( "AProperty",
IsObject );
\end{Verbatim}
leads to this:
\subsection{\textcolor{Chapter }{AProperty (testlabel)}}
\logpage{[ 2, 1, 6 ]}\nobreak
\hyperdef{L}{X83B63B847B5199CF}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AProperty({\mdseries\slshape arg})\index{AProperty@\texttt{AProperty}!testlabel}
\label{AProperty:testlabel}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} or \texttt{false}
}
while
\begin{Verbatim}[commandchars=@|B,fontsize=\small,frame=single,label=]
#!
DeclareProperty( "AProperty",
IsObject );
\end{Verbatim}
leads to this:
\subsection{\textcolor{Chapter }{AProperty (for IsObject)}}
\logpage{[ 2, 1, 7 ]}\nobreak
\hyperdef{L}{X78A9022A7D5CB20E}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AProperty({\mdseries\slshape arg})\index{AProperty@\texttt{AProperty}!for IsObject}
\label{AProperty:for IsObject}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} or \texttt{false}
}
\subsection{\textcolor{Chapter }{\texttt{@ChapterInfo \mbox{\texttt{\mdseries\slshape chapter}}, \mbox{\texttt{\mdseries\slshape section}}}}}\label{@ChapterInfo}
\logpage{[ 2, 1, 8 ]}
\hyperdef{L}{X78938EE37A532FFA}{}
{
\index{"@ChapterInfo@\texttt{"@ChapterInfo}} Adds the entry to the given chapter and section. Here, \mbox{\texttt{\mdseries\slshape chapter}} and \mbox{\texttt{\mdseries\slshape section}} are the respective titles. }
As an example, a full \textsf{AutoDoc} comment with all options could look like this:
\begin{Verbatim}[commandchars=|EF,fontsize=\small,frame=single,label=]
#! @Description
#! Computes the list of lists of degrees of ordinary characters
#! associated to the $p$-blocks of the group $G$
#! with $p$-modular character table modtbl
#! and underlying ordinary character table `ordtbl`.
#! @Returns a list
#! @Arguments modtbl
#! @Group CharacterDegreesOfBlocks
#! @Label chardegblocks
#! @ChapterInfo Blocks, Attributes
DeclareAttribute( "CharacterDegreesOfBlocks",
IsBrauerTable );
\end{Verbatim}
}
\section{\textcolor{Chapter }{Other documentation comments}}\logpage{[ 2, 2, 0 ]}
\hyperdef{L}{X8152FEF9844B1ACD}{}
{
There are also some commands which can be used in \textsf{AutoDoc} comments that are not associated to any declaration. This is useful for
additional text in your documentation, examples, mathematical chapters, etc..
\subsection{\textcolor{Chapter }{\texttt{@Chapter \mbox{\texttt{\mdseries\slshape name}}}}}\label{@Chapter}
\logpage{[ 2, 2, 1 ]}
\hyperdef{L}{X823E613385D09F6F}{}
{
\index{"@Chapter@\texttt{"@Chapter}} \index{"@ChapterLabel@\texttt{"@ChapterLabel}} \index{"@ChapterTitle@\texttt{"@ChapterTitle}} Sets the active chapter, all subsequent functions which do not have an
explicit chapter declared in their \textsf{AutoDoc} comment via \texttt{@ChapterInfo} will be added to this chapter. Also all text comments, i.e. lines that begin
with \#! without a command, and which do not follow after \texttt{@Description}, will be added to the chapter as regular text. Additionally, the chapters
label will be set to \texttt{Chapter{\textunderscore}}\mbox{\texttt{\mdseries\slshape name}}. Example:
\begin{Verbatim}[commandchars=|AB,fontsize=\small,frame=single,label=]
#! @Chapter My chapter
#! This is my chapter.
#! I document my stuff in it.
\end{Verbatim}
The \texttt{@ChapterLabel} \mbox{\texttt{\mdseries\slshape label}} command can be used to set the label of the chapter to \texttt{Chapter{\textunderscore}}\mbox{\texttt{\mdseries\slshape label}} instead of \texttt{Chapter{\textunderscore}}\mbox{\texttt{\mdseries\slshape name}}. Additionally, the chapter will be stored as \texttt{{\textunderscore}Chapter{\textunderscore}}\mbox{\texttt{\mdseries\slshape label}}\texttt{.xml}. The \texttt{@ChapterTitle} \mbox{\texttt{\mdseries\slshape title}} command can be used to set a heading for the chapter that is different from \mbox{\texttt{\mdseries\slshape name}}. Note that the title does not affect the label. If you use all three
commands, i.e.,
\begin{Verbatim}[commandchars=|AB,fontsize=\small,frame=single,label=]
#! @Chapter name
#! @ChapterLabel label
#! @ChapterTitle title
\end{Verbatim}
\texttt{title} is used for the headline, \texttt{label} for cross\texttt{\symbol{45}}referencing, and \texttt{name} for setting the same chapter as active chapter again. }
\subsection{\textcolor{Chapter }{\texttt{@Section \mbox{\texttt{\mdseries\slshape name}}}}}\label{@Section}
\logpage{[ 2, 2, 2 ]}
\hyperdef{L}{X78AA98BA7E0635D0}{}
{
\index{"@Section@\texttt{"@Section}} \index{"@SectionLabel@\texttt{"@SectionLabel}} \index{"@SectionTitle@\texttt{"@SectionTitle}} Sets an active section like \texttt{@Chapter} sets an active chapter. The section automatically ends with the next \texttt{@Section} or \texttt{@Chapter} command.
\begin{Verbatim}[commandchars=|AB,fontsize=\small,frame=single,label=]
#! @Section My first manual section
#! In this section I am going to document my first method.
\end{Verbatim}
The \texttt{@SectionLabel} \mbox{\texttt{\mdseries\slshape label}} command can be used to set the label of the section to \texttt{Section{\textunderscore}}\mbox{\texttt{\mdseries\slshape label}} instead of \texttt{Chapter{\textunderscore}chaptername{\textunderscore}Section{\textunderscore}}\mbox{\texttt{\mdseries\slshape name}}. The \texttt{@SectionTitle} \mbox{\texttt{\mdseries\slshape title}} command can be used to set a heading for the section that is different from \mbox{\texttt{\mdseries\slshape name}}. }
\subsection{\textcolor{Chapter }{\texttt{@Subsection \mbox{\texttt{\mdseries\slshape name}}}}}\label{@Subsection}
\logpage{[ 2, 2, 3 ]}
\hyperdef{L}{X7FD77434802A3580}{}
{
\index{"@Subsection@\texttt{"@Subsection}} \index{"@SubsectionLabel@\texttt{"@SubsectionLabel}} \index{"@SubsectionTitle@\texttt{"@SubsectionTitle}} Sets an active subsection like \texttt{@Section} sets an active section. The subsection automatically ends with the next \texttt{@Subsection}, \texttt{@Section} or \texttt{@Chapter} command. It also ends with the next documented function. Indeed, internally
each function ``manpage'' is treated like a subsection.
\begin{Verbatim}[commandchars=|AB,fontsize=\small,frame=single,label=]
#! @Subsection My first manual subsection
#! In this subsection I am going to document my first example.
\end{Verbatim}
The \texttt{@SubsectionLabel} \mbox{\texttt{\mdseries\slshape label}} command can be used to set the label of the subsection to \texttt{Subsection{\textunderscore}}\mbox{\texttt{\mdseries\slshape label}} instead of \texttt{Chapter{\textunderscore}chaptername{\textunderscore}Section{\textunderscore}sectionname{\textunderscore}Subsection{\textunderscore}}\mbox{\texttt{\mdseries\slshape name}}. The \texttt{@SubsectionTitle} \mbox{\texttt{\mdseries\slshape title}} command can be used to set a heading for the subsection that is different from \mbox{\texttt{\mdseries\slshape name}}. }
\subsection{\textcolor{Chapter }{\texttt{@BeginGroup \mbox{\texttt{\mdseries\slshape [grpname]}}}}}\label{@BeginGroup}
\logpage{[ 2, 2, 4 ]}
\hyperdef{L}{X7D3060C17EDBCED1}{}
{
\index{"@BeginGroup@\texttt{"@BeginGroup}} Starts a group. All following documented declarations without an explicit \texttt{@Group} command are grouped together in the same group with the given name. If no name
is given, then a new nameless group is generated. The effect of this command
is ended when an \texttt{@EndGroup} command is reached.
See section \ref{Groups} for more information about groups. }
\subsection{\textcolor{Chapter }{\texttt{@EndGroup}}}\label{@EndGroup}
\logpage{[ 2, 2, 5 ]}
\hyperdef{L}{X7C17EB007FD42C87}{}
{
\index{"@EndGroup@\texttt{"@EndGroup}} Ends the current group.
\begin{Verbatim}[commandchars=|CF,fontsize=\small,frame=single,label=]
#! @BeginGroup MyGroup
#!
DeclareAttribute( "GroupedAttribute",
IsList );
DeclareOperation( "NonGroupedOperation",
[ IsObject ] );
#!
DeclareOperation( "GroupedOperation",
[ IsList, IsRubbish ] );
#! @EndGroup
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{@GroupTitle \mbox{\texttt{\mdseries\slshape title}}}}\label{@GroupTitle}
\logpage{[ 2, 2, 6 ]}
\hyperdef{L}{X82FB96F37FAE8167}{}
{
\index{"@GroupTitle@\texttt{"@GroupTitle}} Sets the subsection heading for the current group to \mbox{\texttt{\mdseries\slshape title}}. In the absence of any \texttt{@GroupTitle} command, the heading will be the name of the first entry in the group. See \ref{Groups} for more information. }
\subsection{\textcolor{Chapter }{\texttt{@Level \mbox{\texttt{\mdseries\slshape lvl}}}}}\label{@Level}
\logpage{[ 2, 2, 7 ]}
\hyperdef{L}{X7BF81EAF80D1A4B5}{}
{
\index{"@Level@\texttt{"@Level}} Sets the current level of the documentation. All items created after this,
chapters, sections, and items, are given the level \mbox{\texttt{\mdseries\slshape lvl}}, until the \texttt{@ResetLevel} command resets the level to 0 or another level is set.
See section \ref{Level} for more information about levels. }
\subsection{\textcolor{Chapter }{\texttt{@ResetLevel}}}\label{@ResetLevel}
\logpage{[ 2, 2, 8 ]}
\hyperdef{L}{X7C6723D57F424215}{}
{
\index{"@ResetLevel@\texttt{"@ResetLevel}} Resets the current level to 0.
}
\subsection{\textcolor{Chapter }{\texttt{@BeginExample} and \texttt{@EndExample}}}\label{@BeginExample}
\logpage{[ 2, 2, 9 ]}
\hyperdef{L}{X83D6DA3B83D3436C}{}
{
\index{"@BeginExample@\texttt{"@BeginExample}} \index{"@EndExample@\texttt{"@EndExample}} \texttt{@BeginExample} marks the start of an example to be put into the manual. It differs from \textsf{GAPDoc}'s \texttt{{\textless}Example{\textgreater}} (see (\textbf{GAPDoc: Log})), in that it expects actual code (not in a comment) interspersed with
comments, to allow for examples files that can be both executed by \textsf{GAP}, and parsed by \textsf{AutoDoc}. To achieve this, \textsf{GAP} commands are not preceded by a comment, while output has to be preceded by an \textsf{AutoDoc} comment. The \texttt{gap{\textgreater}} prompt for the display in the manual is added by \textsf{AutoDoc}. \texttt{@EndExample} ends the example block.
To illustrate this command, consider this input:
\begin{Verbatim}[commandchars=|AC,fontsize=\small,frame=single,label=]
#! @BeginExample
S5 := SymmetricGroup(5);
#! Sym( [ 1 .. 5 ] )
Order(S5);
#! 120
#! @EndExample
\end{Verbatim}
This results in the following output:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
!gapprompt@gap>| !gapinput@S5 := SymmetricGroup(5);|
Sym( [ 1 .. 5 ] )
!gapprompt@gap>| !gapinput@Order(S5);|
120
\end{Verbatim}
The \textsf{AutoDoc} command \texttt{@Example} is an alias of \texttt{@BeginExample}. }
\subsection{\textcolor{Chapter }{\texttt{@BeginExampleSession} and \texttt{@EndExampleSession}}}\label{@BeginExampleSession}
\logpage{[ 2, 2, 10 ]}
\hyperdef{L}{X861E2E778510CAF7}{}
{
\index{"@BeginExampleSession@\texttt{"@BeginExampleSession}} \index{"@EndExampleSession@\texttt{"@EndExampleSession}} \texttt{@BeginExampleSession} marks the start of an example to be put into the manual, while \texttt{@EndExampleSession} ends the example block. It is the direct analog of \textsf{GAPDoc}'s \texttt{{\textless}Example{\textgreater}} (see (\textbf{GAPDoc: Log})).
To illustrate this command, consider this input:
\begin{Verbatim}[commandchars=|AC,fontsize=\small,frame=single,label=]
#! @BeginExampleSession
#! gap> S5 := SymmetricGroup(5);
#! Sym( [ 1 .. 5 ] )
#! gap> Order(S5);
#! 120
#! @EndExampleSession
\end{Verbatim}
This results in the following output:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
!gapprompt@gap>| !gapinput@S5 := SymmetricGroup(5);|
Sym( [ 1 .. 5 ] )
!gapprompt@gap>| !gapinput@Order(S5);|
120
\end{Verbatim}
It inserts an example into the manual just as \texttt{@Example} would do, but all lines are commented and therefore not executed when the file
is read. All lines that should be part of the example displayed in the manual
have to start with an \textsf{AutoDoc} comment (\texttt{\#!}). The comment will be removed, and, if the following character is a space,
this space will also be removed. There is never more than one space removed.
To ensure examples are correctly colored in the manual, there should be
exactly one space between \texttt{\#!} and the \texttt{gap{\textgreater}} prompt. The \textsf{AutoDoc} command \texttt{@ExampleSession} is an alias of \texttt{@BeginExampleSession}. }
\subsection{\textcolor{Chapter }{\texttt{@BeginLog} and \texttt{@EndLog}}}\label{@BeginLog}
\logpage{[ 2, 2, 11 ]}
\hyperdef{L}{X81A2D44D834C0A17}{}
{
\index{"@BeginLog@\texttt{"@BeginLog}} \index{"@EndLog@\texttt{"@EndLog}} Works just like the \texttt{@BeginExample} command, but the example will not be tested. See the \textsf{GAPDoc} manual for more information. The \textsf{AutoDoc} command \texttt{@Log} is an alias of \texttt{@BeginLog}. }
\subsection{\textcolor{Chapter }{\texttt{@BeginLogSession} and \texttt{@EndLogSession}}}\label{@BeginLogSession}
\logpage{[ 2, 2, 12 ]}
\hyperdef{L}{X7BADE876794FF309}{}
{
\index{"@BeginLogSession@\texttt{"@BeginLogSession}} \index{"@EndLogSession@\texttt{"@EndLogSession}} Works just like the \texttt{@BeginExampleSession} command, but the example will not be tested if manual examples are run. It is
the direct analog of \textsf{GAPDoc}'s \texttt{{\textless}Log{\textgreater}} (see (\textbf{GAPDoc: Log})). The \textsf{AutoDoc} command \texttt{@LogSession} is an alias of \texttt{@BeginLogSession}. }
\subsection{\textcolor{Chapter }{\texttt{@DoNotReadRestOfFile}}}\label{@DoNotReadRestOfFile}
\logpage{[ 2, 2, 13 ]}
\hyperdef{L}{X78DC644E8519280C}{}
{
\index{"@DoNotReadRestOfFile@\texttt{"@DoNotReadRestOfFile}} Prevents the rest of the file from being read by the parser. Useful for
unfinished or temporary files.
\begin{Verbatim}[commandchars=|AB,fontsize=\small,frame=single,label=]
#! This will appear in the manual
#! @DoNotReadRestOfFile
#! This will not appear in the manual.
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{\texttt{@BeginChunk \mbox{\texttt{\mdseries\slshape name}}}, \texttt{@EndChunk}, and \texttt{@InsertChunk \mbox{\texttt{\mdseries\slshape name}}}}}\label{@BeginChunk}
\logpage{[ 2, 2, 14 ]}
\hyperdef{L}{X83C01F9B7FA1C973}{}
{
\index{"@BeginChunk@\texttt{"@BeginChunk \mbox{\texttt{\mdseries\slshape name}}}} \index{"@EndChunk@\texttt{"@EndChunk}} \index{"@EndChunk@\texttt{"@InsertChunk \mbox{\texttt{\mdseries\slshape name}}}} Text inside a \texttt{@BeginChunk} / \texttt{@EndChunk} part will not be inserted into the final documentation directly. Instead, the
text is stored in an internal buffer. That chunk of text can then later on be
inserted in any other place by using the \texttt{@InsertChunk \mbox{\texttt{\mdseries\slshape name}}} command. If you do not provide an \texttt{@EndChunk}, the chunk ends at the end of the file.
\begin{Verbatim}[commandchars=|AD,fontsize=\small,frame=single,label=]
#! @BeginChunk MyChunk
#! Hello, world.
#! @EndChunk
#! @InsertChunk MyChunk
## The text "Hello, world." is inserted right before this.
\end{Verbatim}
You can use this to define an example like this in one file:
\begin{Verbatim}[commandchars=|AD,fontsize=\small,frame=single,label=]
#! @BeginChunk Example_Symmetric_Group
#! @BeginExample
S5 := SymmetricGroup(5);
#! Sym( [ 1 .. 5 ] )
Order(S5);
#! 120
#! @EndExample
#! @EndChunk
\end{Verbatim}
And then later, insert the example in a different file, like this:
\begin{Verbatim}[commandchars=|AB,fontsize=\small,frame=single,label=]
#! @InsertChunk Example_Symmetric_Group
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{\texttt{@BeginCode \mbox{\texttt{\mdseries\slshape name}}}, @EndCode, and \texttt{@InsertCode \mbox{\texttt{\mdseries\slshape name}}}}}\label{@BeginCode}
\logpage{[ 2, 2, 15 ]}
\hyperdef{L}{X7D3671AF86B995B9}{}
{
\index{"@BeginCode@\texttt{"@BeginCode \mbox{\texttt{\mdseries\slshape name}}}} \index{"@EndCode@\texttt{"@EndCode}} \index{"@InsertCode@\texttt{"@InsertCode \mbox{\texttt{\mdseries\slshape name}}}} Inserts the text between \texttt{@BeginCode} and \texttt{@EndCode} verbatim at the point where \texttt{@InsertCode} is called. This is useful to insert code excerpts directly into the manual.
\begin{Verbatim}[commandchars=|AD,fontsize=\small,frame=single,label=]
#! @BeginCode Increment
i := i + 1;
#! @EndCode
#! @InsertCode Increment
## Code is inserted here.
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{\texttt{@LatexOnly \mbox{\texttt{\mdseries\slshape text}}}, \texttt{@BeginLatexOnly}, and \texttt{@EndLatexOnly}}}\label{@LatexOnly}
\logpage{[ 2, 2, 16 ]}
\hyperdef{L}{X8033B34F80A12A10}{}
{
\index{"@LatexOnly@\texttt{"@LatexOnly \mbox{\texttt{\mdseries\slshape text}}}} \index{"@BeginLatexOnly@\texttt{"@BeginLatexOnly}} \index{"@EndLatexOnly@\texttt{"@EndLatexOnly}} Code inserted between \texttt{@BeginLatexOnly} and \texttt{@EndLatexOnly} or after \texttt{@LatexOnly} is only inserted in the PDF version of the manual or worksheet. It can hold
arbitrary {\LaTeX}\texttt{\symbol{45}}commands.
\begin{Verbatim}[commandchars=|AC,fontsize=\small,frame=single,label=]
#! @BeginLatexOnly
#! \include{picture.tex}
#! @EndLatexOnly
#! @LatexOnly \include{picture.tex}
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{\texttt{@NotLatex \mbox{\texttt{\mdseries\slshape text}}}, \texttt{@BeginNotLatex}, and \texttt{@EndNotLatex}}}\label{@NotLatex}
\logpage{[ 2, 2, 17 ]}
\hyperdef{L}{X7EF303147F1BCC22}{}
{
\index{"@NotLatex@\texttt{"@NotLatex \mbox{\texttt{\mdseries\slshape text}}}} \index{"@BeginNotLatex@\texttt{"@BeginNotLatex}} \index{"@EndNotLatex@\texttt{"@EndNotLatex}} Code inserted between \texttt{@BeginNotLatex} and \texttt{@EndNotLatex} or after \texttt{@NotLatex} is inserted in the HTML and text versions of the manual or worksheet, but not
in the PDF version.
\begin{Verbatim}[commandchars=|AC,fontsize=\small,frame=single,label=]
#! @BeginNotLatex
#! For further information see the PDF version of this manual.
#! @EndNotLatex
#! @NotLatex For further information see the PDF version of this manual.
\end{Verbatim}
}
}
\section{\textcolor{Chapter }{Title page commands}}\label{TitlepageCommands}
\logpage{[ 2, 3, 0 ]}
\hyperdef{L}{X841E3AD584F5385C}{}
{
The following commands can be used to add the corresponding parts to the title
page of the document which generated by \textsf{AutoDoc} if scaffolding is enabled.
\begin{itemize}
\item \texttt{@Title}
\item \texttt{@Subtitle}
\item \texttt{@Version}
\item \texttt{@TitleComment}
\item \texttt{@Author}
\item \texttt{@Date}
\item \texttt{@Address}
\item \texttt{@Abstract}
\item \texttt{@Copyright}
\item \texttt{@Acknowledgements}
\item \texttt{@Colophon}
\end{itemize}
Those add the following lines at the corresponding point of the title page.
Please note that many of those things can be (better) extracted from the \texttt{PackageInfo.g}. In case you set some of those, the extracted or in scaffold defined items
will be overwritten. While this is not very useful for documenting packages,
they are necessary for worksheets created with \texttt{AutoDocWorksheet} (\ref{AutoDocWorksheet}), since worksheets do not have a \texttt{PackageInfo.g} file from which this information could be extracted. }
\section{\textcolor{Chapter }{Plain text files}}\label{PlainText}
\logpage{[ 2, 4, 0 ]}
\hyperdef{L}{X828AE38F80CB02E7}{}
{
Files that have the suffix \texttt{.autodoc} and are listed in the \texttt{autodoc.files} option of \texttt{AutoDoc} (\ref{AutoDoc}), resp. are contained in one of the directories listed in \texttt{autodoc.scan{\textunderscore}dirs}, are treated as \textsf{AutoDoc} plain text files. These work exactly like \textsf{AutoDoc} comments, except that lines do not need to (and in fact, should not) start
with \texttt{\#!}. }
\section{\textcolor{Chapter }{Grouping}}\label{Groups}
\logpage{[ 2, 5, 0 ]}
\hyperdef{L}{X7D7A38F87BC40C48}{}
{
In \textsf{GAPDoc}, it is possible to make groups of manual items, i.e., when documenting a
function, operation, etc., it is possible to group them into suitable chunks.
This can be particularly useful if there are several definitions of an
operation with several different argument types, all doing more or less the
same to the arguments. Then their manual items can be grouped, sharing the
same description and return type information. You can give a heading to the
group in the manual with the \texttt{@GroupTitle} command; if that is not supplied, then the heading of the first manual item in
the group will be used as the heading.
Note that group names are globally unique throughout the whole manual. That
is, groups with the same name are in fact merged into a single group, even if
they were declared in different source files. Thus you can have multiple \texttt{@BeginGroup} / \texttt{@EndGroup} pairs using the same group name, in different places, and these all will refer
to the same group.
Moreover, this means that you can add items to a group via the \texttt{@Group} command in the \textsf{AutoDoc} comment of an arbitrary declaration, at any time.
The following code
\begin{Verbatim}[commandchars=|CH,fontsize=\small,frame=single,label=]
#! @BeginGroup Group1
#! @GroupTitle A family of operations
#! @Description
#! First sentence.
DeclareOperation( "FirstOperation", [ IsInt ] );
#! @Description
#! Second sentence.
DeclareOperation( "SecondOperation", [ IsInt, IsGroup ] );
#! @EndGroup
## .. Stuff ..
#! @Description
#! Third sentence.
#! @Group Group1
KeyDependentOperation( "ThirdOperation", IsGroup, IsInt, "prime );
\end{Verbatim}
produces the following:
\subsection{\textcolor{Chapter }{A family of operations}}\label{Group1}
\logpage{[ 2, 5, 1 ]}
\hyperdef{L}{X79BF060F8436C586}{}
{
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{FirstOperation({\mdseries\slshape arg})\index{FirstOperation@\texttt{FirstOperation}!for IsInt}
\label{FirstOperation:for IsInt}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SecondOperation({\mdseries\slshape arg1, arg2})\index{SecondOperation@\texttt{SecondOperation}!for IsInt, IsGroup}
\label{SecondOperation:for IsInt, IsGroup}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ThirdOperation({\mdseries\slshape arg1, arg2})\index{ThirdOperation@\texttt{ThirdOperation}!for IsGroup, IsInt}
\label{ThirdOperation:for IsGroup, IsInt}
}\hfill{\scriptsize (operation)}}\\
First sentence. Second sentence. Third sentence. }
}
\section{\textcolor{Chapter }{Level}}\label{Level}
\logpage{[ 2, 6, 0 ]}
\hyperdef{L}{X8209AFDE8209AFDE}{}
{
Levels can be set to not write certain parts in the manual by default. Every
entry has by default the level 0. The command \texttt{@Level} can be used to set the level of the following part to a higher level, for
example 1, and prevent it from being printed to the manual by default.
However, if one sets the level to a higher value in the autodoc option of \textsf{AutoDoc}, the parts will be included in the manual at the specific place.
\begin{Verbatim}[commandchars=|AB,fontsize=\small,frame=single,label=]
#! This text will be printed to the manual.
#! @Level 1
#! This text will be printed to the manual if created with level 1 or higher.
#! @Level 2
#! This text will be printed to the manual if created with level 2 or higher.
#! @ResetLevel
#! This text will be printed to the manual.
\end{Verbatim}
}
\section{\textcolor{Chapter }{Markdown\texttt{\symbol{45}}like formatting of text in \textsf{AutoDoc}}}\label{MarkdownExtension}
\logpage{[ 2, 7, 0 ]}
\hyperdef{L}{X79558A2F7FE187B4}{}
{
\textsf{AutoDoc} has some convenient ways to insert special format into text, like math
formulas and lists. The syntax for them are inspired by Markdown and {\LaTeX}, but do not follow them strictly. Neither are all features of the Markdown
language supported. The following subsections describe what is possible.
\subsection{\textcolor{Chapter }{Lists}}\label{MarkdownExtensionList}
\logpage{[ 2, 7, 1 ]}
\hyperdef{L}{X7B256AE5780F140A}{}
{
One can create lists of items by beginning a new line with *, +,
\texttt{\symbol{45}}, followed by one space. The first item starts the list.
When items are longer than one line, the following lines have to be indented
by at least two spaces. The list ends when a line which does not start a new
item is not indented by two spaces. Of course lists can be nested. Here is an
example:
\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=]
#! The list starts in the next line
#! * item 1
#! * item 2
#! which is a bit longer
#! * and also contains a nested list
#! * with two items
#! * item 3 of the outer list
#! This does not belong to the list anymore.
\end{Verbatim}
This is the output:\\
The list starts in the next line
\begin{itemize}
\item item 1
\item item 2 which is a bit longer
\begin{itemize}
\item and also contains a nested list
\item with two items
\end{itemize}
\item item 3 of the outer list
\end{itemize}
This does not belong to the list anymore.\\
The *, \texttt{\symbol{45}}, and + are fully interchangeable and can even be
used mixed, but this is not recommended. }
\subsection{\textcolor{Chapter }{Math modes}}\label{MarkdownExtensionMath}
\logpage{[ 2, 7, 2 ]}
\hyperdef{L}{X871412737A0E12E2}{}
{
One can start an inline formula with a \$, and also end it with \$, just like
in {\LaTeX}. This will translate into \textsf{GAPDoc}s inline math environment. For display mode one can use \$\$, also like {\LaTeX}.
\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=]
#! This is an inline formula: $1+1 = 2$.
#! This is a display formula:
#! $$ \sum_{i=1}^n i. $$
\end{Verbatim}
produces the following output:\\
This is an inline formula: $1+1 = 2$. This is a display formula:
\[ \sum_{i=1}^n i. \]
}
\subsection{\textcolor{Chapter }{Emphasize}}\label{MarkdownExtensionEmph}
\logpage{[ 2, 7, 3 ]}
\hyperdef{L}{X7ED0330479146EFC}{}
{
One can emphasize text by using two asterisks (**) or two underscores
({\textunderscore}{\textunderscore}) at the beginning and the end of the text
which should be emphasized. Example:
\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=]
#! **This** is very important.
#! This is __also important__.
#! **Naturally, more than one line
#! can be important.**
\end{Verbatim}
This produces the following output:\\
\emph{This} is very important. This is \emph{also important}. \emph{Naturally, more than one line can be important.} }
\subsection{\textcolor{Chapter }{Inline code}}\label{MarkdownExtensionInlineCode}
\logpage{[ 2, 7, 4 ]}
\hyperdef{L}{X838CCDEB7E0ECEE2}{}
{
One can mark inline code snippets by using backticks (`) at the beginning and
the end of the text which should be marked as code. Example:
\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=]
#! Call function `foobar()` at the start.
\end{Verbatim}
This produces the following output:\\
Call function \texttt{foobar()} at the start. }
}
\section{\textcolor{Chapter }{Deprecated commands}}\label{Deprecated}
\logpage{[ 2, 8, 0 ]}
\hyperdef{L}{X78CA9E5C7F494C19}{}
{
The following commands used to be supported, but are not anymore.
\begin{description}
\item[{\texttt{@EndSection}}] You can simply remove any use of this, \textsf{AutoDoc} ends sections automatically at the start of any new section or chapter.
\item[{\texttt{@EndSubsection}}] You can simply remove any use of this, \textsf{AutoDoc} ends subsections automatically at the start of any new subsection, section or
chapter.
\item[{\texttt{@BeginAutoDoc} and \texttt{@EndAutoDoc}}] It suffices to prepend each declaration that is meant to be appear in the
manual with a minimal \textsf{AutoDoc} comment \texttt{\#!}.
\item[{\texttt{@BeginSystem \mbox{\texttt{\mdseries\slshape name}}}, \texttt{@EndSystem}, and \texttt{@InsertSystem \mbox{\texttt{\mdseries\slshape name}}}}] Please use the chunk commands from subsection \ref{@BeginChunk} instead.
\item[{\texttt{@AutoDocPlainText} and \texttt{@EndAutoDocPlainText}}] Use \texttt{.autodoc} files or \textsf{AutoDoc} comments instead.
\end{description}
}
}
\chapter{\textcolor{Chapter }{AutoDoc worksheets}}\label{Chapter_AutoDoc_worksheets}
\logpage{[ 3, 0, 0 ]}
\hyperdef{L}{X80ED3C2A78146AD1}{}
{
\section{\textcolor{Chapter }{Worksheets}}\label{Chapter_AutoDoc_worksheets_Section_Worksheets}
\logpage{[ 3, 1, 0 ]}
\hyperdef{L}{X801D4A2F8292704C}{}
{
\subsection{\textcolor{Chapter }{AutoDocWorksheet}}
\logpage{[ 3, 1, 1 ]}\nobreak
\hyperdef{L}{X809FE4137C08B28D}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AutoDocWorksheet({\mdseries\slshape list{\textunderscore}of{\textunderscore}filenames: options})\index{AutoDocWorksheet@\texttt{AutoDocWorksheet}}
\label{AutoDocWorksheet}
}\hfill{\scriptsize (function)}}\\
The intention of these function is to create stand\texttt{\symbol{45}}alone
pdf and html files using AutoDoc without having them associated to a package.
It uses the same optional records as the \textsf{AutoDoc} command itself, but instead of a package name there should be a filename or a
list of filenames containing AutoDoc text from which the documents are
created. Please see the \textsf{AutoDoc} command for more information about this and have a look at \ref{Tut:AutoDocWorksheet} for a simple worksheet example. }
}
}
\chapter{\textcolor{Chapter }{AutoDoc}}\label{Chapter_AutoDoc}
\logpage{[ 4, 0, 0 ]}
\hyperdef{L}{X7CBD8AAF7DCEF352}{}
{
\section{\textcolor{Chapter }{The AutoDoc() function}}\label{Chapter_AutoDoc_Section_The_AutoDoc_function}
\logpage{[ 4, 1, 0 ]}
\hyperdef{L}{X863584DB8497D8BA}{}
{
\subsection{\textcolor{Chapter }{AutoDoc}}
\logpage{[ 4, 1, 1 ]}\nobreak
\hyperdef{L}{X7CBD8AAF7DCEF352}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AutoDoc({\mdseries\slshape [packageOrDirectory][,] [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/PACKAGENAME.xml} (with your package's name substituted) 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 (by using \textsf{AutoDoc} tags and the Autodoc command. This will produce further 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}
For more information and some examples, please refer to Chapter \ref{Tutorials}.
The parameters have the following meanings:
\begin{description}
\item[{\mbox{\texttt{\mdseries\slshape packageOrDirectory}}}] The purpose of this parameter is twofold: to determine the package directory
in which \textsf{AutoDoc} will operate, and to find the metadata concerning the package being
documented. The parameter is either a string, an \texttt{IsDirectory} object, or omitted. If it is a string, \textsf{AutoDoc} interprets it as the name of a package, uses the metadata of the first package
known to \textsf{GAP} with that name, and uses the \texttt{InstallationPath} specified in that metadata as the package directory. If \mbox{\texttt{\mdseries\slshape packageOrDirectory}} is an \texttt{IsDirectory} object, this is used as package directory; if the argument is omitted, then
the current directory is used. In the last two 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.
Note that when using \texttt{AutoDocWorksheet} (see \ref{Chapter_AutoDoc_worksheets_Section_Worksheets}), there is no parameter corresponding to \mbox{\texttt{\mdseries\slshape packageOrDirectory}} 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.
\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 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 := "SomePackage",
RELEASEYEAR := "2015" )
\end{Verbatim}
then the following entity definitions are added to the XML preamble:
\begin{Verbatim}[commandchars=@|B,fontsize=\small,frame=single,label=]
SomePackage'>
\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.
\item[{\mbox{\texttt{\mdseries\slshape TitlePage}}}] A record whose entries are used to embellish the generated title page for the
package manual with extra information, such as a copyright statement or
acknowledgments. To this end, the names of the record components are used as
XML element names, and the values of the components are outputted as content
of these XML elements. For example, you could pass the following record to set
a custom acknowledgements text:
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
rec( Acknowledgements := "Many thanks to ..." )
\end{Verbatim}
For a list of valid entries in the title page, please refer to 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 for .gi, .gd, .g, and .autodoc files; all of these files are then
scanned for \textsf{AutoDoc} documentation comments. \\
\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{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 for .gi, .gd and .g files; all of these files are then scanned for \textsf{GAPDoc} documentation comments. \\
\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.
As a record, the entry can have the following entries itself, to specify some
options.
\begin{description}
\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}
}
\subsection{\textcolor{Chapter }{InfoAutoDoc}}
\logpage{[ 4, 1, 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(InfoPackageManager, 0)}. Default value 1. }
}
\section{\textcolor{Chapter }{Examples}}\label{Chapter_AutoDoc_Section_Examples}
\logpage{[ 4, 2, 0 ]}
\hyperdef{L}{X7A489A5D79DA9E5C}{}
{
Some basic examples for using \texttt{AutoDoc} were already shown in Chapter \ref{Tutorials}. }
}
\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}
AutoDoc-2025.10.16/doc/times.css 0000644 0001751 0001751 00000000261 15074117054 015457 0 ustar runner runner /* times.css Frank Lübeck */
/* Change default CSS to use Times font. */
body {
font-family: Times,Times New Roman,serif;
}
AutoDoc-2025.10.16/doc/rainbow.js 0000644 0001751 0001751 00000005336 15074117054 015633 0 ustar runner runner
function randchar(str) {
var i = Math.floor(Math.random() * str.length);
while (i == str.length)
i = Math.floor(Math.random() * str.length);
return str[i];
}
hexdigits = "0123456789abcdef";
function randlight() {
return randchar("cdef")+randchar(hexdigits)+
randchar("cdef")+randchar(hexdigits)+
randchar("cdef")+randchar(hexdigits)
}
function randdark() {
return randchar("012345789")+randchar(hexdigits)+
randchar("012345789")+randchar(hexdigits)+
randchar("102345789")+randchar(hexdigits)
}
document.write('\n');
AutoDoc-2025.10.16/doc/_Chunks.xml 0000644 0001751 0001751 00000000000 15074117054 015727 0 ustar runner runner AutoDoc-2025.10.16/doc/AutoDoc.xml 0000644 0001751 0001751 00000000644 15074117054 015711 0 ustar runner runner
]
>
<#Include SYSTEM "title.xml">
<#Include SYSTEM "Tutorials.xml">
<#Include SYSTEM "Comments.xml">
<#Include SYSTEM "_AutoDocMainFile.xml">
AutoDoc-2025.10.16/doc/nocolorprompt.css 0000644 0001751 0001751 00000000313 15074117054 017251 0 ustar runner runner
/* colors for ColorPrompt like examples */
span.GAPprompt {
color: #000000;
font-weight: normal;
}
span.GAPbrkprompt {
color: #000000;
font-weight: normal;
}
span.GAPinput {
color: #000000;
}
AutoDoc-2025.10.16/doc/chap1_mj.html 0000644 0001751 0001751 00000103260 15074117054 016177 0 ustar runner runner
GAP (AutoDoc) - Chapter 1: Getting started using AutoDoc
AutoDoc is a GAP package which is meant to aid GAP package authors in creating and maintaining the documentation of their packages. In this capacity it builds upon the GAPDoc package (see https://www.gap-system.org/Packages/gapdoc.html). As such, it is not a replacement for GAPDoc, but rather complements it.
In this chapter we describe how to get started using AutoDoc for your package. First, we explain in Section 1.1 how to write a new package manual from scratch.
Then we show in Section 1.3 how you might benefit from AutoDoc even if you already have a complete manual written using GAPDoc.
In Section 1.4, we explain how you may use AutoDoc to generate a title page and the main XML file for your manual.
Finally, Section 1.5, explains what AutoDoc worksheets are and how to use them.
1.1 Creating a package manual from scratch
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 AutoDoc (4.1-1) command like this, while running GAP from within your package's directory (the one containing the PackageInfo.g file):
This first reads the PackageInfo.g file from the current directory. It extracts information about the package from it (such as its name and version, see Section 1.4-1). It then creates two XML files doc/NAME_OF_YOUR_PACKAGE.xml and doc/title.xml inside the package directory. Finally, it runs GAPDoc on them to produce a nice initial PDF and HTML version of your fresh manual.
To ensure that the GAP help system picks up your package manual, you should also add something like the following to your PackageInfo.g:
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 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-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 that for you, more research on artificial intelligence is required). To add more content, you have several options: You could add further GAPDoc XML files containing extra chapters, sections and so on. Or you could use classic GAPDoc source comments. For details on either, please refer to GAPDoc: Distributing a Document into Several Files, as well as Section 1.3 of this manual on how to teach the AutoDoc (4.1-1) command to include this extra documentation. Or you could use the special documentation facilities AutoDoc provides (see Section 1.2).
You will probably want to re-run the AutoDoc (4.1-1) command frequently, e.g. whenever you modified your documentation or your PackageInfo.g. To make this more convenient and reproducible, we recommend putting its invocation into a file makedoc.g in your package directory, with content based on the following example:
Then you can regenerate the package manual from the command line with the following command, executed from within in the package directory:
gap makedoc.g
1.2 Documenting code with AutoDoc
To get one of your global functions, operations, attributes etc. to appear in the package manual, simply insert an AutoDoc comment of the form #! directly in front of it. For example:
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:
#! @Arguments conv
#! @Returns a toric variety
#! @Description
#! Creates a toric variety out
#! of the convex object <A>conv</A>.
DeclareOperation( "ToricVariety", [ IsConvexObject ] );
For a thorough description of what you can do with AutoDoc documentation comments, please refer to chapter 2.
Suppose you have not been using GAPDoc before but instead used the process described in section 1.1 to create your manual. Then the following GAP command will regenerate the manual and automatically include all newly documented functions, operations etc.:
If you are not using the scaffolding feature, e.g. because you already have an existing GAPDoc based manual, then you can still use AutoDoc documentation comments. Just make sure to first edit the main XML file of your documentation, and insert the line
<#Include SYSTEM "_AutoDocMainFile.xml">
in a suitable place. This means that you can mix AutoDoc documentation comment freely with your existing documentation; you can even still make use of any existing GAPDoc documentation comments in your code. The following command should be useful for you in this case; it still scans the package code for AutoDoc documentation comments and the runs GAPDoc to produce HTML and PDF output, but does not touch your documentation XML files otherwise.
Even if you already have an existing GAPDoc manual, it might be interesting for you to use AutoDoc for two purposes:
First off, with 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 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 AutoDoc for this purpose only, e.g. io and orb.
1.3-1 Using AutoDoc on a complete GAPDoc manual
Suppose you already have a complete XML manual, with some main and title XML files and some documentation for operations distributed over all your .g, .gd, and .gi files. Suppose the main XML file is named PACKAGENAME.xml and is in the /doc subdirectory of your package. Then you can rebuild your manual by executing the following two GAP commands from a GAP session started in the root directory of your package:
LoadPackage( "AutoDoc" );
AutoDoc( );
In contrast, the RingsForHomalg package currently uses essentially the following code in its makedoc.g file to achieve the same result:
Now files PACKAGENAME01.tst, PACKAGENAME02.tst and so appear in the tst/ subdirectory of your package, and can be tested as usual using Test (Reference: Test) respectively TestDirectory (Reference: TestDirectory).
1.3-2 Setting different GAPDoc options
Sometimes, the default values for the GAPDoc command used by AutoDoc may not be suitable for your manual.
Suppose your main XML file is not named PACKAGENAME.xml, but rather something else, e.g. main.xml. Then you can tell AutoDoc to use this file as the main XML file via
As explained above, by default AutoDoc scans all .g, .gd and .gi files it can find inside of your package root directory, and in the subdirectories gap, lib, examples and examples/doc as well. If you keep source files with documentation in other directories, you can adjust the list of directories AutoDoc scans via the scan_dirs option. The following example illustrates this by instructing AutoDoc to only search in the subdirectory package_sources of the packages root directory.
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:
Giving such a file does not prevent the standard scan_dirs from being scanned for other files.
Next, GAPDoc supports the documentation to be built with relative paths. This means, links to manuals of other packages or the 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 GAP installation around later. Suppose you are starting GAP in the root path of your package as always, and the standard call of AutoDoc (4.1-1) will then build the documentation in the doc subdirectory of your package. From this directory, the gap root directory has the relative path ../../... Then you can enable the relative paths by
1.3-3
Checklist for converting an existing GAPDoc manual to use AutoDoc
Here is a checklist for authors of a package PackageName, which already has a GAPDoc based manual, who wish to use AutoDoc to build the manual from now on. We assume that the manual is currently built by reading a file makedoc.g and that the main .xml file is named manual.xml.
The files PackageInfo.g, makedoc.g, doc/title.xml and doc/PackageName.xml (if it exists) will be altered by this procedure, so it may be wise to keep backup copies.
You should have copies of the AutoDoc files PackageInfo.g and makedoc.g to hand when reading these instructions.
Copy AutoDoc/makedoc.g to PackageName/makedoc.g.
Edit PackageName/makedoc.g as follows.
Change the header comment to match other files in your package.
After LoadPackage("AutoDoc"); add LoadPackage("PackageName");.
In the AutoDoc record delete autodoc := true;.
In the scaffold record change the includes list to be the list of your .xml files that are contained in manual.xml.
If you do not have a bibliography you may delete the bib := "bib.xml", field in the scaffold. Otherwise, edit the file name if you have a different file. If you only have a .bib file (manual.bib or bib.xml.bib say) you should rename this file PackageName.bib.
In the LaTeXOptions record, which is in the gapdoc record, enter any LaTeX newcommands previously in manual.xml. (If there are none you may safely delete this record.) To illustrate this option, the AutoDoc file makedoc.g defines the command \bbZ by \newcommand{\bbZ}{\mathbb{Z}}, 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.
Now edit PackageName/PackageInfo.g as follows.
Delete any PKGVERSIONDATA chunk that may be there. One reason for converting your manual to use AutoDoc is to stop using entities such as PACKAGENAMEVERSION.
Copy the AutoDoc record from AutoDoc/PackageInfo.g to the end of your file (just before the final "));".
Replace the Copyright, Abstract and Acknowledgements fields of the TitlePage record with the corresponding material from your manual.xml. (If you do not have an abstract, then delete the Abstract field, etc.)
In the entities record enter any entities previously stored in your manual.xml. (Again, if you have none, you may safely delete this record.) To illustrate this option the AutoDoc file PackageInfo.g defines entities for the names of packages io and PackageName.
If you are using a GitHub repository, as well as running "git add" on files makedoc.g, PackageInfo.g and doc/PackageName.bib, you should run "git rm -f" on files doc/manual.xml, and doc/title.xml.
You should now be ready to run GAP and Read("makedoc.g"); in your package root directory.
1.4 Scaffolds
1.4-1 Generating a title page
For most (if not all) 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 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. GAPDoc can help to a degree with this via entities. Thus, you will sometimes see code like this in PackageInfo.g files:
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>
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 AutoDoc to generate a title page for your manual based on the information in your PackageInfo.g. The following commands do just that (in addition to building your manual), by generating a file called doc/title.xml.
Note that this only outputs doc/title.xml but does not touch any other files of your documentation. In particular, you need to explicitly include doc/title.xml from your main XML file.
However, you can also tell 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 AutoDoc not to generate a main page.
1.4-2 Generating the main XML file
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 AutoDoc documentation comments.
For more information, please consult the documentation of the AutoDoc (4.1-1) function.
1.4-3 What data is used from PackageInfo.g?
AutoDoc can use data from PackageInfo.g in order to generate a title page. Specifically, the following components of the package info record are taken into account:
PackageName
This is used to set the <Title> element of the title page.
Subtitle
This is used to set the <Subtitle> element of the title page.
Version
This is used to set the <Version> element of the title page, with the string Version prepended.
Date
This is used to set the <Date> element of the title page.
Persons
This is used to generate <Author> elements in the generated title page.
PackageDoc
This is a record (or a list of records) which is used to tell the GAP help system about the package manual. Currently AutoDoc extracts the value of the PackageDoc.BookName component and then passes that on to GAPDoc when creating the HTML, PDF and text versions of the manual.
AutoDoc
This is a record which can be used to control the scaffolding performed by AutoDoc, specifically to provide extra information for the title page. For example, you can set AutoDoc.TitlePage.Copyright to a string which will then be inserted on the generated title page. Using this method you can customize the following title page elements: TitleComment, Abstract, Copyright, Acknowledgements and Colophon.
Note that AutoDoc.TitlePage behaves exactly the same as the scaffold.TitlePage parameter of the AutoDoc (4.1-1) function.
1.5 AutoDoc worksheets
AutoDoc worksheets can be used to create HTML and PDF documents using AutoDoc syntax and possibly including GAP examples and implementations without having them associated to a package. A file for a worksheet could look like this:
#! @Title My first worksheet
#! @Author Charlie Brown
#! @Chapter Some groups
#! @BeginExample
S3 := SymmetricGroup( 3 );;
S4 := SymmetricGroup( 4 );;
#! @EndExample
Now, one can create a PDF and HTML document, like a package documentation out of it. Suppose the document above is saved as worksheet.g. Then, when GAP is started in the directory of this file, the command
AutoDocWorksheet( "worksheet.g" );
will create a subdirectory called doc of the current directory in which it will create the documentation. There are several options to configure the output of the worksheet command, which are identical to the options of the AutoDoc (4.1-1) command. It is even possible to test the examples in the worksheet using the extract_examples option of the AutoDoc (4.1-1) command.
Since the worksheets do not have a PackageInfo.g to extract information, all possible tags that GAPDoc supports for the title page can be set into the document. A fully typed title page can look like this:
#! @Title My first worksheet
#! @Subtitle Some small examples
#! @Author Charlie Brown
#! @Version 0.1
#! @TitleComment Some worksheet
#! @Date 01/01/2016
#! @Address TU Kaiserslautern
#! @Abstract
#! A worksheet showing some small examples about groups.
#! @Copyright 2016 Charlie Brown
#! @Acknowledgements Woodstock
#! @Colophon Some colophon
#! @Chapter Some groups
#! @BeginExample
S3 := SymmetricGroup( 3 );;
S4 := SymmetricGroup( 4 );;
#! @EndExample