  
  [1X1 [33X[0;0YGetting started using [5XAutoDoc[105X[101X[1X[133X[101X
  
  [33X[0;0Y[5XAutoDoc[105X  is  a  [5XGAP[105X  package  which  is  meant to aid [5XGAP[105X package authors in
  creating  and  maintaining  the  documentation  of  their  packages. In this
  capacity      it     builds     upon     the     [5XGAPDoc[105X     package     (see
  [7Xhttps://www.gap-system.org/Packages/gapdoc.html[107X).  As  such,  it  is  not  a
  replacement for [5XGAPDoc[105X, but rather complements it.[133X
  
  [33X[0;0YIn  this  chapter  we  describe  how  to  get started using [5XAutoDoc[105X for your
  package.  First, we explain in Section [14X1.1[114X how to write a new package manual
  from scratch.[133X
  
  [33X[0;0YThen  we  show in Section [14X1.3[114X how you might benefit from [5XAutoDoc[105X even if you
  already have a complete manual written using [5XGAPDoc[105X.[133X
  
  [33X[0;0YIn  Section [14X1.4[114X, we explain how you may use [5XAutoDoc[105X to generate a title page
  and the main XML file for your manual.[133X
  
  [33X[0;0YFinally,  Section  [14X1.5[114X,  explains what [5XAutoDoc[105X worksheets are and how to use
  them.[133X
  
  
  [1X1.1 [33X[0;0YCreating a package manual from scratch[133X[101X
  
  [33X[0;0YSuppose  your  package  is already up and running, but so far has no manual.
  Then  you  can  rapidly  generate  a [21Xscaffold[121X for a package manual using the
  [2XAutoDoc[102X  ([14X4.1-1[114X)  command  like  this,  while  running  [5XGAP[105X from within your
  package's directory (the one containing the [11XPackageInfo.g[111X file):[133X
  
  [4X[32X[104X
    [4XLoadPackage( "AutoDoc" );[104X
    [4XAutoDoc( rec( scaffold := true ) );[104X
  [4X[32X[104X
  
  [33X[0;0YThis  first  reads  the  [11XPackageInfo.g[111X  file  from the current directory. It
  extracts  information  about  package from it (such as its name and version,
  see     Section     [14X1.4-1[114X).     It    then    creates    two    XML    files
  [11Xdoc/NAME_OF_YOUR_PACKAGE.xml[111X and [11Xdoc/title.xml[111X inside the package directory.
  Finally,  it  runs  [5XGAPDoc[105X  on  them  to produce a nice initial PDF and HTML
  version of your fresh manual.[133X
  
  [33X[0;0YTo  ensure that the [5XGAP[105X help system picks up your package manual, you should
  also add something like the following to your [11XPackageInfo.g[111X:[133X
  
  [4X[32X[104X
    [4XPackageDoc := rec([104X
    [4X  BookName  := ~.PackageName,[104X
    [4X  ArchiveURLSubset := ["doc"],[104X
    [4X  HTMLStart := "doc/chap0.html",[104X
    [4X  PDFFile   := "doc/manual.pdf",[104X
    [4X  SixFile   := "doc/manual.six",[104X
    [4X  LongTitle := ~.Subtitle,[104X
    [4X),[104X
  [4X[32X[104X
  
  [33X[0;0YCongratulations, your package now has a minimal working manual. Of course it
  will  be  mostly  empty  for  now, but it already should contain some useful
  information,  based  on  the  data in your [11XPackageInfo.g[111X. This includes your
  package's  name,  version  and  description as well as information about its
  authors.  And  if you ever change the package data, (e.g. because your email
  address  changed),  just re-run the above command to regenerate the two main
  XML files with the latest information.[133X
  
  [33X[0;0YNext  of  course  you need to provide actual content (unfortunately, we were
  not  yet  able  to  automate  [13Xthat[113X  for  you,  more  research  on artificial
  intelligence  is  required).  To add more content, you have several options:
  You  could  add further [5XGAPDoc[105X XML files containing extra chapters, sections
  and  so  on. Or you could use classic [5XGAPDoc[105X source comments. For details on
  either,  please  refer  to  [14X'GAPDoc:  Distributing  a  Document into Several
  Files'[114X,  as  well  as Section [14X1.3[114X of this manual on how to teach the [2XAutoDoc[102X
  ([14X4.1-1[114X)  command  to  include this extra documentation. Or you could use the
  special documentation facilities [5XAutoDoc[105X provides (see Section [14X1.2[114X).[133X
  
  [33X[0;0YYou  will  probably  want  to re-run the [2XAutoDoc[102X ([14X4.1-1[114X) command frequently,
  e.g. whenever you modified your documentation or your [11XPackageInfo.g[111X. To make
  this  more  convenient and reproducible, we recommend putting its invocation
  into  a  file [11Xmakedoc.g[111X in your package directory, with content based on the
  following example:[133X
  
  [4X[32X[104X
    [4XLoadPackage( "AutoDoc" );[104X
    [4XAutoDoc( rec( autodoc := true ) );[104X
    [4XQUIT;[104X
  [4X[32X[104X
  
  [33X[0;0YThen  you  can  regenerate the package manual from the command line with the
  following command, executed from within in the package directory:[133X
  
  [4X[32X[104X
    [4Xgap makedoc.g[104X
  [4X[32X[104X
  
  
  [1X1.2 [33X[0;0YDocumenting code with [5XAutoDoc[105X[101X[1X[133X[101X
  
  [33X[0;0YTo  get  one of your global functions, operations, attributes etc. to appear
  in  the  package  manual,  simply  insert  an [5XAutoDoc[105X comment of the form [10X#![110X
  directly in front of it. For example:[133X
  
  [4X[32X[104X
    [4X#![104X
    [4XDeclareOperation( "ToricVariety", [ IsConvexObject ] );[104X
  [4X[32X[104X
  
  [33X[0;0YThis  tiny change is already sufficient to ensure that the operation appears
  in  the  manual.  In general, you will want to add further information about
  the operation, such as in the following example:[133X
  
  [4X[32X[104X
    [4X#! @Arguments conv[104X
    [4X#! @Returns a toric variety[104X
    [4X#! @Description[104X
    [4X#!  Creates a toric variety out[104X
    [4X#!  of the convex object <A>conv</A>.[104X
    [4XDeclareOperation( "ToricVariety", [ IsConvexObject ] );[104X
  [4X[32X[104X
  
  [33X[0;0YFor  a  thorough  description  of what you can do with [5XAutoDoc[105X documentation
  comments, please refer to chapter [14X2[114X.[133X
  
  [33X[0;0YSuppose  you  have not been using [5XGAPDoc[105X before but instead used the process
  described  in  section  [14X1.1[114X  to  create  your manual. Then the following [5XGAP[105X
  command  will  regenerate  the  manual  and  automatically include all newly
  documented functions, operations etc.:[133X
  
  [4X[32X[104X
    [4XLoadPackage( "AutoDoc" );[104X
    [4XAutoDoc( rec( scaffold := true,[104X
    [4X              autodoc := true ) );[104X
  [4X[32X[104X
  
  [33X[0;0YIf  you are not using the scaffolding feature, e.g. because you already have
  an   existing   [5XGAPDoc[105X   based  manual,  then  you  can  still  use  [5XAutoDoc[105X
  documentation  comments.  Just  make sure to first edit the main XML file of
  your documentation, and insert the line[133X
  
  [4X[32X[104X
    [4X<#Include SYSTEM "_AutoDocMainFile.xml">[104X
  [4X[32X[104X
  
  [33X[0;0Yin  a  suitable  place.  This  means  that you can mix [5XAutoDoc[105X documentation
  comment freely with your existing documentation; you can even still make use
  of  any  existing  [5XGAPDoc[105X documentation comments in your code. The following
  command  should  be  useful for you in this case; it still scans the package
  code  for [5XAutoDoc[105X documentation comments and the runs [5XGAPDoc[105X to produce HTML
  and PDF output, but does not touch your documentation XML files otherwise.[133X
  
  [4X[32X[104X
    [4XLoadPackage( "AutoDoc" );[104X
    [4XAutoDoc( rec( autodoc := true ) );[104X
  [4X[32X[104X
  
  
  [1X1.3 [33X[0;0YUsing [5XAutoDoc[105X[101X[1X in an existing [5XGAPDoc[105X[101X[1X manual[133X[101X
  
  [33X[0;0YEven  if you already have an existing [5XGAPDoc[105X manual, it might be interesting
  for you to use [5XAutoDoc[105X for two purposes:[133X
  
  [33X[0;0YFirst off, with [5XAutoDoc[105X is very convenient to regenerate your documentation.[133X
  
  [33X[0;0YSecondly,  the scaffolding feature which generates a title page with all the
  metadata  of  your  package  in  a  uniform  way is very handy. The somewhat
  tedious  process  of keeping your title page in sync with your [11XPackageInfo.g[111X
  is  fully  automated  this way (including the correct version, release data,
  author information and so on).[133X
  
  [33X[0;0YThere  are various examples of packages using [5XAutoDoc[105X for only this purpose,
  e.g. [5Xio[105X and [5Xorb[105X.[133X
  
  
  [1X1.3-1 [33X[0;0YUsing [5XAutoDoc[105X[101X[1X on a complete [5XGAPDoc[105X[101X[1X manual[133X[101X
  
  [33X[0;0YSuppose you already have a complete XML manual, with some main and title XML
  files  and  some  documentation for operations distributed over all your [11X.g[111X,
  [11X.gd[111X,  and  [11X.gi[111X files. Suppose the main XML file is named [11XPACKAGENAME.xml[111X and
  is  in  the  [11X/doc[111X  subdirectory  of  your package. Then you can rebuild your
  manual  by  executing  the  following  two  [5XGAP[105X commands from a [5XGAP[105X sessions
  started started in the root directory of your package:[133X
  
  [4X[32X[104X
    [4XLoadPackage( "AutoDoc" );[104X
    [4XAutoDoc( );[104X
  [4X[32X[104X
  
  [33X[0;0YIn  contrast,  the  [5XRingsForHomalg[105X  currently uses essentially the following
  code in its [11Xmakedoc.g[111X file to achieve the same result[133X
  
  [4X[32X[104X
    [4XLoadPackage( "GAPDoc" );[104X
    [4XSetGapDocLaTeXOptions( "utf8" );[104X
    [4Xbib := ParseBibFiles( "doc/RingsForHomalg.bib" );[104X
    [4XWriteBibXMLextFile( "doc/RingsForHomalgBib.xml", bib );[104X
    [4Xlist := [[104X
    [4X         "../gap/RingsForHomalg.gd",[104X
    [4X         "../gap/RingsForHomalg.gi",[104X
    [4X         "../gap/Singular.gi",[104X
    [4X         "../gap/SingularBasic.gi",[104X
    [4X         "../examples/RingConstructionsExternalGAP.g",[104X
    [4X         "../examples/RingConstructionsSingular.g",[104X
    [4X         "../examples/RingConstructionsMAGMA.g",[104X
    [4X         "../examples/RingConstructionsMacaulay2.g",[104X
    [4X         "../examples/RingConstructionsSage.g",[104X
    [4X         "../examples/RingConstructionsMaple.g",[104X
    [4X         ];[104X
    [4XMakeGAPDocDoc( "doc", "RingsForHomalg", list, "RingsForHomalg" );[104X
    [4XGAPDocManualLab( "RingsForHomalg" );[104X
  [4X[32X[104X
  
  [33X[0;0YNote  that  in  particular, you do not have to worry about keeping a list of
  your implementation files up-to-date.[133X
  
  [33X[0;0YBut  there  is more. [5XAutoDoc[105X can create [11X.tst[111X files from the examples in your
  manual to test your package. This can be achieved via[133X
  
  [4X[32X[104X
    [4XLoadPackage( "AutoDoc" );[104X
    [4XAutoDoc( rec( extract_examples := true ) );[104X
  [4X[32X[104X
  
  [33X[0;0YNow  files  [11XPACKAGENAME01.tst[111X,  [11XPACKAGENAME02.tst[111X  and so appear in the [11Xtst/[111X
  subdirectory  of  your  package,  and  can  be  tested  as  usual using [2XTest[102X
  ([14XReference: Test[114X) respectively [2XTestDirectory[102X ([14XReference: TestDirectory[114X).[133X
  
  
  [1X1.3-2 [33X[0;0YSetting different [5XGAPDoc[105X[101X[1X options[133X[101X
  
  [33X[0;0YSometimes, the default values for the [5XGAPDoc[105X command used by [5XAutoDoc[105X may not
  be suitable for your manual.[133X
  
  [33X[0;0YSuppose  your  main  XML  file  is  [13Xnot[113X  named  [11XPACKAGENAME.xml[111X,  but rather
  something else, e.g. [11Xmain.xml[111X. Then you can tell [5XAutoDoc[105X to use this file as
  the main XML file via[133X
  
  [4X[32X[104X
    [4XLoadPackage( "AutoDoc" );[104X
    [4XAutoDoc( rec( gapdoc := rec( main := "main" ) ) );[104X
  [4X[32X[104X
  
  [33X[0;0YAs  explained  above,  by default [5XAutoDoc[105X scans all [11X.g[111X, [11X.gd[111X and [11X.gi[111X files it
  can  find  inside  of your package root directory, and in the subdirectories
  [11Xgap[111X,  [11Xlib[111X,  [11Xexamples[111X and [11Xexamples/doc[111X as well. If you keep source files with
  documentation  in  other directories, you can adjust the list of directories
  AutoDoc  scans  via  the [10Xscan_dirs[110X option. The following example illustrates
  this   by   instructing   [5XAutoDoc[105X   to   only  search  in  the  subdirectory
  [11Xpackage_sources[111X of the packages root directory.[133X
  
  [4X[32X[104X
    [4XLoadPackage( "AutoDoc" );[104X
    [4XAutoDoc( rec( gapdoc := rec( scan_dirs := [ "package_sources" ] ) ) );[104X
  [4X[32X[104X
  
  [33X[0;0YYou  can  also  specify  an explicit list of files containing documentation,
  which  will  be  searched  in  addition to any files located within the scan
  directories:[133X
  
  [4X[32X[104X
    [4XLoadPackage( "AutoDoc" );[104X
    [4XAutoDoc( rec( gapdoc := rec( files := [ "path/to/some/hidden/file.gds" ] ) ) );[104X
  [4X[32X[104X
  
  [33X[0;0YGiving  such  a  file  does  not  prevent  the standard [10Xscan_dirs[110X from being
  scanned for other files.[133X
  
  [33X[0;0YNext,  [5XGAPDoc[105X  supports  the  documentation to be built with relative paths.
  This  means,  links to manuals of other packages or the [5XGAP[105X library will not
  be  absolute, but relative from your documentation. This can be particularly
  useful  if you want to build a release tarball or move your [5XGAP[105X installation
  around  later. Suppose you are starting [5XGAP[105X in the root path of your package
  as  always,  and  the  standard  call of [2XAutoDoc[102X ([14X4.1-1[114X) will then build the
  documentation  in the [11Xdoc[111X subdirectory of your package. From this directory,
  the  gap  root directory has the relative path [11X../../..[111X. Then you can enable
  the relative paths by[133X
  
  [4X[32X[104X
    [4XLoadPackage( "AutoDoc" );[104X
    [4XAutoDoc( rec( gapdoc := rec( gap_root_relative_path := "../../.." ) ) );[104X
  [4X[32X[104X
  
  [33X[0;0Yor, since [11X../../..[111X is the standard option for [10Xgap_root_relative_path[110X, by[133X
  
  [4X[32X[104X
    [4XLoadPackage( "AutoDoc" );[104X
    [4XAutoDoc( rec( gapdoc := rec( gap_root_relative_path := true ) ) );[104X
  [4X[32X[104X
  
  
  [1X1.3-3 [33X[0;0YChecklist for converting an existing [5XGAPDoc[105X[101X[1X manual to use [5XAutoDoc[105X[101X[1X[133X[101X
  
  [33X[0;0YHere  is a checklist for authors of a package [5XPackageName[105X, [13Xwhich already has
  a  [5XGAPDoc[105X based manual[113X, who wish to use [5XAutoDoc[105X to build the manual from now
  on. We assume that the manual is currently built by reading a file [11Xmakedoc.g[111X
  and that the main [11X.xml[111X file is named [11Xmanual.xml[111X.[133X
  
  [33X[0;0YThe  files  [11XPackageInfo.g[111X,  [11Xmakedoc.g[111X, [11Xdoc/title.xml[111X and [11Xdoc/PackageName.xml[111X
  (if  it exists) will be altered by this procedure, so it may be wise to keep
  backup copies.[133X
  
  [33X[0;0YYou  should  have copies of the [5XAutoDoc[105X files [11XPackageInfo.g[111X and [11Xmakedoc.g[111X to
  hand when reading these instructions.[133X
  
  [30X    [33X[0;6YCopy [11XAutoDoc/makedoc.g[111X to [11XPackageName/makedoc.g[111X.[133X
  
  [30X    [33X[0;6YEdit [11XPackageName/makedoc.g[111X as follows.[133X
  
        [30X    [33X[0;12YChange the header comment to match other files in your package.[133X
  
        [30X    [33X[0;12YAfter [10XLoadPackage("AutoDoc");[110X add [10XLoadPackage("PackageName");[110X.[133X
  
        [30X    [33X[0;12YIn the [10XAutoDoc[110X record delete [10Xautodoc := true;[110X.[133X
  
        [30X    [33X[0;12YIn  the  [10Xscaffold[110X record change the [10Xincludes[110X list to be the list
              of your [10X.xml[110X files that are contained in [11Xmanual.xml[111X.[133X
  
        [30X    [33X[0;12YIf  you  do  not  have  a bibliography you may delete the [10Xbib :=
              "bib.xml",[110X  field in the scaffold. Otherwise, edit the file name
              if  you  have  a  different  file.  If you only have a [10X.bib[110X file
              ([10Xmanual.bib[110X  or  [10Xbib.xml.bib[110X  say)  you  should rename this file
              [11XPackageName.bib[111X.[133X
  
        [30X    [33X[0;12YIn the [10XLaTeXOptions[110X record, which is in the [10Xgapdoc[110X record, enter
              any  LaTeX  [10Xnewcommands[110X  previously in [11Xmanual.xml[111X. (If there are
              none  you  may  safely  delete  this record.) To illustrate this
              option,  the  [5XAutoDoc[105X file [11Xmakedoc.g[111X defines the command [10X\bbZ[110X by
              [10X\newcommand{\bbZ}{\mathbb{Z}}[110X,  which may be used to produce the
              LaTeX formula [22Xf : bbZ^2 -> bbZ[122X.[133X
  
        [30X    [33X[0;12YIn  the  [10Xentities[110X record enter any entities previously stored in
              [11Xmanual.xml[111X. (Again, if you have none, you may safely delete this
              record.)  To  illustrate  this option the [5XAutoDoc[105X file [11Xmakedoc.g[111X
              defines entities for the names of packages [5Xio[105X and [5XPackageName[105X.[133X
  
  [30X    [33X[0;6YNow edit [11XPackageName/PackageInfo.g[111X as follows.[133X
  
        [30X    [33X[0;12YDelete  any  [10XPKGVERSIONDATA[110X  chunk that may be there. One reason
              for  converting  your  manual  to  use  [5XAutoDoc[105X is to stop using
              entities such as [10XPACKAGENAMEVERSION[110X.[133X
  
        [30X    [33X[0;12YCopy the [10XAutoDoc[110X record from [11XAutoDoc/PackageInfo.g[111X to the end of
              your file (just before the final [10X"));"[110X.[133X
  
        [30X    [33X[0;12YReplace  the  [10XCopyright[110X, [10XAbstract[110X and [10XAcknowledgements[110X fields of
              the  [10XTitlePage[110X  record with the corresponding material from your
              [11Xmanual.xml[111X.  (If  you  do  not have an abstract, then delete the
              [10XAbstract[110X field, etc.) For other introductory components, such as
              [10XColophon[110X, consult the file [11Xgap/Magic.gd[111X.[133X
  
  [30X    [33X[0;6YIf  you are using a GitHub repository, as well as running "[10Xgit add[110X" on
        files [11Xmakedoc.g[111X, [11XPackageInfo.g[111X and [11Xdoc/PackageName.bib[111X, you should run
        "[10Xgit rm -f[110X" on files [11Xdoc/manual.xml[111X, and [11Xdoc/title.xml[111X.[133X
  
  [33X[0;0YYou  should  now  be ready to run [5XGAP[105X and [10XRead("makedoc.g");[110X in your package
  root directory.[133X
  
  
  [1X1.4 [33X[0;0YScaffolds[133X[101X
  
  
  [1X1.4-1 [33X[0;0YGenerating a title page[133X[101X
  
  [33X[0;0YFor  most  (if  not  all) [5XGAP[105X packages, the title page of the package manual
  lists  information  such  as  the  release  date, version, names and contact
  details  of  the authors, and so on. All this data is also contained in your
  [11XPackageInfo.g[111X,  and whenever you make a change to that file, there is a risk
  that you forget to update your manual to match. And even if you don't forget
  it,  you  of course have to spend some time to adjust the manual. [5XGAPDoc[105X can
  help  to  a degree with this via entities. Thus, you will sometimes see code
  like this in [11XPackageInfo.g[111X files:[133X
  
  [4X[32X[104X
    [4XVersion        := "1.2.3",[104X
    [4XDate           := "20/01/2015",[104X
    [4X##  <#GAPDoc Label="PKGVERSIONDATA">[104X
    [4X##  <!ENTITY VERSION "1.2.3">[104X
    [4X##  <!ENTITY RELEASEDATE "20 January 2015">[104X
    [4X##  <!ENTITY RELEASEYEAR "2015">[104X
    [4X##  <#/GAPDoc>[104X
  [4X[32X[104X
  
  [33X[0;0YHowever,  it  is still easy to forget both of these versions. And it doesn't
  solve the problem of updating package authors addresses. Neither of these is
  a  big  issue,  of  course,  but there have been plenty examples in the past
  where  people  forget  either  of  these  two things, and it can be slightly
  embarrassing.  It may even require you to make a new release just to fix the
  issue, which in our opinion is a sad waste of your valuable time.[133X
  
  [33X[0;0YSo  instead  of  worrying about manually synchronising these things, you can
  instruct  [5XAutoDoc[105X  to  generate  a  title  page for your manual based on the
  information  in  your [11XPackageInfo.g[111X. The following commands do just that (in
  addition   to   building   your   manual),   by  generating  a  file  called
  [11Xdoc/title.xml[111X.[133X
  
  [4X[32X[104X
    [4XLoadPackage( "AutoDoc" );[104X
    [4XAutoDoc( rec( scaffold := rec( MainPage := false ) ) );[104X
  [4X[32X[104X
  
  [33X[0;0YNote that this only outputs [11Xdoc/title.xml[111X but does not touch any other files
  of  your  documentation.  In  particular,  you  need  to  explicitly include
  [11Xdoc/title.xml[111X from your main XML file.[133X
  
  [33X[0;0YHowever, you can also tell [5XAutoDoc[105X to maintain the main XML file for you, in
  which  case  this  is  automatic. In fact, this is the default if you enable
  scaffolding;  the  above  example  command  explicitly  told  [5XAutoDoc[105X not to
  generate a main page.[133X
  
  
  [1X1.4-2 [33X[0;0YGenerating the main XML file[133X[101X
  
  [33X[0;0YThe  following  generates a main XML file for your documentation in addition
  to  the title page. The main XML file includes the title page by default, as
  well as any documentation generated from [5XAutoDoc[105X documentation comments.[133X
  
  [4X[32X[104X
    [4XLoadPackage( "AutoDoc" );[104X
    [4XAutoDoc( rec( scaffold := true ) );[104X
  [4X[32X[104X
  
  [33X[0;0YYou can instruct [5XAutoDoc[105X to include additional XML files by giving it a list
  of filenames, as in the following example:[133X
  
  [4X[32X[104X
    [4XLoadPackage( "AutoDoc" );[104X
    [4XAutoDoc(rec([104X
    [4X    scaffold := rec([104X
    [4X        includes := [ "somefile.xml", "anotherfile.xml" ][104X
    [4X    )[104X
    [4X));[104X
  [4X[32X[104X
  
  [33X[0;0YFor  more  information,  please  consult  the  documentation  of the [2XAutoDoc[102X
  ([14X4.1-1[114X) function.[133X
  
  
  [1X1.4-3 [33X[0;0YWhat data is used from [11XPackageInfo.g[111X[101X[1X?[133X[101X
  
  [33X[0;0Y[5XAutoDoc[105X  can  use data from [11XPackageInfo.g[111X in order to generate a title page.
  Specifically,  the following components of the package info record are taken
  into account:[133X
  
  [8XPackageName[108X
        [33X[0;6YThis is used to set the [10X<Title>[110X element of the title page.[133X
  
  [8XSubtitle[108X
        [33X[0;6YThis is used to set the [10X<Subtitle>[110X element of the title page.[133X
  
  [8XVersion[108X
        [33X[0;6YThis  is used to set the [10X<Version>[110X element of the title page, with the
        string [21XVersion [121X prepended.[133X
  
  [8XDate[108X
        [33X[0;6YThis is used to set the [10X<Date>[110X element of the title page.[133X
  
  [8XPersons[108X
        [33X[0;6YThis  is  used  to  generate  [10X<Author>[110X elements in the generated title
        page.[133X
  
  [8XPackageDoc[108X
        [33X[0;6YThis  is a record (or a list of records) which is used to tell the [5XGAP[105X
        help  system  about the package manual. Currently [5XAutoDoc[105X extracts the
        value  of the [10XPackageDoc.BookName[110X component and then passes that on to
        [5XGAPDoc[105X when creating the HTML, PDF and text versions of the manual.[133X
  
  [8XAutoDoc[108X
        [33X[0;6YThis  is  a  record  which  can  be  used  to  control the scaffolding
        performed  by  [5XAutoDoc[105X,  specifically to provide extra information for
        the  title  page. For example, you can set [10XAutoDoc.TitlePage.Copyright[110X
        to  a  string which will then be inserted on the generated title page.
        Using this method you can customize the following title page elements:
        [10XTitleComment[110X, [10XAbstract[110X, [10XCopyright[110X, [10XAcknowledgements[110X and [10XColophon[110X.[133X
  
        [33X[0;6YNote   that   [10XAutoDoc.TitlePage[110X   behaves  exactly  the  same  as  the
        [10Xscaffold.TitlePage[110X parameter of the [2XAutoDoc[102X ([14X4.1-1[114X) function.[133X
  
  
  [1X1.5 [33X[0;0YAutoDoc worksheets[133X[101X
  
  [33X[0;0Y[5XAutoDoc[105X  worksheets  can  be  used  to  create  HTML and PDF documents using
  AutoDoc  syntax  and  possibly  including  [5XGAP[105X  examples and implementations
  without  having  them  associated to a package. A file for a worksheet could
  look like this:[133X
  
  [4X[32X[104X
    [4X#! @Title My first worksheet[104X
    [4X#! @Author Charlie Brown[104X
    [4X[104X
    [4X#! @Chapter Some groups[104X
    [4X[104X
    [4X#! @BeginExample[104X
    [4XS3 := SymmetricGroup( 3 );;[104X
    [4XS4 := SymmetricGroup( 4 );;[104X
    [4X#! @EndExample[104X
  [4X[32X[104X
  
  [33X[0;0YNow,  one  can  create a PDF and HTML document, like a package documentation
  out  of  it.  Suppose the document above is saved as [11Xworksheet.g[111X. Then, when
  [5XGAP[105X is started in the directory of this file, the command[133X
  
  [4X[32X[104X
    [4XAutoDocWorksheet( "worksheet.g" );[104X
  [4X[32X[104X
  
  [33X[0;0Ywill  create  a subdirectory called [11Xdoc[111X of the current directory in which it
  will  create  the  documentation. There are several options to configure the
  output  of  the worksheet command, which are identical to the options of the
  [2XAutoDoc[102X  ([14X4.1-1[114X)  command.  It  is even possible to test the examples in the
  worksheet using the [10Xextract_examples[110X option of the [2XAutoDoc[102X ([14X4.1-1[114X) command.[133X
  
  [33X[0;0YSince the worksheets do not have a [11XPackageInfo.g[111X to extract information, all
  possible  tags  that  [5XGAPDoc[105X supports for the title page can be set into the
  document. A fully typed title page can look like this:[133X
  
  [4X[32X[104X
    [4X#! @Title My first worksheet[104X
    [4X#! @Subtitle Some small examples[104X
    [4X#! @Author Charlie Brown[104X
    [4X[104X
    [4X#! @Version 0.1[104X
    [4X#! @TitleComment Some worksheet[104X
    [4X#! @Date 01/01/2016[104X
    [4X#! @Address TU Kaiserslautern[104X
    [4X#! @Abstract[104X
    [4X#!  A worksheet showing some small examples about groups.[104X
    [4X#! @Copyright 2016 Charlie Brown[104X
    [4X#! @Acknowledgements Woodstock[104X
    [4X#! @Colophon Some colophon[104X
    [4X[104X
    [4X#! @Chapter Some groups[104X
    [4X[104X
    [4X#! @BeginExample[104X
    [4XS3 := SymmetricGroup( 3 );;[104X
    [4XS4 := SymmetricGroup( 4 );;[104X
    [4X#! @EndExample[104X
  [4X[32X[104X
  
