  
  [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( [3Xlist_of_filenames:[103X [3Xoptions[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;0YIt  uses the same optional record entries as [2XAutoDoc[102X ([14X4.2-1[114X), but instead of
  a  package  name,  you  pass  one filename or a list of filenames containing
  [5XAutoDoc[105X text from which the document is created.[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
  
  
  [1X4.2 [33X[0;0YThe AutoDoc() function[133X[101X
  
  [1X4.2-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/_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;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 [14X4.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  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;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[3Xbibstyle[103X[8X[108X
                    [33X[0;18YOverrides  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;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
  
                    [33X[0;18YNote that [5XAutoDoc[105X predefines several entities:[133X
  
                    [8X[3XVERSION[103X[8X[108X
                          [33X[0;24YSet  to  the  [10XVersion[110X  field  of  your  package info
                          record.[133X
  
                    [8X[3XRELEASEYEAR[103X[8X[108X
                          [33X[0;24YSet  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;24YDerived  from  the  [10XDate[110X  field of your package info
                          record.[133X
  
                    [8X[3XSomePackage[103X[8X[108X
                          [33X[0;24YThe  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
  
              [8X[3XTitlePage[103X[8X[108X
                    [33X[0;18YA  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;18YIf     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;18YFor  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;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 recursively
                    for  .gi,  .gd, .g, and .autodoc files; all of these files
                    are  then  scanned for [5XAutoDoc[105X documentation comments. 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;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:  [10X_main.xml[110X when scaffolding is enabled for
                    package manuals, otherwise [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 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;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;12YIf set to a record, it may contain the following entries:[133X
  
              [8Xsubdir[108X
                    [33X[0;18YA   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;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
  
  [33X[0;0YThe  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 [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[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
  call inside [11Xmakedoc.g[111X.[133X
  
  [1X4.2-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
  
