  
  [1X4 [33X[0;0YReference[133X[101X
  
  
  [1X4.1 [33X[0;0YAutoDoc worksheets[133X[101X
  
  [1X4.1-1 AutoDocWorksheet[101X
  
  [33X[1;0Y[29X[2XAutoDocWorksheet[102X( [[3Xfilenames[103X][,] [[3Xoptrec[103X] ) [32X function[133X
  
  [33X[0;0YThe  purpose  of  this  function is to create stand-alone PDF and HTML files
  using [5XAutoDoc[105X without associating them with a package.[133X
  
  [33X[0;0YInstead of a package directory, you pass one filename or a list of filenames
  containing  [5XAutoDoc[105X  text  from  which the document is created. Settings are
  supplied  via  an  optional  record  using  the  same  entries as the [3Xoptrec[103X
  argument  of  [2XAutoDoc[102X  ([14X4.3-1[114X).  Alternatively,  you  may omit [3Xfilenames[103X and
  specify the files via [10Xoptrec.autodoc.files[110X.[133X
  
  [33X[0;0YA  simple  worksheet  file  can  define  title-page  information and chapter
  content  directly  in  the source file, including example blocks. If this is
  stored in [11Xworksheet.g[111X, you can generate documentation via[133X
  
  [4X[32X  Example  [32X[104X
    [4X[28X AutoDocWorksheet( "worksheet.g" );[128X[104X
  [4X[32X[104X
  
  [33X[0;0YThis creates documentation in a [11Xdoc[111X subdirectory of the current directory.[133X
  
  [33X[0;0YSince  worksheets  do  not  have  a  [11XPackageInfo.g[111X,  title-page  fields  are
  specified directly in the worksheet file.[133X
  
  [33X[0;0YFor backwards compatibility, worksheet calls still accept GAP global options
  for  specifying  the  option-record  entries such as [10Xdir[110X, [10Xscaffold[110X, [10Xautodoc[110X,
  [10Xgapdoc[110X, and [10Xextract_examples[110X. However, this feature is deprecated.[133X
  
  
  [1X4.2 [33X[0;0YExtracting manual examples[133X[101X
  
  [1X4.2-1 AutoDocExtractExamples[101X
  
  [33X[1;0Y[29X[2XAutoDocExtractExamples[102X( [3Xpkg[103X[, [3Xmakedoc[103X] ) [32X function[133X
  [6XReturns:[106X  [33X[0;10Ya directory[133X
  
  [33X[0;0YExtracts  the  examples  from  the manual of the package [3Xpkg[103X and returns the
  directory holding the resulting [11X.tst[111X files.[133X
  
  [33X[0;0Y[3Xpkg[103X  is  either the name of a package or a directory object pointing at one.
  The  optional  argument  [3Xmakedoc[103X  names  the script to read, and defaults to
  [11Xmakedoc.g[111X.[133X
  
  [33X[0;0YThe  package's  own  [11Xmakedoc.g[111X is used as-is, so the settings which describe
  the  manual  —  its source files, scaffolding and [3Xextract_examples[103X options —
  are  not  duplicated.  Only  the  parts  of the manual needed to collect the
  examples are built, no HTML or PDF is produced, and everything is written to
  a  temporary  directory,  so  this  works even when the package directory is
  read-only.[133X
  
  [33X[0;0YThis  is  meant to be used from a package's [11Xtst/testall.g[111X, so that extracted
  tests need not be committed to the repository:[133X
  
  [4X[32X[104X
    [4X  LoadPackage( "mypkg" );[104X
    [4X  dirs := DirectoriesPackageLibrary( "mypkg", "tst" );[104X
    [4X  Add( dirs, AutoDocExtractExamples( "mypkg" ) );[104X
    [4X  TestDirectory( dirs, rec( exitGAP := true ) );[104X
  [4X[32X[104X
  
  [33X[0;0YNote  that [11Xmakedoc.g[111X is read in the usual way, so any other work it performs
  still happens; and a script ending in [10XQUIT[110X cannot be used this way.[133X
  
  
  [1X4.3 [33X[0;0YThe AutoDoc() function[133X[101X
  
  [1X4.3-1 AutoDoc[101X
  
  [33X[1;0Y[29X[2XAutoDoc[102X( [[3Xpkgdir[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/_main.xml[111X 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, using
        documentation  comments  and  commands.  This  produces additional 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;0YThese  tasks  can  be  enabled  independently,  so you can use as much or as
  little  of [5XAutoDoc[105X as your package currently needs. For more information and
  some examples, please refer to Chapter [14X2[114X.[133X
  
  [33X[0;0YIf  exactly  one  parameter is given, it is interpreted as [10Xoptrec[110X if it is a
  record, and as [10Xpkgdir[110X otherwise.[133X
  
  [33X[0;0YThe parameters have the following meaning:[133X
  
  [8X[3Xpkgdir[103X[8X[108X
        [33X[0;6YThis  optional parameter is used to determine the package directory in
        which  [5XAutoDoc[105X  will  operate, and to find the metadata concerning the
        package  being  documented.  If  given,  it  should  be an [10XIsDirectory[110X
        object.  If  the  argument  is  omitted, then [5XAutoDoc[105X checks if it was
        called from a [11Xmakedoc.g[111X 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 [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;6YFor  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 [5XGAP[105X knows about. However, this
        is  deprecated, as it is unreliable in the presence of multiple copies
        of a package.[133X
  
        [33X[0;6YNote that when using [10XAutoDocWorksheet[110X (see [14X4.1[114X), there is no parameter
        corresponding  to  [3Xpkgdir[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 an [10XIsDirectory[110X
              object.  (Thus,  the only way to designate an absolute directory
              is  with an [10XIsDirectory[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;12YControls  whether and how to generate scaffold XML files for the
              package documentation; see [14X4.3-3[114X.[133X
  
        [8X[3Xautodoc[103X[8X[108X
              [33X[0;12YControls   whether   and   how   to   generate   additional  XML
              documentation   files  by  scanning  for  [5XAutoDoc[105X  documentation
              comments; see [14X4.3-5[114X.[133X
  
        [8X[3Xgapdoc[103X[8X[108X
              [33X[0;12YControls  whether  and  how to invoke [5XGAPDoc[105X to create HTML, PDF
              and text files from your various XML files; see [14X4.3-6[114X.[133X
  
        [8X[3Xextract_examples[103X[8X[108X
              [33X[0;12YControls  whether  and  how  to extract the manual examples into
              test files; see [14X4.3-7[114X.[133X
  
  [33X[0;0YThe  function  also checks some GAP global options, which are not entries of
  [3Xoptrec[103X; see [14X4.3-8[114X.[133X
  
  [1X4.3-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(InfoAutoDoc, 0)[110X.
  Default value is 1.[133X
  
  
  [1X4.3-3 [33X[0;0YScaffold options[133X[101X
  
  [33X[0;0YThe  entry  [3Xoptrec.scaffold[103X  of  [2XAutoDoc[102X ([14X4.3-1[114X) controls whether and how to
  generate scaffold XML files for the package documentation.[133X
  
  [33X[0;0YThe  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 [3Xoptrec.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 [3Xoptrec.scaffold[103X is [9Xfalse[109X), scaffolding is disabled.[133X
  
  [33X[0;0YIf  scaffolding  is  enabled,  and  [10XPackageInfo.AutoDoc[110X  exists,  then it is
  assumed  to be a record, and its contents are used as default values for the
  scaffold settings.[133X
  
  [33X[0;0YIf [3Xoptrec.scaffold[103X is a record, it may contain the following entries.[133X
  
  [8X[3Xincludes[103X[8X[108X
        [33X[0;6YA  list  of XML files to be included in the body of the main XML file.
        They are included in the order in which they are given. 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;6YBy  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;6YThis  entry  is  similar  to  [3Xoptrec.scaffold.includes[103X  but is used to
        specify  files  to  include  after  the  main body of the manual, i.e.
        typically  appendices  written  directly  in  [5XGAPDoc[105X  XML.  Appendices
        created  with  [10X@Appendix[110X  are included automatically after these files
        when scaffolding generates the main XML file.[133X
  
  [8X[3Xbib[103X[8X[108X
        [33X[0;6YThe  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[3Xbibstyle[103X[8X[108X
        [33X[0;6YOverrides  the  bibliography  style  used  for  LaTeX  output. This is
        written  as  the  [10XStyle[110X attribute of the generated [10X<Bibliography .../>[110X
        element,  so  valid values are the bibliography style names understood
        by [5XGAPDoc[105X and BibTeX, such as [10Xalpha[110X, [10Xalphaurl[110X, or [10Xplain[110X.[133X
  
  [8X[3Xentities[103X[8X[108X
        [33X[0;6YA record defining additional XML entities; see [14X4.3-4[114X.[133X
  
  [8X[3XTitlePage[103X[8X[108X
        [33X[0;6YA  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[133X
  
  [4X      [32X[104X
          [4X     rec( Acknowledgements := "Many thanks to ..." )[104X
        [4X[32X[104X
  
        [33X[0;6YIf  this  is set in [11XPackageInfo.g[111X as [10XPkgInfo.AutoDoc.TitlePage[110X, it has
        the same meaning as this option; see subsection [14X2.5-3[114X in chapter [14X2[114X for
        details and an example.[133X
  
        [33X[0;6YFor  the  list  of  valid  title-page elements, see the [5XGAPDoc[105X manual,
        specifically section [14X'GAPDoc: TitlePage'[114X.[133X
  
  [8X[3XMainPage[103X[8X[108X
        [33X[0;6YIf  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;6YSets  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;6YReplaces 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
  
  
  [1X4.3-4 [33X[0;0YScaffold entities[133X[101X
  
  [33X[0;0YThe entry [3Xoptrec.scaffold.entities[103X of [2XAutoDoc[102X ([14X4.3-1[114X) is a record whose keys
  are  taken  as  entity  names, set to the corresponding (string) values. For
  example, if you pass the record[133X
  
  [4X[32X[104X
    [4X rec( SomePackage := "<Package>SomePackage</Package>",[104X
    [4X      RELEASEYEAR := "2015" )[104X
  [4X[32X[104X
  
  [33X[0;0Ythen the following entity definitions are added to the XML preamble:[133X
  
  [4X[32X[104X
    [4X<!ENTITY SomePackage '<Package>SomePackage</Package>'>[104X
    [4X <!ENTITY RELEASEYEAR '2015'>[104X
  [4X[32X[104X
  
  [33X[0;0YThis   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
  
  [33X[0;0YNote that [5XAutoDoc[105X predefines several entities:[133X
  
  [8X[3XVERSION[103X[8X[108X
        [33X[0;6YSet to the [10XVersion[110X field of your package info record.[133X
  
  [8X[3XRELEASEYEAR[103X[8X[108X
        [33X[0;6YSet  to a string containing the release year, as derived from the [10XDate[110X
        field of your package info record.[133X
  
  [8X[3XRELEASEDATE[103X[8X[108X
        [33X[0;6YDerived from the [10XDate[110X field of your package info record.[133X
  
  [8X[3XSomePackage[103X[8X[108X
        [33X[0;6YThe  precise name of this entity is derived from the [10XPackageName[110X field
        of  your  package  info  record.  Note  that it is case sensitive. The
        content is defined as suggested by the example above.[133X
  
  
  [1X4.3-5 [33X[0;0YOptions for scanning AutoDoc comments[133X[101X
  
  [33X[0;0YThe  entry  [3Xoptrec.autodoc[103X  of  [2XAutoDoc[102X  ([14X4.3-1[114X) controls whether and how to
  generate   additional  XML  documentation  files  by  scanning  for  [5XAutoDoc[105X
  documentation comments.[133X
  
  [33X[0;0YThe  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 [3Xoptrec.autodoc[103X is missing but the
  package  depends  (directly)  on the [5XAutoDoc[105X package. In all other cases (in
  particular if [3Xoptrec.autodoc[103X is [9Xfalse[109X), this feature is disabled.[133X
  
  [33X[0;0YIf [3Xoptrec.autodoc[103X is a record, it may contain the following entries.[133X
  
  [8X[3Xfiles[103X[8X[108X
        [33X[0;6YA  list of files (given by paths relative to the package directory) to
        be scanned for [5XAutoDoc[105X documentation comments. They are scanned in the
        order  in which they are given, and always before the files scanned by
        [3Xautodoc.scan_dirs[103X.  Unless  the  order  of  files  is important, it is
        usually more convenient to use [3Xautodoc.scan_dirs[103X, see below.[133X
  
  [8X[3Xscan_dirs[103X[8X[108X
        [33X[0;6YA  list  of subdirectories of the package directory (given as relative
        paths)  which  [5XAutoDoc[105X  then  scans  recursively for .gi, .gd, .g, and
        .autodoc  files;  all  of  these  files  are  then scanned for [5XAutoDoc[105X
        documentation  comments.  The  directories are scanned in the order in
        which  they  are given, and the files in each directory are scanned in
        lexicographic  order.  The  special entries [10X"."[110X and [10X""[110X still only scan
        the  package root itself. This controls where [5XAutoDoc[105X looks for source
        comments  beginning with [10X#![110X and for standalone [11X.autodoc[111X files. It does
        not  affect where [5XGAPDoc[105X looks for GAPDoc comments; that is controlled
        separately by [3Xgapdoc.scan_dirs[103X.[133X
        [33X[0;6Y[13XDefault value: [10X[ ".", "gap", "lib", "examples", "examples/doc" ][110X.[113X[133X
  
  
  [1X4.3-6 [33X[0;0YOptions for GAPDoc[133X[101X
  
  [33X[0;0YThe  entry  [3Xoptrec.gapdoc[103X  of  [2XAutoDoc[102X  ([14X4.3-1[114X)  controls whether and how to
  invoke  [5XGAPDoc[105X  to  create  HTML,  PDF  and text files from your various XML
  files.[133X
  
  [33X[0;0YThe  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 [3Xoptrec.gapdoc[103X is missing. In all
  other  cases  (in  particular  if  [3Xoptrec.gapdoc[103X  is [9Xfalse[109X), this feature is
  disabled.[133X
  
  [33X[0;0YIf [3Xoptrec.gapdoc[103X is a record, it may contain the following entries.[133X
  
  [8X[3Xmain[103X[8X[108X
        [33X[0;6YThe  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;6Y[13XDefault  value:  [10X_main.xml[110X  when  scaffolding  is  enabled for package
        manuals, otherwise [10XPACKAGENAME.xml[110X.[113X[133X
  
  [8X[3Xfiles[103X[8X[108X
        [33X[0;6YA  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;6YA  list  of subdirectories of the package directory (given as relative
        paths) which [5XAutoDoc[105X then scans recursively for .gi, .gd and .g files;
        all of these files are then scanned for [5XGAPDoc[105X documentation comments.
        The  special  entries  [10X"."[110X  and  [10X""[110X  still  only scan the package root
        itself.  This controls only where [5XGAPDoc[105X comments are searched for. It
        does not affect where [5XAutoDoc[105X looks for source comments beginning with
        [10X#![110X or for [11X.autodoc[111X files; use [3Xautodoc.scan_dirs[103X for that.[133X
        [33X[0;6Y[13XDefault value: [10X[ ".", "gap", "lib", "examples", "examples/doc" ][110X.[113X[133X
  
  [8X[3XLaTeXOptions[103X[8X[108X
        [33X[0;6YMust   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;6YEither  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;6YThus,  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;6YOn  a technical level, [5XAutoDoc[105X passes the relative path to the [3Xgaproot[103X
        parameter of [2XMakeGAPDocDoc[102X ([14XGAPDoc: MakeGAPDocDoc[114X)[133X
  
  
  [1X4.3-7 [33X[0;0YOptions for extracting examples[133X[101X
  
  [33X[0;0YThe  entry [3Xoptrec.extract_examples[103X of [2XAutoDoc[102X ([14X4.3-1[114X) must be either [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;0YIf set to a record, it may contain the following entries:[133X
  
  [8Xsubdir[108X
        [33X[0;6YA  string  or  [10XDirectory()[110X  object  selecting where the generated [11X.tst[111X
        files  are  written.  The  default is [11Xtst[111X. If a string is given, it is
        interpreted  relative  to  the  package  directory,  so values such as
        [11Xtst/generated[111X are supported.[133X
  
  [8Xunits[108X
        [33X[0;6YThis  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;6YOn  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;6YIf  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.3-8 [33X[0;0YGlobal options[133X[101X
  
  [33X[0;0Y[2XAutoDoc[102X  ([14X4.3-1[114X)  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 [3Xoptrec[103X. See [14X'Reference: Options Stack'[114X for more
  information about GAP's global options system.[133X
  
  [8X[3Xnopdf[103X[8X[108X
        [33X[0;6YIf this global option is set to [9Xtrue[109X, then [5XAutoDoc[105X tells [5XGAPDoc[105X not to
        build  the  PDF  version of the manual. HTML and text output are still
        generated.[133X
  
        [33X[0;6YThis  is useful on systems without a working [10Xpdflatex[110X installation, or
        when you only need the non-PDF outputs while iterating on the manual.[133X
  
        [33X[0;6YFor example:[133X
  
  [4X      [32X[104X
          [4X     AutoDoc( rec( autodoc := true ) : nopdf );[104X
        [4X[32X[104X
  
        [33X[0;6YAlso,  if  the environment variable [10XNOPDF[110X is set, then [5XAutoDoc[105X behaves
        as if the global option [3Xnopdf[103X had been enabled.[133X
  
  [8X[3XAutoDocExtractOnly[103X[8X[108X
        [33X[0;6YIf  this  global  option  is  set,  [5XAutoDoc[105X builds only as much of the
        manual  as  is  needed to collect its examples: no HTML, PDF or manual
        index  is  produced, and all output is written below the given scratch
        directory  instead  of  the package. The extracted tests end up in its
        [11Xtst[111X subdirectory.[133X
  
        [33X[0;6YThe value is a directory, or [9Xtrue[109X to have one chosen automatically. If
        the  environment variable [10XAUTODOC_EXTRACT_ONLY[110X is set, [5XAutoDoc[105X behaves
        as if this option had been given; that is useful for a [11Xmakedoc.g[111X which
        ends in [10XQUIT[110X and therefore has to be run as a separate process.[133X
  
        [33X[0;6YRather than setting this by hand, use [2XAutoDocExtractExamples[102X ([14X4.2-1[114X).[133X
  
  [8X[3XrelativePath[103X[8X[108X
        [33X[0;6YThis  has  the  same effect as [3Xgapdoc.gap_root_relative_path[103X, but as a
        GAP  global option. It takes precedence over that record entry if both
        are specified.[133X
  
        [33X[0;6YIf  [3XrelativePath[103X  is  [9Xtrue[109X, then the default relative path [11X../../..[111X is
        used. If it is a string, then that string is used as the relative path
        from the documentation directory to the GAP root.[133X
  
        [33X[0;6YFor example:[133X
  
  [4X      [32X[104X
          [4X     AutoDoc( rec( autodoc := true ) : relativePath := "../../.." );[104X
        [4X[32X[104X
  
  [33X[0;0YIn particular, a call such as[133X
  
  [4X[32X[104X
    [4X Read( "makedoc.g" : nopdf, relativePath );[104X
  [4X[32X[104X
  
  [33X[0;0Ysets  both  global  options  to [9Xtrue[109X, and they remain visible to the [2XAutoDoc[102X
  ([14X4.3-1[114X) call inside [11Xmakedoc.g[111X.[133X
  
