  
  [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  content  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 := "<Package>SomePackage</Package>",[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
                      [4X<!ENTITY SomePackage '<Package>SomePackage</Package>'>[104X
                      [4X             <!ENTITY RELEASEYEAR '2015'>[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
  
        [8X[3Xmaketest[103X[8X[108X
              [33X[0;12Y[13XThis option is deprecated. Please use [10Xextract_examples[110X instead.[113X[133X
  
              [33X[0;12YEither  [9Xtrue[109X  or  a record. When it is [9Xtrue[109X, a simple [11Xmaketest.g[111X
              file is created in the main package directory, which can be used
              to test the examples from the manual. As a record, the entry can
              have the following entries itself, to specify some options.[133X
  
              [8Xfilename[108X
                    [33X[0;18YSets the name of the test file.[133X
  
              [8Xcommands[108X
                    [33X[0;18YA  list  of  strings,  each  one  a command, which will be
                    executed at the beginning of the test file.[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
  
