_Chapter_Tutorials.xml

<?xml version="1.0" encoding="UTF-8"?>

<!-- This is an automatically generated file. -->
<Chapter Label="Chapter_Tutorials">
<Heading>Getting started using &AutoDoc;</Heading>

<P/>
This chapter gives practical workflows for adding &AutoDoc; to a package.
For a high-level feature overview and adoption strategy, see
chapter <Ref Chap="Chapter_Overview"/>.
<P/>
<Section Label="Section_Tut:ChooseWorkflow">
<Heading>Choose your workflow</Heading>

<P/>
You can use &AutoDoc; in several ways, and it is fine to combine them:
<List>
<Item>
Start a new package manual from scratch (Section <Ref Sect="Section_Tut:Scratch"/>).
</Item>
<Item>
Integrate &AutoDoc; into an existing &GAPDoc; manual
  (Section <Ref Sect="Section_Tut:IntegrateExisting"/>).
</Item>
<Item>
Use only selected features, such as title-page generation or
  example extraction, while keeping everything else unchanged.
</Item>
</List>
<P/>
This incremental approach is encouraged: start with the smallest helpful step,
then adopt additional features when useful.
</Section>

<Section Label="Section_Tut:Scratch">
<Heading>Creating a package manual from scratch</Heading>

<P/>
Suppose your package is already up and running, but so far has no
manual. Then you can rapidly generate a <Q>scaffold</Q> for a package manual
using the <Ref Func="AutoDoc"/> command like this,
while running &GAP; from within your package's directory (the
one containing the <F>PackageInfo.g</F> file):
<Listing><![CDATA[
LoadPackage( "AutoDoc" );
AutoDoc( rec( scaffold := true ) );
]]></Listing>
This first reads the <F>PackageInfo.g</F> file from the current
directory. It extracts information about the package from it
(such as its name and version, see Section <Ref Sect="Subsection_Tut:Scaffolds:Title"/>).
It then creates two XML files <F>doc/_main.xml</F> and
<F>doc/title.xml</F> inside the package directory. Finally, it runs
&GAPDoc; on them to produce a nice initial PDF and HTML version of your
fresh manual.
<P/>
To ensure that the &GAP; help system picks up your package manual, you
should also add something like the following to your
<F>PackageInfo.g</F>:
<Listing><![CDATA[
PackageDoc := rec(
  BookName  := ~.PackageName,
  ArchiveURLSubset := ["doc"],
  HTMLStart := "doc/chap0.html",
  PDFFile   := "doc/manual.pdf",
  SixFile   := "doc/manual.six",
  LongTitle := ~.Subtitle,
),
]]></Listing>
<P/>
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 <F>PackageInfo.g</F>.
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.
<P/>
Next of course you need to provide actual content (unfortunately, we were
not yet able to automate <E>that</E> 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
<Ref Chap="Distributing" BookName="gapdoc"/>, as well as Section
<Ref Sect="Section_Tut:IntegrateExisting"/> of this manual on how to teach the
<Ref Func="AutoDoc"/> command to include this extra documentation.
Or you could use the special documentation facilities &AutoDoc; provides
(see Section <Ref Sect="Section_Tut:AdvancedAutoDoc"/>).
<P/>
You will probably want to re-run the  <Ref Func="AutoDoc"/> command
frequently, e.g. whenever you modified your documentation or your
<F>PackageInfo.g</F>. To make this more convenient and reproducible, we
recommend putting its invocation into a file <F>makedoc.g</F> in your package
<Index Key="makedoc.g"><F>makedoc.g</F></Index>
directory, with content based on the following example:
<Listing><![CDATA[
LoadPackage( "AutoDoc" );
AutoDoc( rec( autodoc := true ) );
QUIT;
]]></Listing>
Then you can regenerate the package manual from the command line with the
following command, executed from within the package directory:
<Listing><![CDATA[
gap makedoc.g
]]></Listing>
<P/>
If you also want regression tests from your manual examples, enable
<C>extract_examples := true</C>; this is explained in
Section <Ref Sect="Subsection_Tut:IntegrateExisting:EverythingThere"/>.
<P/>
</Section>

<Section Label="Section_Tut:AdvancedAutoDoc">
<Heading>Documenting code with &AutoDoc;</Heading>

<P/>
&AutoDoc; supports several equally supported ways to organize your manual text.
You can put chapter and section material directly into <C>#!</C> comments inside
<F>.g</F>, <F>.gd</F>, or <F>.gi</F> files, you can put it into standalone
<F>.autodoc</F> files, and you can mix either style with existing &GAPDoc; XML.
Which arrangement is best is mostly a matter of taste and convenience.
The detailed command reference for these styles is in chapter
<Ref Chap="Chapter_Comments"/>, especially Section <Ref Sect="Section_PlainText"/>.
<P/>
To get one of your global functions, operations, attributes
etc. to appear in the package manual, simply insert an &AutoDoc; comment
of the form <C>#!</C> directly in front of it. For example:
<Listing><![CDATA[
#!
DeclareOperation( "ToricVariety", [ IsConvexObject ] );
]]></Listing>
<P/>
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:
<P/>
Important: the comment block must be immediately followed by the declaration
it documents. Do not place other code between the comment block and the
<C>Declare...</C> statement.
<P/>
<Listing><![CDATA[
#! @Arguments conv
#! @Returns a toric variety
#! @Description
#!  Creates a toric variety out
#!  of the convex object <A>conv</A>.
DeclareOperation( "ToricVariety", [ IsConvexObject ] );
]]></Listing>
<P/>
In these comment lines, you can freely use normal &GAPDoc; XML markup
(with the usual exceptions for lines starting with <C>@</C>, which are
interpreted as &AutoDoc; commands). So, for instance, tags like
<Code>&lt;Ref&gt;</Code>, <Code>&lt;A&gt;</Code>, <Code>&lt;K&gt;</Code>, <Code>&lt;List&gt;</Code>, etc. can be written
directly in <C>#!</C> comment text.
<P/>
For chapter text, tutorial material, worked examples, and similar prose, some
authors prefer to keep the material next to their code using
<C>#! @Chapter</C>, <C>#! @Section</C>, and related commands, while others prefer
standalone <F>.autodoc</F> files. In an <F>.autodoc</F> file you write the same
commands without the <C>#!</C> prefix, and you list the file in
<C>autodoc.files</C> or place it in a directory scanned via
<C>autodoc.scan_dirs</C>. AutoDoc itself still uses the source-comment style in
places, for example in <F>gap/Magic.gd</F>.
<P/>
One caveat applies if you decide to keep prose in a standalone
<F>.autodoc</F> file but want to interrupt it with the documentation of a
declaration that is written in source comments. Today that requires the chunk
mechanism, and that workflow is currently limited; see issue <C>#60</C> in the
AutoDoc issue tracker.
<P/>
For a thorough description of what you can do with &AutoDoc;
documentation comments, please refer to chapter <Ref Chap="Chapter_Comments"/>.
<P/>
<!--
Once we switched AutoDoc itself to use AutoDoc comments,
mention that, i.e. point out that all operations and functions
documented in this manual are documented exactly like
described here, and that one can hence use that as examples.
-->
<P/>
<!-- 
<P/>
#  <#GAPDoc Label="ToricVarietyConst">
#  <ManSection>
#    <Oper Arg="conv" Name="ToricVariety"
#          Label="for IsConvexObject"/>
#    <Returns>a toric variety</Returns>
#    <Description>
#      Creates a toric variety out 
#      of the convex object <A>conv</A>.
#    </Description>
#  </ManSection>
#  <#/GAPDoc>
DeclareOperation( "ToricVariety",
                  [ IsConvexObject ] );
 -->
<P/>
Suppose you have not been using &GAPDoc; before but instead used the process
described in section <Ref Sect="Section_Tut:Scratch"/> to create your manual.
Then the following &GAP; command will regenerate the manual and automatically
include all newly documented functions, operations etc.:
<P/>
<Listing><![CDATA[
LoadPackage( "AutoDoc" );
AutoDoc( rec( scaffold := true,
              autodoc := true ) );
]]></Listing>
<P/>
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 and standalone <F>.autodoc</F> files. Just make sure to first edit the main XML
file of your documentation, and insert the line
<Listing><![CDATA[
&lt;#Include SYSTEM "_AutoDocMainFile.xml">
]]></Listing>
in a suitable place. This means that you can mix &AutoDoc; documentation
comments and <F>.autodoc</F> files freely with your existing documentation; you can even still make
use of any existing &GAPDoc; documentation comments in your code.
<P/>
The following command should be useful for you in this case; it
still scans the package code for &AutoDoc; documentation comments
and then runs &GAPDoc; to produce HTML and PDF output, but does not
touch your documentation XML files otherwise.
<Listing><![CDATA[
LoadPackage( "AutoDoc" );
AutoDoc( rec( autodoc := true ) );
]]></Listing>
<P/>
</Section>

<Section Label="Section_Tut:IntegrateExisting">
<Heading>Using &AutoDoc; in an existing &GAPDoc; manual</Heading>

<P/>
Even if you already have an existing &GAPDoc; manual, it might be
interesting for you to use &AutoDoc; for two purposes:
<P/>
First, with &AutoDoc; it is very convenient to regenerate your
documentation.
<P/>
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 <F>PackageInfo.g</F> is fully automated this way
(including the correct version, release data, author information
and so on).
<P/>
There are various examples of packages using &AutoDoc; for
this purpose only, e.g. &io; and <Package>orb</Package>.
<P/>
In particular, this setup works well if you want to keep your existing manual
structure and only adopt selected &AutoDoc; features first; for example
automatic title-page data and predefined entities such as
<C>&amp;VERSION;</C>, <C>&amp;RELEASEYEAR;</C> and <C>&amp;RELEASEDATE;</C>
(see Section <Ref Sect="Subsection_Tut:PackageInfo:Entities"/>).
<P/>
<Subsection Label="Subsection_Tut:IntegrateExisting:EverythingThere">
<Heading>Using &AutoDoc; on a complete &GAPDoc; manual</Heading>

<P/>
Suppose you already have a complete XML manual, with some main and title
XML files and some documentation for operations distributed over
all your <F>.g</F>, <F>.gd</F>, and <F>.gi</F> files.
Suppose the main XML file is named <F>PACKAGENAME.xml</F> and is in the
<F>/doc</F> 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:
<Listing><![CDATA[
LoadPackage( "AutoDoc" );
AutoDoc( );
]]></Listing>
Note that in particular, you do not have to worry about keeping a list of your
implementation files up-to-date.
<P/>
But there is more. &AutoDoc; can create <F>.tst</F> files from the
examples in your manual to test your package. This can be achieved via
<Listing><![CDATA[
LoadPackage( "AutoDoc" );
AutoDoc( rec( extract_examples := true ) );
]]></Listing>
Now files <F>PACKAGENAME01.tst</F>, <F>PACKAGENAME02.tst</F> and so appear in the
<F>tst/</F> subdirectory of your package, and can be tested as usual using
<Ref BookName="ref" Func="Test"/> respectively <Ref BookName="ref" Func="TestDirectory"/>.
<P/>
If you prefer to keep generated tests in a separate location, set
<C>extract_examples.subdir</C> to a path relative to the package root:
<Listing><![CDATA[
LoadPackage( "AutoDoc" );
AutoDoc( rec( extract_examples := rec( subdir := "tst/generated" ) ) );
]]></Listing>
This writes the extracted examples into <F>tst/generated/</F> instead.
<P/>
</Subsection>

<Subsection Label="Subsection_Tut:IntegrateExisting:GapDocOptions">
<Heading>Setting different &GAPDoc; options</Heading>

<P/>
Sometimes, the default values for the &GAPDoc; command used by &AutoDoc;
may not be suitable for your manual.
<P/>
 Suppose your main XML file is <E>not</E> named <F>PACKAGENAME.xml</F>, but rather something else, e.g. <F>main.xml</F>.
Then you can tell &AutoDoc; to use this file as the main XML file via
<Listing><![CDATA[
LoadPackage( "AutoDoc" );
AutoDoc( rec( gapdoc := rec( main := "main" ) ) );
]]></Listing>
<P/>
&AutoDoc; can scan directories for documentation input automatically.
In fact there are two separate scanning steps.
The option <C>autodoc.scan_dirs</C> controls where it looks for source comments beginning with
<C>#!</C> and for standalone <F>.autodoc</F> files.
By default, it scans the package root directory and the subdirectories <F>gap</F>,
<F>lib</F>, <F>examples</F> and <F>examples/doc</F>; the listed subdirectories are
scanned recursively, while the package root itself is only scanned at top level.
If you keep that kind of input in other directories, adjust <C>autodoc.scan_dirs</C>.
The following example instructs &AutoDoc; to only search in the subdirectory
<F>package_sources</F> of the package's root directory for those files.
<Listing><![CDATA[
LoadPackage( "AutoDoc" );
AutoDoc( rec( autodoc := rec( scan_dirs := [ "package_sources" ] ) ) );
]]></Listing>
The separate option <C>gapdoc.scan_dirs</C> serves a different purpose:
it controls where &GAPDoc; comments are searched for.
<P/>
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:
<Listing><![CDATA[
LoadPackage( "AutoDoc" );
AutoDoc( rec( autodoc := rec( files := [ "path/to/some/hidden/file.gd" ] ) ) );
]]></Listing>
Giving such a file does not prevent the standard <C>scan_dirs</C> from being scanned for
other files.
<P/>
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 <Ref Func="AutoDoc"/> will then build the documentation in the <F>doc</F> subdirectory of your package.
From this directory, the gap root directory has the relative path <F>../../..</F>.
Then you can enable the relative paths by
<Listing><![CDATA[
LoadPackage( "AutoDoc" );
AutoDoc( rec( gapdoc := rec( gap_root_relative_path := "../../.." ) ) );
]]></Listing>
or, since <F>../../..</F> is the standard option for <C>gap_root_relative_path</C>, by
<Listing><![CDATA[
LoadPackage( "AutoDoc" );
AutoDoc( rec( gapdoc := rec( gap_root_relative_path := true ) ) );
]]></Listing>
<P/>
The same behavior is also available via the global option
<Code>relativePath</Code>. This is particularly convenient in a short
<F>makedoc.g</F> script, and it overrides <Code>gapdoc.gap_root_relative_path</Code>
if both are given. Since this is a GAP global option, you can also set it
outside the eventual <Ref Func="AutoDoc"/> call and let it propagate through
nested calls; see <Ref Chap="Options Stack" BookName="ref"/> for more
information about GAP's global options system:
<Listing><![CDATA[
LoadPackage( "AutoDoc" );
AutoDoc( rec( autodoc := true ) : relativePath := "../../.." );
]]></Listing>
If you pass <Code>relativePath := true</Code>, then &AutoDoc; uses the default
relative path <F>../../..</F>.
<P/>
For example, if your <F>makedoc.g</F> reads the manual via
<Ref Func="AutoDoc"/>, then the following command sets both
<Code>relativePath</Code> and <Code>nopdf</Code> to <Keyword>true</Keyword> for that nested call:
<Listing><![CDATA[
Read( "makedoc.g" : nopdf, relativePath );
]]></Listing>
<P/>
Finally, if you only want HTML and text output, you can suppress PDF
generation with the global option <Code>nopdf</Code>:
<Listing><![CDATA[
LoadPackage( "AutoDoc" );
AutoDoc( rec( autodoc := true ) : nopdf );
]]></Listing>
This is useful if <Code>pdflatex</Code> is unavailable, or when you want a faster
documentation rebuild while editing.
<P/>
You can also request the same behavior from the shell by setting the
environment variable <Code>NOPDF</Code> before invoking <F>makedoc.g</F>. For
example:
<Listing><![CDATA[
NOPDF=1 gap makedoc.g
]]></Listing>
If <Code>NOPDF</Code> is set, &AutoDoc; skips PDF generation even if no
<Code>nopdf</Code> option is given in the GAP code.
<P/>
</Subsection>

<Subsection Label="Subsection_Tut:Checklist">
<Heading>Checklist for converting an existing &GAPDoc; manual to use &AutoDoc;</Heading>

<P/>
Here is a checklist for authors of a package &PackageName;, 
<E>which already has a &GAPDoc; based manual</E>, who wish to use &AutoDoc; 
to build the manual from now on. 
We assume that the manual is currently built by reading a file 
<File>makedoc.g</File> and that the main <File>.xml</File> file 
is named <File>manual.xml</File>. 
<P/>
The files <File>PackageInfo.g</File>, <File>makedoc.g</File>, 
<File>doc/title.xml</File> and <File>doc/_main.xml</File>
(if it exists) will be altered by this procedure, 
so it may be wise to keep backup copies. 
<P/>
You should have copies of the &AutoDoc; files <File>PackageInfo.g</File> 
and <File>makedoc.g</File> to hand when reading these instructions. 
<P/>
<List>
<Item> 
Copy <File>AutoDoc/makedoc.g</File> to <File>PackageName/makedoc.g</File>. 
</Item>
<Item>
Edit <File>PackageName/makedoc.g</File> as follows. 
  <List>
  <Item> 
  Change the header comment to match other files in your package. 
  </Item> 
  <Item> 
  After <Code>LoadPackage("AutoDoc");</Code> 
  add <Code>LoadPackage("PackageName");</Code>. 
  </Item> 
  <Item> 
  In the <Code>AutoDoc</Code> record delete <Code>autodoc := true;</Code>. 
  </Item>
  <Item> 
<Index Key="Scaffold record in makedoc.g"></Index>
  In the <Code>scaffold</Code> record change the <Code>includes</Code> list 
  to be the list of your <Code>.xml</Code> files that are contained in  
  <File>manual.xml</File>. 
  </Item> 
  <Item>
<Index Key="Bibliography field in makedoc.g"></Index>
  If you do not have a bibliography you may delete the 
  <Code>bib := "bib.xml",</Code> field in the scaffold. 
  Otherwise, edit the file name if you have a different file. 
  If you only have a <Code>.bib</Code> file  
  (<Code>manual.bib</Code> or <Code>bib.xml.bib</Code> say) 
  you should rename this file <File>PackageName.bib</File>. 
  </Item>
  <Item> 
<Index Key="LaTeXOptions record in makedoc.g"></Index>
  In the <Code>LaTeXOptions</Code> record,
  which is in the <Code>gapdoc</Code> record, enter any
  &LaTeX; <Code>newcommands</Code> previously in <File>manual.xml</File>. 
  (If there are none you may safely delete this record.) 
  To illustrate this option, the &AutoDoc; file <File>makedoc.g</File>
  defines the command <Code>\bbZ</Code>
  by <Code>\newcommand{\bbZ}{\mathbb{Z}}</Code>,
  which may be used to produce
  the &LaTeX; formula <M>f : \bbZ^2 \to \bbZ</M>.
  However, note that this only works in the PDF version of the file.
  </Item>
  </List>
</Item> 
<Item> 
Now edit <File>PackageName/PackageInfo.g</File> as follows. 
  <List>
  <Item> 
  Delete any <Code>PKGVERSIONDATA</Code> chunk that may be there. 
  One reason for converting your manual to use &AutoDoc; is to stop
  using entities such as <Code>PACKAGENAMEVERSION</Code>. 
  </Item>
  <Item> 
  Copy the <Code>AutoDoc</Code> record from <File>AutoDoc/PackageInfo.g</File> 
  to the end of your file (just before the final <Code>"));"</Code>. 
  </Item>
  <Item> 
<Index Key="Copyright field in PackageInfo.g"></Index>
<Index Key="Abstract field in PackageInfo.g"></Index>
<Index Key="Acknowledgements field in PackageInfo.g"></Index>
  Replace the <Code>Copyright</Code>, <Code>Abstract</Code> and 
  <Code>Acknowledgements</Code> fields of the <Code>TitlePage</Code> 
  record with the corresponding material from your <File>manual.xml</File>. 
  (If you do not have an abstract, then delete the 
  <Code>Abstract</Code> field, etc.) 
<!--  For other introductory components, such as <Code>Colophon</Code>, -->
<!--  consult the file <File>gap/Magic.gd</File>. -->
  </Item>
  <Item> 
<Index Key="Entities record in makedoc.g"></Index>
  In the <Code>entities</Code> record enter any entities 
  previously stored in your <File>manual.xml</File>. 
  (Again, if you have none, you may safely delete this record.) 
  To illustrate this option the &AutoDoc; file <File>PackageInfo.g</File> 
  defines entities for the names of packages &io; and &PackageName;. 
  </Item> 
  </List> 
</Item>
<Item> 
If you are using a GitHub repository, as well as running 
"<Code>git add</Code>" on files <File>makedoc.g</File>, 
<File>PackageInfo.g</File> and <File>doc/PackageName.bib</File>, 
you should run "<Code>git rm -f</Code>" on files <File>doc/manual.xml</File>, 
and <File>doc/title.xml</File>. 
</Item> 
</List>
You should now be ready to run &GAP; and <Code>Read("makedoc.g");</Code> 
in your package root directory. 
<P/>
</Subsection>

</Section>

<Section Label="Section_Tut:Scaffolds">
<Heading>Scaffolds</Heading>

<P/>
<!-- TODO: insert an introduction here -->
<P/>
<Subsection Label="Subsection_Tut:Scaffolds:Title">
<Heading>Generating a title page</Heading>

<P/>
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.
<P/>
All this data is also contained in your <F>PackageInfo.g</F>, 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 <F>PackageInfo.g</F>
files:
<Listing><![CDATA[
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>
]]></Listing>
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.
<P/>
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 <F>PackageInfo.g</F>. The following commands do just that
(in addition to building your manual), by generating a file called
<F>doc/title.xml</F>.
<Listing><![CDATA[
LoadPackage( "AutoDoc" );
AutoDoc( rec( scaffold := rec( MainPage := false ) ) );
]]></Listing>
Note that this only outputs <F>doc/title.xml</F> but does not
touch any other files of your documentation. In particular, you need
to explicitly include <F>doc/title.xml</F> from your main XML file.
<P/>
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. 
<P/>
</Subsection>

<Subsection Label="Subsection_Tut:Scaffolds:Main">
<Heading>Generating the main XML file</Heading>

<P/>
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.
<Listing><![CDATA[
LoadPackage( "AutoDoc" );
AutoDoc( rec( scaffold := true ) );
]]></Listing>
<P/>
You can instruct &AutoDoc; to include additional XML files by giving it
a list of filenames, as in the following example:
<Listing><![CDATA[
LoadPackage( "AutoDoc" );
AutoDoc(rec(
    scaffold := rec(
        includes := [ "somefile.xml", "anotherfile.xml" ]
    )
));
]]></Listing>
<P/>
For more information, please consult the documentation
of the <Ref Func="AutoDoc"/> function.
<P/>
</Subsection>

<Subsection Label="Subsection_Tut:PackageInfo">
<Heading>What data is used from <F>PackageInfo.g</F>?</Heading>

<P/>
&AutoDoc; can use data from <F>PackageInfo.g</F> in order to
generate a title page. Specifically, the following components
of the package info record are taken into account:
<P/>
<List>
<Mark>PackageName</Mark><Item>
This is used to set the <Code>&lt;Title&gt;</Code> element of the
title page.
</Item>
<Mark>Subtitle</Mark><Item>
This is used to set the <Code>&lt;Subtitle&gt;</Code> element of the
title page.
</Item>
<Mark>Version</Mark><Item>
This is used to set the <Code>&lt;Version&gt;</Code> element of the
title page, with the string <Q>Version </Q> prepended.
</Item>
<Mark>Date</Mark><Item>
This is used to set the <Code>&lt;Date&gt;</Code> element of the
title page.
</Item>
<Mark>Persons</Mark><Item>
This is used to generate <Code>&lt;Author&gt;</Code> elements in the
generated title page.
</Item>
<Mark>PackageDoc</Mark><Item>
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 <C>PackageDoc.BookName</C> component
and then passes that on to &GAPDoc; when creating the HTML, PDF
and text versions of the manual.
</Item>
<Mark>AutoDoc</Mark><Item>
This record controls extra settings used by &AutoDoc; while generating the
manual. In particular, <C>PkgInfo.AutoDoc.TitlePage</C> lets you add or
override title-page elements coming from package metadata.
<P/>
Typical fields you may set there include <C>TitleComment</C>,
<C>Abstract</C>, <C>Copyright</C>, <C>Acknowledgements</C> and <C>Colophon</C>.
For example, in <F>PackageInfo.g</F>:
<Listing><![CDATA[
SetPackageInfo( rec(
  ...
  AutoDoc := rec(
    TitlePage := rec(
      Copyright := "(C) 2026 Jane Doe",
      Acknowledgements := "Funded by Example Grant 1234."
    )
  )
) );
]]></Listing>
This inserts <Code>&lt;Copyright&gt;</Code> and <Code>&lt;Acknowledgements&gt;</Code> blocks into
the generated <F>title.xml</F>.
<P/>
<C>PkgInfo.AutoDoc.TitlePage</C> has exactly the same meaning as
<C>scaffold.TitlePage</C> in <Ref Func="AutoDoc"/>. The function documentation
for <C>scaffold.TitlePage</C> points back to this subsection.
</Item>
</List>
<P/>
</Subsection>

<Subsection Label="Subsection_Tut:PackageInfo:Entities">
<Heading>Entities from <F>PackageInfo.g</F> and scaffold options</Heading>

<P/>
Besides title-page fields, you can define custom entities in
<C>AutoDoc.entities</C> inside <F>PackageInfo.g</F>.
They are written to <F>doc/_entities.xml</F>, so they can be used both by
generated main files and by hand-written main XML files.
<P/>
In addition, &AutoDoc; predefines the entities <C>VERSION</C>,
<C>RELEASEYEAR</C> and <C>RELEASEDATE</C>, derived from package metadata.
This is useful if you keep a custom title page or custom chapters and still
want release information to stay synchronized with <F>PackageInfo.g</F>.
<P/>
You can specify scaffold-related settings in <F>PackageInfo.g</F> and in your
<F>makedoc.g</F> call at the same time; both records are merged, and values
from <F>makedoc.g</F> take precedence when both define the same key.
<P/>
</Subsection>

</Section>

<Section Label="Section_Tut:WorksheetsPointer">
<Heading>Worksheets</Heading>

<P/>
For stand-alone documents that are not tied to a package, use
<Ref Func="AutoDocWorksheet"/>. Its documentation and examples are in
Section <Ref Sect="Section_AutoDocWorksheet"/> of chapter
<Ref Chap="AutoDoc"/>.
</Section>

</Chapter>