  
  [1X4 [33X[0;0YAutoDoc[133X[101X
  
  
  [1X4.1 [33X[0;0YThe AutoDoc() function[133X[101X
  
  [1X4.1-1 AutoDoc[101X
  
  [29X[2XAutoDoc[102X( [[3Xpackage[103X[, [3Xoptrec[103X]] ) [32X function
  [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 three 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[3Xpackage[103X[108X
        [33X[0;6YThis  is  either the name of package, or an [10XIsDirectory[110X object. In the
        former  case, [5XAutoDoc[105X uses the metadata of the first package with that
        name  known  to  [5XGAP[105X.  In the latter case, it checks whether the given
        directory  contains  a  [11XPackageInfo.g[111X  file,  and  extracts all needed
        metadata  from  that.  This 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;6YIf this argument is omitted, [5XAutoDoc[105X uses the [10XDirectoryCurrent()[110X.[133X
  
  [8X[3Xoptrec[103X[108X
        [33X[0;6Y[3Xoptrec[103X can be a record with some additional options. The following are
        currently supported:[133X
  
        [8X[3Xdir[103X[108X
              [33X[0;12YThis  should  be  a  string  containing  a  (relative) path or a
              Directory()  object  specifying  where the package documentation
              (i.e. the [5XGAPDoc[105X XML files) are stored.[133X
              [33X[0;12Y[13XDefault value: [10X"doc/"[110X.[113X[133X
  
        [8X[3Xscaffold[103X[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[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[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[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[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[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
                      [4Xrec( SomePackage := "<Package>SomePackage</Package>",[104X
                      [4XRELEASEYEAR := "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[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
                      [4Xrec( 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[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[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[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 GAPDoc's latexheader.tex file for an example.[133X
  
              [8X[3Xgapdoc_latex_options[103X[108X
                    [33X[0;18YMust  be  a record with entries which can be understood by
                    SetGapDocLaTeXOptions.  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[3Xautodoc[103X[108X
              [33X[0;12YThis   controls   whether  and  how  to  generate  addition  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[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[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[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[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[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[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[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[3Xgap_root_relative_path[103X[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 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.[133X
                    [33X[0;18YThus,  if  a relative path is provided via this option (or
                    if  it  is  set  to  true, 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 GAP 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[3Xmaketest[103X[108X
              [33X[0;12YThe  maketest  item  can be true or a record. When it is true, a
              simple  maketest.g  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
  
