  
  [1X4 [33X[0;0YAutoDoc[133X[101X
  
  
  [1X4.1 [33X[0;0YThe AutoDoc() function[133X[101X
  
  [1X4.1-1 AutoDoc[101X
  
  [29X[2XAutoDoc[102X( [3Xpackage_name[103X[, [3Xoption_record[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 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_name[103X[108X
        [33X[0;6YThe name of the package whose documentation should be(re)generated.[133X
  
  [8X[3Xoption_record[103X[108X
        [33X[0;6Y[3Xoption_record[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 main and title page of the package's 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  [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 [11XAutoDocMainFile.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[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[3XTitlePage[103X[108X
                    [33X[0;18YA record whose entries are used to embellish the generated
                    titlepage  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 titlepage, please refer
                    to the [5XGAPDoc[105X manual, specifically section [14X'GAPDoc: Title'[114X
                    and following.[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
                    and  .g  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[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
  
