Reference
AutoDoc worksheets The purpose of this function is to create stand-alone PDF and HTML files using &AutoDoc; without associating them with a package.

Instead of a package directory, you pass one filename or a list of filenames containing &AutoDoc; text from which the document is created. Settings are supplied via an optional record using the same entries as the optrec argument of . Alternatively, you may omit filenames and specify the files via optrec.autodoc.files.

A simple worksheet file can define title-page information and chapter content directly in the source file, including example blocks. If this is stored in worksheet.g, you can generate documentation via AutoDocWorksheet( "worksheet.g" ); This creates documentation in a doc subdirectory of the current directory.

Since worksheets do not have a PackageInfo.g, title-page fields are specified directly in the worksheet file.

For backwards compatibility, worksheet calls still accept GAP global options for specifying the option-record entries such as dir, scaffold, autodoc, gapdoc, and extract_examples. However, this feature is deprecated.
The AutoDoc() function nothing 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/_main.xml which is used as main XML file for the package manual, i.e. this file sets the XML doctype and defines various XML entities, includes other XML files (both those generated by &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, using documentation comments and commands. This produces additional 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 ). These tasks can be enabled independently, so you can use as much or as little of &AutoDoc; as your package currently needs. For more information and some examples, please refer to Chapter .

The parameters have the following meanings: pkgdir This optional parameter is used to determine the package directory in which &AutoDoc; will operate, and to find the metadata concerning the package being documented. If given, it should be an IsDirectory object. If the argument is omitted, then &AutoDoc; checks if it was called from a makedoc.g file or similar, and if so, uses the directory this is contained in. Otherwise the current directory is used. In both cases, the specified directory must contain a 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.

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

Note that when using AutoDocWorksheet (see ), there is no parameter corresponding to pkgdir and so the package directory is always the current directory, and there is no metadata. optrec optrec 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 written directly in &GAPDoc; XML. Appendices created with @Appendix are included automatically after these files when scaffolding generates the main XML file. 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. bibstyle Overrides the bibliography style used for LaTeX output. This is written as the Style attribute of the generated <Bibliography .../> element, so valid values are the bibliography style names understood by &GAPDoc; and BibTeX, such as alpha, alphaurl, or plain. entities A record whose keys are taken as entity names, set to the corresponding (string) values. For example, if you pass the record SomePackage,

                 rec( SomePackage := "<Package>SomePackage</Package>",
                      RELEASEYEAR := "2015" )

then the following entity definitions are added to the XML preamble:

    <!ENTITY SomePackage '<Package>SomePackage</Package>'>
                 <!ENTITY RELEASEYEAR '2015'>

This allows you to write &SomePackage; and &RELEASEYEAR; in your documentation, which will be replaced by respective values specified in the entities definition.

Note that &AutoDoc; predefines several entities: VERSION Set to the Version field of your package info record. RELEASEYEAR Set to a string containing the release year, as derived from the Date field of your package info record. RELEASEDATE Derived from the Date field of your package info record. SomePackage The precise name of this entity is derived from the PackageName field of your package info record. Note that it is case sensitive. The content is defined as suggested by the example above. TitlePage A record with extra title-page fields for the generated manual. Field names are interpreted as title-page XML element names, and their values are written as element content. For example, you can set a custom acknowledgements block with

                 rec( Acknowledgements := "Many thanks to ..." )

If this is set in PackageInfo.g as PkgInfo.AutoDoc.TitlePage, it has the same meaning as this option; see subsection in chapter for details and an example.

For the list of valid title-page elements, see 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 false document_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 recursively for .gi, .gd, .g, and .autodoc files; all of these files are then scanned for &AutoDoc; documentation comments. The special entries "." and "" still only scan the package root itself. This controls where &AutoDoc; looks for source comments beginning with #! and for standalone .autodoc files. It does not affect where &GAPDoc; looks for GAPDoc comments; that is controlled separately by gapdoc.scan_dirs.
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: _main.xml when scaffolding is enabled for package manuals, otherwise 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 recursively for .gi, .gd and .g files; all of these files are then scanned for &GAPDoc; documentation comments. The special entries "." and "" still only scan the package root itself. This controls only where &GAPDoc; comments are searched for. It does not affect where &AutoDoc; looks for source comments beginning with #! or for .autodoc files; use autodoc.scan_dirs for that.
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.

If set to a record, it may contain the following entries: subdir A string or Directory() object selecting where the generated .tst files are written. The default is tst. If a string is given, it is interpreted relative to the package directory, so values such as tst/generated are supported. 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.

The function also checks the following GAP global options, i.e. options supplied via GAP's value-option syntax and visible through nested calls. These are not entries of optrec. See for more information about GAP's global options system. nopdf If this global option is set to true, then &AutoDoc; tells &GAPDoc; not to build the PDF version of the manual. HTML and text output are still generated.

This is useful on systems without a working `pdflatex` installation, or when you only need the non-PDF outputs while iterating on the manual.

For example:

         AutoDoc( rec( autodoc := true ) : nopdf );

Also, if the environment variable `NOPDF` is set, then &AutoDoc; behaves as if the global option nopdf had been enabled. relativePath This has the same effect as gapdoc.gap_root_relative_path, but as a GAP global option. It takes precedence over that record entry if both are specified.

If relativePath is true, then the default relative path ../../.. is used. If it is a string, then that string is used as the relative path from the documentation directory to the GAP root.

For example:

         AutoDoc( rec( autodoc := true ) : relativePath := "../../.." );

In particular, a call such as

     Read( "makedoc.g" : nopdf, relativePath );

sets both global options to true, and they remain visible to the call inside makedoc.g.

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(InfoAutoDoc, 0). Default value is 1.