chap4.txt

  
  4 AutoDoc
  
  
  4.1 The AutoDoc() function
  
  4.1-1 AutoDoc
  
  AutoDoc( [package[, optrec]] )  function
  Returns:  nothing
  
  This  is  the  main  function  of  the  AutoDoc  package. It can perform any
  combination of the following three tasks:
  
  1   It  can  (re)generate  a scaffold for your package manual. That is, it
        can  produce two XML files in GAPDoc format to be used as part of your
        manual:  First,  a file named doc/PACKAGENAME.xml (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 AutoDoc as
        well  as  additional  files  created  by other means), tells GAPDoc to
        generate  a  table  of  content  and  an index, and more. Secondly, it
        creates  a  file  doc/title.xml  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
        PackageInfo.g.
  
  2   It  can  scan  your  package for AutoDoc based documentation (by using
        AutoDoc  tags  and  the Autodoc command. This will produce further XML
        files to be used as part of the package manual.
  
  3   It  can  use  GAPDoc  to  generate  PDF,  text  and HTML (with MathJaX
        enabled)  documentation from the GAPDoc XML files it generated as well
        as  additional  such  files  provided  by  you.  For  this, it invokes
        MakeGAPDocDoc  (GAPDoc: MakeGAPDocDoc) to convert the XML sources, and
        it  also  instructs  GAPDoc  to  copy supplementary files (such as CSS
        style  files) into your doc directory (see CopyHTMLStyleFiles (GAPDoc:
        CopyHTMLStyleFiles)).
  
  For more information and some examples, please refer to Chapter 1.
  
  The parameters have the following meanings:
  
  package
        This  is  either the name of package, or an IsDirectory object. In the
        former  case, AutoDoc uses the metadata of the first package with that
        name  known  to  GAP.  In the latter case, it checks whether the given
        directory  contains  a  PackageInfo.g  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.
  
        If this argument is omitted, AutoDoc uses the DirectoryCurrent().
  
  optrec
        optrec can be a record with some additional options. The following are
        currently supported:
  
        dir
              This  should  be  a  string  containing  a  (relative) path or a
              Directory()  object  specifying  where the package documentation
              (i.e. the GAPDoc XML files) are stored.
              Default value: "doc/".
  
        scaffold
              This controls whether and how to generate scaffold XML files for
              the package documentation.
  
              The  value  should be either true, false or a record. If it is a
              record  or true (the latter is equivalent to specifying an empty
              record),  then  this  feature  is enabled. It is also enabled if
              opt.scaffold  is  missing  but  the  package's  info  record  in
              PackageInfo.g  has  an  AutoDoc  entry.  In  all other cases (in
              particular if opt.scaffold is false), scaffolding is disabled.
  
              If  scaffolding is enabled, and PackageInfo.AutoDoc exists, then
              it  is  assumed  to  be  a  record, and its contents are used as
              default values for the scaffold settings.
  
              If  opt.scaffold  is  a  record,  it  may  contain the following
              entries.
  
              includes
                    A list of XML files to be included in the body of the main
                    XML  file.  If  you  specify  this list and also are using
                    AutoDoc to document your operations with AutoDoc comments,
                    you  can  add _AutoDocMainFile.xml to this list to control
                    at  which  point  the documentation produced by AutoDoc is
                    inserted.  If  you  do not do this, it will be added after
                    the last of your own XML files.
  
              index
                    By  default,  the scaffold creates an index. If you do not
                    want an index, set this to false.
  
              appendix
                    This entry is similar to opt.scaffold.includes but is used
                    to  specify  files  to  include after the main body of the
                    manual, i.e. typically appendices.
  
              bib
                    The  name of a bibliography file, in BibTeX or XML format.
                    If   this   key   is   not   set,  but  there  is  a  file
                    doc/PACKAGENAME.bib  then  it  is assumed that you want to
                    use this as your bibliography.
  
              entities
                    A  record whose keys are taken as entity names, set to the
                    corresponding  (string)  values.  For example, if you pass
                    the record SomePackage,
  
                    
                      rec( SomePackage := "<Package>SomePackage</Package>",
                      RELEASEYEAR := "2015" )
                    
  
                    then the following entity definitions are added to the XML
                    preamble:
  
                    
                      <!ENTITY SomePackage '<Package>SomePackage</Package>'>
                      <!ENTITY RELEASEYEAR '2015'>
                    
  
                    This  allows  you to write &SomePackage; and &RELEASEYEAR;
                    in   your   documentation,   which  will  be  replaced  by
                    respective values specified in the entities definition.
  
              TitlePage
                    A 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:
  
                    
                      rec( Acknowledgements := "Many thanks to ..." )
                    
  
                    For  a  list  of  valid  entries in the title page, please
                    refer  to the GAPDoc manual, specifically section 'GAPDoc:
                    TitlePage'.
  
              MainPage
                    If  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 AutoDoc to
                    generate  a title page for you, you can set this option to
                    false
  
              document_class
                    Sets  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.
  
              latex_header_file
                    Replaces  the  standard header from GAPDoc completely with
                    the header in this LaTeX file. Please be careful here, and
                    look at GAPDoc's latexheader.tex file for an example.
  
              gapdoc_latex_options
                    Must  be  a record with entries which can be understood by
                    SetGapDocLaTeXOptions.  Each  entry can be a string, which
                    will  be given to GAPDoc 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 GAPDoc as option with the name of the
                    entry.
  
        autodoc
              This   controls   whether  and  how  to  generate  addition  XML
              documentation   files  by  scanning  for  AutoDoc  documentation
              comments.
  
              The  value  should be either true, false or a record. If it is a
              record  or true (the latter is equivalent to specifying an empty
              record),  then  this  feature  is enabled. It is also enabled if
              opt.autodoc is missing but the package depends (directly) on the
              AutoDoc   package.   In   all  other  cases  (in  particular  if
              opt.autodoc is false), this feature is disabled.
  
              If  opt.autodoc  is  a  record,  it  may  contain  the following
              entries.
  
              files
                    A  list  of  files (given by paths relative to the package
                    directory)   to   be  scanned  for  AutoDoc  documentation
                    comments.   Usually   it   is   more   convenient  to  use
                    autodoc.scan_dirs, see below.
  
              scan_dirs
                    A  list  of subdirectories of the package directory (given
                    as  relative paths) which AutoDoc then scans for .gi, .gd,
                    .g,  and  .autodoc  files;  all  of  these  files are then
                    scanned for AutoDoc documentation comments.
                    Default   value:   [   ".",   "gap",   "lib",  "examples",
                    "examples/doc" ].
  
              level
                    This  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.
  
        gapdoc
              This  controls  whether and how to invoke GAPDoc to create HTML,
              PDF and text files from your various XML files.
  
              The  value  should be either true, false or a record. If it is a
              record  or true (the latter is equivalent to specifying an empty
              record),  then  this  feature  is enabled. It is also enabled if
              opt.gapdoc  is  missing.  In  all  other cases (in particular if
              opt.gapdoc is false), this feature is disabled.
  
              If opt.gapdoc is a record, it may contain the following entries.
  
              main
                    The  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.
                    Default value: PACKAGENAME.xml.
  
              files
                    A  list  of  files (given by paths relative to the package
                    directory)   to   be   scanned  for  GAPDoc  documentation
                    comments.   Usually   it   is   more   convenient  to  use
                    gapdoc.scan_dirs, see below.
  
              scan_dirs
                    A  list  of subdirectories of the package directory (given
                    as  relative  paths) which AutoDoc then scans for .gi, .gd
                    and  .g  files;  all  of  these files are then scanned for
                    GAPDoc documentation comments.
                    Default   value:   [   ".",   "gap",   "lib",  "examples",
                    "examples/doc" ].
  
              gap_root_relative_path
                    Either  a boolean, or a string containing a relative path.
                    By  default  (if  this  option  is  not  set, or is set to
                    false),   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.
                    Thus,  if  a relative path is provided via this option (or
                    if  it  is  set  to  true, in which case the relative path
                    ../../..  is  used),  then  AutoDoc  and GAPDoc attempt to
                    replace all absolute paths in references to GAP manuals by
                    paths based on this relative path.
  
                    On  a technical level, AutoDoc passes the relative path to
                    the    gaproot   parameter   of   MakeGAPDocDoc   (GAPDoc:
                    MakeGAPDocDoc)
  
        maketest
              The  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.
  
              filename
                    Sets the name of the test file.
  
              commands
                    A  list  of  strings,  each  one  a command, which will be
                    executed at the beginning of the test file.
  
  
  4.2 Examples
  
  Some basic examples for using AutoDoc were already shown in Chapter 1.