2 AutoDoc documentation comments
  
  You can document declarations of global functions and variables, operations,
  attributes etc. by inserting AutoDoc comments into your sources before these
  declaration.  An  AutoDoc  comment  always  starts with #!. This is also the
  smallest  possible AutoDoc command. If you want your declaration documented,
  just write #! at the line before the documentation. For example:
  
  
    #!
    DeclareOperation( "AnOperation",
                      [ IsList ] );
  
  
  This will produce a manual entry for the operation AnOperation.
  
  Inside  of AutoDoc comments, AutoDoc commands starting with @ can be used to
  control the output AutoDoc produces.
  
  
  2.1 Documenting declarations
  
  In  the  bare  form above, the manual entry for AnOperation will not contain
  much more than the name of the operation. In order to change this, there are
  several   commands   you  can  put  into  the  AutoDoc  comment  before  the
  declaration. Currently, the following commands are provided:
  
  
  2.1-1 @Description descr
  
  Adds  the  text  in the following lines of the AutoDoc to the description of
  the  declaration  in the manual. Lines are until the next AutoDoc command or
  until the declaration is reached.
  
  
  2.1-2 @Returns ret_val
  
  The  string  ret_val  is added to the documentation, with the text Returns: 
  put  in front of it. This should usually give a brief hint about the type or
  meaning of the value returned by the documented function.
  
  
  2.1-3 @Arguments args
  
  The  string  args  contains  a  description  of  the  arguments the function
  expects, including optional parts, which are denoted by square brackets. The
  argument names can be separated by whitespace, commas or square brackets for
  the  optional  arguments,  like  grp[, elm] or xx[y[z] ]. If GAP options are
  used,  this  can  be followed by a colon : and one or more assignments, like
  n[, r]: tries := 100.
  
  
  2.1-4 @Group grpname
  
  Adds  the  following  method to a group with the given name. See section 2.5
  for more information about groups.
  
  
  2.1-5 @Label label
  
  Adds  label  to  the  function  as label. If this is not specified, then for
  declarations  that  involve  a  list  of  input  filters (as is the case for
  DeclareOperation, DeclareAttribute, etc.), a default label is generated from
  this filter list.
  
  
    #! @Label testlabel
    DeclareProperty( "AProperty",
                     IsObject );
  
  
  leads to this:
  
  2.1-6 AProperty
  
  AProperty( arg )  property
  Returns:  true or false
  
  while
  
  
    #!
    DeclareProperty( "AProperty",
                     IsObject );
  
  
  leads to this:
  
  2.1-7 AProperty
  
  AProperty( arg )  property
  Returns:  true or false
  
  
  2.1-8 @ChapterInfo chapter, section
  
  Adds  the  entry to the given chapter and section. Here, chapter and section
  are the respective titles.
  
  As an example, a full AutoDoc comment with all options could look like this:
  
  
    #! @Description
    #! Computes the list of lists of degrees of ordinary characters
    #! associated to the $p$-blocks of the group $G$
    #! with $p$-modular character table <A>modtbl</A>
    #! and underlying ordinary character table `ordtbl`.
    #! @Returns a list
    #! @Arguments modtbl
    #! @Group CharacterDegreesOfBlocks
    #! @Label chardegblocks
    #! @ChapterInfo Blocks, Attributes
    DeclareAttribute( "CharacterDegreesOfBlocks",
            IsBrauerTable );
  
  
  
  2.2 Other documentation comments
  
  There  are also some commands which can be used in AutoDoc comments that are
  not  associated  to  any  declaration. This is useful for additional text in
  your documentation, examples, mathematical chapters, etc..
  
  
  2.2-1 @Chapter name
  
  Sets  the  active  chapter,  all  subsequent  functions which do not have an
  explicit  chapter declared in their AutoDoc comment via @ChapterInfo will be
  added to this chapter. Also all text comments, i.e. lines that begin with #!
  without a command, and which do not follow after @Description, will be added
  to the chapter as regular text. Additionally, the chapters label will be set
  to Chapter_name. Example:
  
  
    #! @Chapter My chapter
    #!  This is my chapter.
    #!  I document my stuff in it.
  
  
  The  @ChapterLabel label command can be used to set the label of the chapter
  to  Chapter_label instead of Chapter_name. Additionally, the chapter will be
  stored as _Chapter_label.xml. The @ChapterTitle title command can be used to
  set  a  heading  for  the chapter that is different from name. Note that the
  title does not affect the label. If you use all three commands, i.e.,
  
  
    #! @Chapter name
    #! @ChapterLabel label
    #! @ChapterTitle title
  
  
  title  is  used  for the headline, label for cross-referencing, and name for
  setting the same chapter as active chapter again.
  
  
  2.2-2 @Section name
  
  Sets  an  active  section  like @Chapter sets an active chapter. The section
  automatically ends with the next @Section or @Chapter command.
  
  
    #! @Section My first manual section
    #!  In this section I am going to document my first method.
  
  
  The  @SectionLabel label command can be used to set the label of the section
  to    Section_label   instead   of   Chapter_chaptername_Section_name.   The
  @SectionTitle  title  command  can  be used to set a heading for the section
  that is different from name.
  
  
  2.2-3 @Subsection name
  
  Sets  an  active  subsection  like  @Section  sets  an  active  section. The
  subsection  automatically  ends  with  the  next  @Subsection,  @Section  or
  @Chapter  command.  It  also ends with the next documented function. Indeed,
  internally each function manpage is treated like a subsection.
  
  
    #! @Subsection My first manual subsection
    #!  In this subsection I am going to document my first example.
  
  
  The  @SubsectionLabel  label  command  can  be  used to set the label of the
  subsection          to          Subsection_label          instead         of
  Chapter_chaptername_Section_sectionname_Subsection_name.                 The
  @SubsectionTitle  title  command  can  be  used  to  set  a  heading for the
  subsection that is different from name.
  
  
  2.2-4 @BeginGroup [grpname]
  
  Starts  a  group.  All following documented declarations without an explicit
  @Group  command  are grouped together in the same group with the given name.
  If  no  name is given, then a new nameless group is generated. The effect of
  this command is ended when an @EndGroup command is reached.
  
  See section 2.5 for more information about groups.
  
  
  2.2-5 @EndGroup
  
  Ends the current group.
  
  
    #! @BeginGroup MyGroup
    #!
    DeclareAttribute( "GroupedAttribute",
                      IsList );
    
    DeclareOperation( "NonGroupedOperation",
                      [ IsObject ] );
    
    #!
    DeclareOperation( "GroupedOperation",
                      [ IsList, IsRubbish ] );
    #! @EndGroup
  
  
  
  2.2-6 @GroupTitle title
  
  Sets  the  subsection heading for the current group to title. In the absence
  of  any @GroupTitle command, the heading will be the name of the first entry
  in the group. See 2.5 for more information.
  
  
  2.2-7 @Level lvl
  
  Sets  the  current level of the documentation. All items created after this,
  chapters,   sections,  and  items,  are  given  the  level  lvl,  until  the
  @ResetLevel command resets the level to 0 or another level is set.
  
  See section 2.6 for more information about levels.
  
  
  2.2-8 @ResetLevel
  
  Resets the current level to 0.
  
  
  2.2-9 @BeginExample and @EndExample
  
  @BeginExample  marks  the  start of an example to be put into the manual. It
  differs  from  GAPDoc's  <Example>  (see  'GAPDoc: Log'), in that it expects
  actual  code  (not  in  a  comment) interspersed with comments, to allow for
  examples  files  that can be both executed by GAP, and parsed by AutoDoc. To
  achieve  this,  GAP commands are not preceded by a comment, while output has
  to be preceded by an AutoDoc comment. The gap> prompt for the display in the
  manual is added by AutoDoc. @EndExample ends the example block.
  
  To illustrate this command, consider this input:
  
  
    #! @BeginExample
    S5 := SymmetricGroup(5);
    #! Sym( [ 1 .. 5 ] )
    Order(S5);
    #! 120
    #! @EndExample
  
  
  This results in the following output:
  
    Example  
    gap> S5 := SymmetricGroup(5);
    Sym( [ 1 .. 5 ] )
    gap> Order(S5);
    120
  
  
  The AutoDoc command @Example is an alias of @BeginExample.
  
  
  2.2-10 @BeginExampleSession and @EndExampleSession
  
  @BeginExampleSession  marks  the  start  of  an  example  to be put into the
  manual,  while  @EndExampleSession  ends the example block. It is the direct
  analog of GAPDoc's <Example> (see 'GAPDoc: Log').
  
  To illustrate this command, consider this input:
  
  
    #! @BeginExampleSession
    #! gap> S5 := SymmetricGroup(5);
    #! Sym( [ 1 .. 5 ] )
    #! gap> Order(S5);
    #! 120
    #! @EndExampleSession
  
  
  This results in the following output:
  
    Example  
    gap> S5 := SymmetricGroup(5);
    Sym( [ 1 .. 5 ] )
    gap> Order(S5);
    120
  
  
  It  inserts  an  example  into the manual just as @Example would do, but all
  lines  are  commented  and therefore not executed when the file is read. All
  lines  that  should  be  part of the example displayed in the manual have to
  start with an AutoDoc comment (#!). The comment will be removed, and, if the
  following  character  is  a space, this space will also be removed. There is
  never  more than one space removed. To ensure examples are correctly colored
  in  the  manual,  there  should be exactly one space between #! and the gap>
  prompt.    The    AutoDoc   command   @ExampleSession   is   an   alias   of
  @BeginExampleSession.
  
  
  2.2-11 @BeginLog and @EndLog
  
  Works  just  like  the  @BeginExample  command,  but the example will not be
  tested. See the GAPDoc manual for more information. The AutoDoc command @Log
  is an alias of @BeginLog.
  
  
  2.2-12 @BeginLogSession and @EndLogSession
  
  Works  just  like the @BeginExampleSession command, but the example will not
  be  tested  if  manual examples are run. It is the direct analog of GAPDoc's
  <Log>  (see  'GAPDoc:  Log'). The AutoDoc command @LogSession is an alias of
  @BeginLogSession.
  
  
  2.2-13 @DoNotReadRestOfFile
  
  Prevents  the  rest  of  the  file from being read by the parser. Useful for
  unfinished or temporary files.
  
  
    #! This will appear in the manual
    
    #! @DoNotReadRestOfFile
    
    #! This will not appear in the manual.
  
  
  
  2.2-14 @BeginChunk name, @EndChunk, and @InsertChunk name
  
  Text  inside  a  @BeginChunk  / @EndChunk part will not be inserted into the
  final  documentation  directly.  Instead,  the text is stored in an internal
  buffer.  That chunk of text can then later on be inserted in any other place
  by  using the @InsertChunk name command. If you do not provide an @EndChunk,
  the chunk ends at the end of the file.
  
  
    #! @BeginChunk MyChunk
    #! Hello, world.
    #! @EndChunk
    
    #! @InsertChunk MyChunk
    ## The text "Hello, world." is inserted right before this.
  
  
  You can use this to define an example like this in one file:
  
  
    #! @BeginChunk Example_Symmetric_Group
    #! @BeginExample
    S5 := SymmetricGroup(5);
    #! Sym( [ 1 .. 5 ] )
    Order(S5);
    #! 120
    #! @EndExample
    #! @EndChunk
  
  
  And then later, insert the example in a different file, like this:
  
  
    #! @InsertChunk Example_Symmetric_Group
  
  
  
  2.2-15 @BeginCode name, @EndCode, and @InsertCode name
  
  Inserts the text between @BeginCode and @EndCode verbatim at the point where
  @InsertCode  is called. This is useful to insert code excerpts directly into
  the manual.
  
  
    #! @BeginCode Increment
    i := i + 1;
    #! @EndCode
    
    #! @InsertCode Increment
    ## Code is inserted here.
  
  
  
  2.2-16 @LatexOnly text, @BeginLatexOnly, and @EndLatexOnly
  
  Code  inserted between @BeginLatexOnly and @EndLatexOnly or after @LatexOnly
  is  only inserted in the PDF version of the manual or worksheet. It can hold
  arbitrary LaTeX-commands.
  
  
    #! @BeginLatexOnly
    #! \include{picture.tex}
    #! @EndLatexOnly
    
    #! @LatexOnly \include{picture.tex}
  
  
  
  2.2-17 @NotLatex text, @BeginNotLatex, and @EndNotLatex
  
  Code  inserted between @BeginNotLatex and @EndNotLatex or after @NotLatex is
  inserted  in  the HTML and text versions of the manual or worksheet, but not
  in the PDF version.
  
  
    #! @BeginNotLatex
    #! For further information see the PDF version of this manual.
    #! @EndNotLatex
    
    #! @NotLatex For further information see the PDF version of this manual.
  
  
  
  2.3 Title page commands
  
  The  following  commands  can  be used to add the corresponding parts to the
  title  page  of  the  document  which generated by AutoDoc if scaffolding is
  enabled.
  
      @Title
  
      @Subtitle
  
      @Version
  
      @TitleComment
  
      @Author
  
      @Date
  
      @Address
  
      @Abstract
  
      @Copyright
  
      @Acknowledgements
  
      @Colophon
  
  Those  add the following lines at the corresponding point of the title page.
  Please  note  that  many  of those things can be (better) extracted from the
  PackageInfo.g.  In  case you set some of those, the extracted or in scaffold
  defined  items  will  be  overwritten.  While  this  is  not very useful for
  documenting  packages,  they  are  necessary  for  worksheets  created  with
  AutoDocWorksheet  (3.1-1), since worksheets do not have a PackageInfo.g file
  from which this information could be extracted.
  
  
  2.4 Plain text files
  
  Files  that  have  the  suffix  .autodoc and are listed in the autodoc.files
  option  of  AutoDoc  (4.1-1),  resp. are contained in one of the directories
  listed  in autodoc.scan_dirs, are treated as AutoDoc plain text files. These
  work exactly like AutoDoc comments, except that lines do not need to (and in
  fact, should not) start with #!.
  
  
  2.5 Grouping
  
  In  GAPDoc,  it  is  possible  to  make  groups  of manual items, i.e., when
  documenting  a  function, operation, etc., it is possible to group them into
  suitable  chunks.  This  can  be  particularly  useful  if there are several
  definitions of an operation with several different argument types, all doing
  more  or  less  the  same  to  the arguments. Then their manual items can be
  grouped,  sharing  the same description and return type information. You can
  give  a  heading to the group in the manual with the @GroupTitle command; if
  that is not supplied, then the heading of the first manual item in the group
  will be used as the heading.
  
  Note  that group names are globally unique throughout the whole manual. That
  is,  groups  with the same name are in fact merged into a single group, even
  if  they were declared in different source files. Thus you can have multiple
  @BeginGroup  /  @EndGroup  pairs  using  the  same  group name, in different
  places, and these all will refer to the same group.
  
  Moreover,  this  means  that  you  can  add  items to a group via the @Group
  command in the AutoDoc comment of an arbitrary declaration, at any time.
  
  The following code
  
  
    #! @BeginGroup Group1
    #! @GroupTitle A family of operations
    
    #! @Description
    #!  First sentence.
    DeclareOperation( "FirstOperation", [ IsInt ] );
    
    #! @Description
    #!  Second sentence.
    DeclareOperation( "SecondOperation", [ IsInt, IsGroup ] );
    
    #! @EndGroup
    
    ## .. Stuff ..
    
    #! @Description
    #!  Third sentence.
    #! @Group Group1
    KeyDependentOperation( "ThirdOperation", IsGroup, IsInt, "prime );
  
  
  produces the following:
  
  
  2.5-1 A family of operations
  
  FirstOperation( arg )  operation
  SecondOperation( arg1, arg2 )  operation
  ThirdOperation( arg1, arg2 )  operation
  
  First sentence. Second sentence. Third sentence.
  
  
  2.6 Level
  
  Levels can be set to not write certain parts in the manual by default. Every
  entry  has by default the level 0. The command @Level can be used to set the
  level of the following part to a higher level, for example 1, and prevent it
  from  being printed to the manual by default. However, if one sets the level
  to  a  higher  value  in  the  autodoc  option of AutoDoc, the parts will be
  included in the manual at the specific place.
  
  
    #! This text will be printed to the manual.
    #! @Level 1
    #! This text will be printed to the manual if created with level 1 or higher.
    #! @Level 2
    #! This text will be printed to the manual if created with level 2 or higher.
    #! @ResetLevel
    #! This text will be printed to the manual.
  
  
  
  2.7 Markdown-like formatting of text in AutoDoc
  
  AutoDoc  has  some  convenient ways to insert special format into text, like
  math  formulas  and  lists. The syntax for them are inspired by Markdown and
  LaTeX,  but  do  not  follow  them strictly. Neither are all features of the
  Markdown  language  supported.  The  following  subsections describe what is
  possible.
  
  
  2.7-1 Lists
  
  One can create lists of items by beginning a new line with *, +, -, followed
  by one space. The first item starts the list. When items are longer than one
  line,  the  following  lines have to be indented by at least two spaces. The
  list ends when a line which does not start a new item is not indented by two
  spaces. Of course lists can be nested. Here is an example:
  
  
    #! The list starts in the next line
    #! * item 1
    #! * item 2
    #!   which is a bit longer
    #!   * and also contains a nested list
    #!   * with two items
    #! * item 3 of the outer list
    #! This does not belong to the list anymore.
  
  
  This is the output:
  The list starts in the next line
  
      item 1
  
      item 2 which is a bit longer
  
            and also contains a nested list
  
            with two items
  
      item 3 of the outer list
  
  This does not belong to the list anymore.
  The  *,  -,  and + are fully interchangeable and can even be used mixed, but
  this is not recommended.
  
  
  2.7-2 Math modes
  
  One  can start an inline formula with a $, and also end it with $, just like
  in  LaTeX.  This  will  translate  into GAPDocs inline math environment. For
  display mode one can use $$, also like LaTeX.
  
  
    #! This is an inline formula: $1+1 = 2$.
    #! This is a display formula:
    #! $$ \sum_{i=1}^n i. $$
  
  
  produces the following output:
  This is an inline formula: 1+1 = 2. This is a display formula:
  
  
  \sum_{i=1}^n i.
  
  
  
  
  2.7-3 Emphasize
  
  One  can  emphasize text by using two asterisks (**) or two underscores (__)
  at  the  beginning  and  the  end  of  the  text which should be emphasized.
  Example:
  
  
    #! **This** is very important.
    #! This is __also important__.
    #! **Naturally, more than one line
    #! can be important.**
  
  
  This produces the following output:
  This  is  very  important.  This is also important. Naturally, more than one
  line can be important.
  
  
  2.7-4 Inline code
  
  One  can  mark  inline code snippets by using backticks (`) at the beginning
  and the end of the text which should be marked as code. Example:
  
  
    #! Call function `foobar()` at the start.
  
  
  This produces the following output:
  Call function foobar() at the start.
  
  
  2.8 Deprecated commands
  
  The  following  commands  used  to be supported, but should not generally be
  used anymore. They will be removed in a future version of AutoDoc.
  
  @EndSection
        You  can  simply  remove  any  use  of  this,  AutoDoc  ends  sections
        automatically at the start of any new section or chapter.
  
  @EndSubsection
        You  can  simply  remove  any  use  of  this, AutoDoc ends subsections
        automatically at the start of any new subsection, section or chapter.
  
  @BeginAutoDoc and @EndAutoDoc
        It  suffices to prepend each declaration that is meant to be appear in
        the manual with a minimal AutoDoc comment #!.
  
  @BeginSystem name, @EndSystem, and @InsertSystem name
        Please use the chunk commands from subsection 2.2-14 instead.
  
  @AutoDocPlainText and @EndAutoDocPlainText
        Use .autodoc files or AutoDoc comments instead.