  
  [1X2 [33X[0;0Y[5XAutoDoc[105X[101X[1X documentation comments[133X[101X
  
  [33X[0;0YYou can document declarations of global functions and variables, operations,
  attributes etc. by inserting [13X[5XAutoDoc[105X[113X comments into your sources before these
  declaration.  An  [5XAutoDoc[105X  comment  always  starts with [10X#![110X. This is also the
  smallest  possible [5XAutoDoc[105X command. If you want your declaration documented,
  just write [10X#![110X at the line before the documentation. For example:[133X
  
  [4X[32X[104X
    [4X#![104X
    [4XDeclareOperation( "AnOperation",[104X
    [4X                  [ IsList ] );[104X
  [4X[32X[104X
  
  [33X[0;0YThis will produce a manual entry for the operation [10XAnOperation[110X.[133X
  
  [33X[0;0YInside  of [5XAutoDoc[105X comments, [13X[5XAutoDoc[105X commands[113X starting with [10X@[110X can be used to
  control the output [5XAutoDoc[105X produces.[133X
  
  
  [1X2.1 [33X[0;0YDocumenting declarations[133X[101X
  
  [33X[0;0YIn  the  bare  form above, the manual entry for [10XAnOperation[110X 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  [5XAutoDoc[105X  comment  before  the
  declaration. Currently, the following commands are provided:[133X
  
  
  [1X2.1-1 [33X[0;0Y[10X@Description [3Xdescr[103X[101X[1X[10X[110X[101X[1X[133X[101X
  
  [33X[0;0YAdds  the  text  in the following lines of the [5XAutoDoc[105X to the description of
  the  declaration  in the manual. Lines are until the next [5XAutoDoc[105X command or
  until the declaration is reached.[133X
  
  
  [1X2.1-2 [33X[0;0Y[10X@Returns [3Xret_val[103X[101X[1X[10X[110X[101X[1X[133X[101X
  
  [33X[0;0YThe  string  [3Xret_val[103X  is added to the documentation, with the text [21XReturns: [121X
  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.[133X
  
  
  [1X2.1-3 [33X[0;0Y[10X@Arguments [3Xargs[103X[101X[1X[10X[110X[101X[1X[133X[101X
  
  [33X[0;0YThe  string  [3Xargs[103X  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  [21Xgrp[, elm][121X or [21Xxx[y[z] ][121X. If [5XGAP[105X options are
  used,  this  can  be followed by a colon : and one or more assignments, like
  [21Xn[, r]: tries := 100[121X.[133X
  
  
  [1X2.1-4 [33X[0;0Y[10X@Group [3Xgrpname[103X[101X[1X[10X[110X[101X[1X[133X[101X
  
  [33X[0;0YAdds  the  following  method to a group with the given name. See section [14X2.5[114X
  for more information about groups.[133X
  
  
  [1X2.1-5 [33X[0;0Y[10X@Label [3Xlabel[103X[101X[1X[10X[110X[101X[1X[133X[101X
  
  [33X[0;0YAdds  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
  [10XDeclareOperation[110X, [10XDeclareAttribute[110X, etc.), a default label is generated from
  this filter list.[133X
  
  [4X[32X[104X
    [4X#! @Label testlabel[104X
    [4XDeclareProperty( "AProperty",[104X
    [4X                 IsObject );[104X
  [4X[32X[104X
  
  [33X[0;0Yleads to this:[133X
  
  [1X2.1-6 AProperty[101X
  
  [33X[1;0Y[29X[2XAProperty[102X( [3Xarg[103X ) [32X property[133X
  [6XReturns:[106X  [33X[0;10Y[9Xtrue[109X or [9Xfalse[109X[133X
  
  [33X[0;0Ywhile[133X
  
  [4X[32X[104X
    [4X#![104X
    [4XDeclareProperty( "AProperty",[104X
    [4X                 IsObject );[104X
  [4X[32X[104X
  
  [33X[0;0Yleads to this:[133X
  
  [1X2.1-7 AProperty[101X
  
  [33X[1;0Y[29X[2XAProperty[102X( [3Xarg[103X ) [32X property[133X
  [6XReturns:[106X  [33X[0;10Y[9Xtrue[109X or [9Xfalse[109X[133X
  
  
  [1X2.1-8 [33X[0;0Y[10X@ChapterInfo [3Xchapter[103X[101X[1X[10X, [3Xsection[103X[101X[1X[10X[110X[101X[1X[133X[101X
  
  [33X[0;0YAdds  the  entry to the given chapter and section. Here, [3Xchapter[103X and [3Xsection[103X
  are the respective titles.[133X
  
  [33X[0;0YAs an example, a full [5XAutoDoc[105X comment with all options could look like this:[133X
  
  [4X[32X[104X
    [4X#! @Description[104X
    [4X#! Computes the list of lists of degrees of ordinary characters[104X
    [4X#! associated to the $p$-blocks of the group $G$[104X
    [4X#! with $p$-modular character table <A>modtbl</A>[104X
    [4X#! and underlying ordinary character table `ordtbl`.[104X
    [4X#! @Returns a list[104X
    [4X#! @Arguments modtbl[104X
    [4X#! @Group CharacterDegreesOfBlocks[104X
    [4X#! @Label chardegblocks[104X
    [4X#! @ChapterInfo Blocks, Attributes[104X
    [4XDeclareAttribute( "CharacterDegreesOfBlocks",[104X
    [4X        IsBrauerTable );[104X
  [4X[32X[104X
  
  
  [1X2.2 [33X[0;0YOther documentation comments[133X[101X
  
  [33X[0;0YThere  are also some commands which can be used in [5XAutoDoc[105X comments that are
  not  associated  to  any  declaration. This is useful for additional text in
  your documentation, examples, mathematical chapters, etc..[133X
  
  
  [1X2.2-1 [33X[0;0Y[10X@Chapter [3Xname[103X[101X[1X[10X[110X[101X[1X[133X[101X
  
  [33X[0;0YSets  the  active  chapter,  all  subsequent  functions which do not have an
  explicit  chapter declared in their [5XAutoDoc[105X comment via [10X@ChapterInfo[110X 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 [10X@Description[110X, will be added
  to the chapter as regular text. Additionally, the chapters label will be set
  to [10XChapter_[110X[3Xname[103X. Example:[133X
  
  [4X[32X[104X
    [4X#! @Chapter My chapter[104X
    [4X#!  This is my chapter.[104X
    [4X#!  I document my stuff in it.[104X
  [4X[32X[104X
  
  [33X[0;0YThe  [10X@ChapterLabel[110X [3Xlabel[103X command can be used to set the label of the chapter
  to  [10XChapter_[110X[3Xlabel[103X instead of [10XChapter_[110X[3Xname[103X. Additionally, the chapter will be
  stored as [10X_Chapter_[110X[3Xlabel[103X[10X.xml[110X. The [10X@ChapterTitle[110X [3Xtitle[103X command can be used to
  set  a  heading  for  the chapter that is different from [3Xname[103X. Note that the
  title does not affect the label. If you use all three commands, i.e.,[133X
  
  [4X[32X[104X
    [4X#! @Chapter name[104X
    [4X#! @ChapterLabel label[104X
    [4X#! @ChapterTitle title[104X
  [4X[32X[104X
  
  [33X[0;0Y[10Xtitle[110X  is  used  for the headline, [10Xlabel[110X for cross-referencing, and [10Xname[110X for
  setting the same chapter as active chapter again.[133X
  
  
  [1X2.2-2 [33X[0;0Y[10X@Section [3Xname[103X[101X[1X[10X[110X[101X[1X[133X[101X
  
  [33X[0;0YSets  an  active  section  like [10X@Chapter[110X sets an active chapter. The section
  automatically ends with the next [10X@Section[110X or [10X@Chapter[110X command.[133X
  
  [4X[32X[104X
    [4X#! @Section My first manual section[104X
    [4X#!  In this section I am going to document my first method.[104X
  [4X[32X[104X
  
  [33X[0;0YThe  [10X@SectionLabel[110X [3Xlabel[103X command can be used to set the label of the section
  to    [10XSection_[110X[3Xlabel[103X   instead   of   [10XChapter_chaptername_Section_[110X[3Xname[103X.   The
  [10X@SectionTitle[110X  [3Xtitle[103X  command  can  be used to set a heading for the section
  that is different from [3Xname[103X.[133X
  
  
  [1X2.2-3 [33X[0;0Y[10X@Subsection [3Xname[103X[101X[1X[10X[110X[101X[1X[133X[101X
  
  [33X[0;0YSets  an  active  subsection  like  [10X@Section[110X  sets  an  active  section. The
  subsection  automatically  ends  with  the  next  [10X@Subsection[110X,  [10X@Section[110X  or
  [10X@Chapter[110X  command.  It  also ends with the next documented function. Indeed,
  internally each function [21Xmanpage[121X is treated like a subsection.[133X
  
  [4X[32X[104X
    [4X#! @Subsection My first manual subsection[104X
    [4X#!  In this subsection I am going to document my first example.[104X
  [4X[32X[104X
  
  [33X[0;0YThe  [10X@SubsectionLabel[110X  [3Xlabel[103X  command  can  be  used to set the label of the
  subsection          to          [10XSubsection_[110X[3Xlabel[103X          instead         of
  [10XChapter_chaptername_Section_sectionname_Subsection_[110X[3Xname[103X.                 The
  [10X@SubsectionTitle[110X  [3Xtitle[103X  command  can  be  used  to  set  a  heading for the
  subsection that is different from [3Xname[103X.[133X
  
  
  [1X2.2-4 [33X[0;0Y[10X@BeginGroup [3X[grpname][103X[101X[1X[10X[110X[101X[1X[133X[101X
  
  [33X[0;0YStarts  a  group.  All following documented declarations without an explicit
  [10X@Group[110X  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 [10X@EndGroup[110X command is reached.[133X
  
  [33X[0;0YSee section [14X2.5[114X for more information about groups.[133X
  
  
  [1X2.2-5 [33X[0;0Y[10X@EndGroup[110X[101X[1X[133X[101X
  
  [33X[0;0YEnds the current group.[133X
  
  [4X[32X[104X
    [4X#! @BeginGroup MyGroup[104X
    [4X#![104X
    [4XDeclareAttribute( "GroupedAttribute",[104X
    [4X                  IsList );[104X
    [4X[104X
    [4XDeclareOperation( "NonGroupedOperation",[104X
    [4X                  [ IsObject ] );[104X
    [4X[104X
    [4X#![104X
    [4XDeclareOperation( "GroupedOperation",[104X
    [4X                  [ IsList, IsRubbish ] );[104X
    [4X#! @EndGroup[104X
  [4X[32X[104X
  
  
  [1X2.2-6 [33X[0;0Y@GroupTitle [3Xtitle[103X[101X[1X[133X[101X
  
  [33X[0;0YSets  the  subsection heading for the current group to [3Xtitle[103X. In the absence
  of  any [10X@GroupTitle[110X command, the heading will be the name of the first entry
  in the group. See [14X2.5[114X for more information.[133X
  
  
  [1X2.2-7 [33X[0;0Y[10X@Level [3Xlvl[103X[101X[1X[10X[110X[101X[1X[133X[101X
  
  [33X[0;0YSets  the  current level of the documentation. All items created after this,
  chapters,   sections,  and  items,  are  given  the  level  [3Xlvl[103X,  until  the
  [10X@ResetLevel[110X command resets the level to 0 or another level is set.[133X
  
  [33X[0;0YSee section [14X2.6[114X for more information about levels.[133X
  
  
  [1X2.2-8 [33X[0;0Y[10X@ResetLevel[110X[101X[1X[133X[101X
  
  [33X[0;0YResets the current level to 0.[133X
  
  
  [1X2.2-9 [33X[0;0Y[10X@BeginExample[110X[101X[1X and [10X@EndExample[110X[101X[1X[133X[101X
  
  [33X[0;0Y[10X@BeginExample[110X  marks  the  start of an example to be put into the manual. It
  differs  from  [5XGAPDoc[105X's  [10X<Example>[110X  (see  [14X'GAPDoc: Log'[114X), in that it expects
  actual  code  (not  in  a  comment) interspersed with comments, to allow for
  examples  files  that can be both executed by [5XGAP[105X, and parsed by [5XAutoDoc[105X. To
  achieve  this,  [5XGAP[105X commands are not preceded by a comment, while output has
  to be preceded by an [5XAutoDoc[105X comment. The [10Xgap>[110X prompt for the display in the
  manual is added by [5XAutoDoc[105X. [10X@EndExample[110X ends the example block.[133X
  
  [33X[0;0YTo illustrate this command, consider this input:[133X
  
  [4X[32X[104X
    [4X#! @BeginExample[104X
    [4XS5 := SymmetricGroup(5);[104X
    [4X#! Sym( [ 1 .. 5 ] )[104X
    [4XOrder(S5);[104X
    [4X#! 120[104X
    [4X#! @EndExample[104X
  [4X[32X[104X
  
  [33X[0;0YThis results in the following output:[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XS5 := SymmetricGroup(5);[127X[104X
    [4X[28XSym( [ 1 .. 5 ] )[128X[104X
    [4X[25Xgap>[125X [27XOrder(S5);[127X[104X
    [4X[28X120[128X[104X
  [4X[32X[104X
  
  [33X[0;0YThe [5XAutoDoc[105X command [10X@Example[110X is an alias of [10X@BeginExample[110X.[133X
  
  
  [1X2.2-10 [33X[0;0Y[10X@BeginExampleSession[110X[101X[1X and [10X@EndExampleSession[110X[101X[1X[133X[101X
  
  [33X[0;0Y[10X@BeginExampleSession[110X  marks  the  start  of  an  example  to be put into the
  manual,  while  [10X@EndExampleSession[110X  ends the example block. It is the direct
  analog of [5XGAPDoc[105X's [10X<Example>[110X (see [14X'GAPDoc: Log'[114X).[133X
  
  [33X[0;0YTo illustrate this command, consider this input:[133X
  
  [4X[32X[104X
    [4X#! @BeginExampleSession[104X
    [4X#! gap> S5 := SymmetricGroup(5);[104X
    [4X#! Sym( [ 1 .. 5 ] )[104X
    [4X#! gap> Order(S5);[104X
    [4X#! 120[104X
    [4X#! @EndExampleSession[104X
  [4X[32X[104X
  
  [33X[0;0YThis results in the following output:[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XS5 := SymmetricGroup(5);[127X[104X
    [4X[28XSym( [ 1 .. 5 ] )[128X[104X
    [4X[25Xgap>[125X [27XOrder(S5);[127X[104X
    [4X[28X120[128X[104X
  [4X[32X[104X
  
  [33X[0;0YIt  inserts  an  example  into the manual just as [10X@Example[110X 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 [5XAutoDoc[105X comment ([10X#![110X). 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 [10X#![110X and the [10Xgap>[110X
  prompt.    The    [5XAutoDoc[105X   command   [10X@ExampleSession[110X   is   an   alias   of
  [10X@BeginExampleSession[110X.[133X
  
  
  [1X2.2-11 [33X[0;0Y[10X@BeginLog[110X[101X[1X and [10X@EndLog[110X[101X[1X[133X[101X
  
  [33X[0;0YWorks  just  like  the  [10X@BeginExample[110X  command,  but the example will not be
  tested. See the [5XGAPDoc[105X manual for more information. The [5XAutoDoc[105X command [10X@Log[110X
  is an alias of [10X@BeginLog[110X.[133X
  
  
  [1X2.2-12 [33X[0;0Y[10X@BeginLogSession[110X[101X[1X and [10X@EndLogSession[110X[101X[1X[133X[101X
  
  [33X[0;0YWorks  just  like the [10X@BeginExampleSession[110X command, but the example will not
  be  tested  if  manual examples are run. It is the direct analog of [5XGAPDoc[105X's
  [10X<Log>[110X  (see  [14X'GAPDoc:  Log'[114X). The [5XAutoDoc[105X command [10X@LogSession[110X is an alias of
  [10X@BeginLogSession[110X.[133X
  
  
  [1X2.2-13 [33X[0;0Y[10X@DoNotReadRestOfFile[110X[101X[1X[133X[101X
  
  [33X[0;0YPrevents  the  rest  of  the  file from being read by the parser. Useful for
  unfinished or temporary files.[133X
  
  [4X[32X[104X
    [4X#! This will appear in the manual[104X
    [4X[104X
    [4X#! @DoNotReadRestOfFile[104X
    [4X[104X
    [4X#! This will not appear in the manual.[104X
  [4X[32X[104X
  
  
  [1X2.2-14 [33X[0;0Y[10X@BeginChunk [3Xname[103X[101X[1X[10X[110X[101X[1X, [10X@EndChunk[110X[101X[1X, and [10X@InsertChunk [3Xname[103X[101X[1X[10X[110X[101X[1X[133X[101X
  
  [33X[0;0YText  inside  a  [10X@BeginChunk[110X  / [10X@EndChunk[110X 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 [10X@InsertChunk [3Xname[103X[10X[110X command. If you do not provide an [10X@EndChunk[110X,
  the chunk ends at the end of the file.[133X
  
  [4X[32X[104X
    [4X#! @BeginChunk MyChunk[104X
    [4X#! Hello, world.[104X
    [4X#! @EndChunk[104X
    [4X[104X
    [4X#! @InsertChunk MyChunk[104X
    [4X## The text "Hello, world." is inserted right before this.[104X
  [4X[32X[104X
  
  [33X[0;0YYou can use this to define an example like this in one file:[133X
  
  [4X[32X[104X
    [4X#! @BeginChunk Example_Symmetric_Group[104X
    [4X#! @BeginExample[104X
    [4XS5 := SymmetricGroup(5);[104X
    [4X#! Sym( [ 1 .. 5 ] )[104X
    [4XOrder(S5);[104X
    [4X#! 120[104X
    [4X#! @EndExample[104X
    [4X#! @EndChunk[104X
  [4X[32X[104X
  
  [33X[0;0YAnd then later, insert the example in a different file, like this:[133X
  
  [4X[32X[104X
    [4X#! @InsertChunk Example_Symmetric_Group[104X
  [4X[32X[104X
  
  
  [1X2.2-15 [33X[0;0Y[10X@BeginCode [3Xname[103X[101X[1X[10X[110X[101X[1X, @EndCode, and [10X@InsertCode [3Xname[103X[101X[1X[10X[110X[101X[1X[133X[101X
  
  [33X[0;0YInserts the text between [10X@BeginCode[110X and [10X@EndCode[110X verbatim at the point where
  [10X@InsertCode[110X  is called. This is useful to insert code excerpts directly into
  the manual.[133X
  
  [4X[32X[104X
    [4X#! @BeginCode Increment[104X
    [4Xi := i + 1;[104X
    [4X#! @EndCode[104X
    [4X[104X
    [4X#! @InsertCode Increment[104X
    [4X## Code is inserted here.[104X
  [4X[32X[104X
  
  
  [1X2.2-16 [33X[0;0Y[10X@LatexOnly [3Xtext[103X[101X[1X[10X[110X[101X[1X, [10X@BeginLatexOnly[110X[101X[1X, and [10X@EndLatexOnly[110X[101X[1X[133X[101X
  
  [33X[0;0YCode  inserted between [10X@BeginLatexOnly[110X and [10X@EndLatexOnly[110X or after [10X@LatexOnly[110X
  is  only inserted in the PDF version of the manual or worksheet. It can hold
  arbitrary LaTeX-commands.[133X
  
  [4X[32X[104X
    [4X#! @BeginLatexOnly[104X
    [4X#! \include{picture.tex}[104X
    [4X#! @EndLatexOnly[104X
    [4X[104X
    [4X#! @LatexOnly \include{picture.tex}[104X
  [4X[32X[104X
  
  
  [1X2.2-17 [33X[0;0Y[10X@NotLatex [3Xtext[103X[101X[1X[10X[110X[101X[1X, [10X@BeginNotLatex[110X[101X[1X, and [10X@EndNotLatex[110X[101X[1X[133X[101X
  
  [33X[0;0YCode  inserted between [10X@BeginNotLatex[110X and [10X@EndNotLatex[110X or after [10X@NotLatex[110X is
  inserted  in  the HTML and text versions of the manual or worksheet, but not
  in the PDF version.[133X
  
  [4X[32X[104X
    [4X#! @BeginNotLatex[104X
    [4X#! For further information see the PDF version of this manual.[104X
    [4X#! @EndNotLatex[104X
    [4X[104X
    [4X#! @NotLatex For further information see the PDF version of this manual.[104X
  [4X[32X[104X
  
  
  [1X2.3 [33X[0;0YTitle page commands[133X[101X
  
  [33X[0;0YThe  following  commands  can  be used to add the corresponding parts to the
  title  page  of  the  document  which generated by [5XAutoDoc[105X if scaffolding is
  enabled.[133X
  
  [30X    [33X[0;6Y[10X@Title[110X[133X
  
  [30X    [33X[0;6Y[10X@Subtitle[110X[133X
  
  [30X    [33X[0;6Y[10X@Version[110X[133X
  
  [30X    [33X[0;6Y[10X@TitleComment[110X[133X
  
  [30X    [33X[0;6Y[10X@Author[110X[133X
  
  [30X    [33X[0;6Y[10X@Date[110X[133X
  
  [30X    [33X[0;6Y[10X@Address[110X[133X
  
  [30X    [33X[0;6Y[10X@Abstract[110X[133X
  
  [30X    [33X[0;6Y[10X@Copyright[110X[133X
  
  [30X    [33X[0;6Y[10X@Acknowledgements[110X[133X
  
  [30X    [33X[0;6Y[10X@Colophon[110X[133X
  
  [33X[0;0YThose  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
  [11XPackageInfo.g[111X.  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
  [2XAutoDocWorksheet[102X  ([14X3.1-1[114X), since worksheets do not have a [11XPackageInfo.g[111X file
  from which this information could be extracted.[133X
  
  
  [1X2.4 [33X[0;0YPlain text files[133X[101X
  
  [33X[0;0YFiles  that  have  the  suffix  [10X.autodoc[110X and are listed in the [10Xautodoc.files[110X
  option  of  [2XAutoDoc[102X  ([14X4.1-1[114X),  resp. are contained in one of the directories
  listed  in [10Xautodoc.scan_dirs[110X, are treated as [5XAutoDoc[105X plain text files. These
  work exactly like [5XAutoDoc[105X comments, except that lines do not need to (and in
  fact, should not) start with [10X#![110X.[133X
  
  
  [1X2.5 [33X[0;0YGrouping[133X[101X
  
  [33X[0;0YIn  [5XGAPDoc[105X,  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 [10X@GroupTitle[110X command; if
  that is not supplied, then the heading of the first manual item in the group
  will be used as the heading.[133X
  
  [33X[0;0YNote  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
  [10X@BeginGroup[110X  /  [10X@EndGroup[110X  pairs  using  the  same  group name, in different
  places, and these all will refer to the same group.[133X
  
  [33X[0;0YMoreover,  this  means  that  you  can  add  items to a group via the [10X@Group[110X
  command in the [5XAutoDoc[105X comment of an arbitrary declaration, at any time.[133X
  
  [33X[0;0YThe following code[133X
  
  [4X[32X[104X
    [4X#! @BeginGroup Group1[104X
    [4X#! @GroupTitle A family of operations[104X
    [4X[104X
    [4X#! @Description[104X
    [4X#!  First sentence.[104X
    [4XDeclareOperation( "FirstOperation", [ IsInt ] );[104X
    [4X[104X
    [4X#! @Description[104X
    [4X#!  Second sentence.[104X
    [4XDeclareOperation( "SecondOperation", [ IsInt, IsGroup ] );[104X
    [4X[104X
    [4X#! @EndGroup[104X
    [4X[104X
    [4X## .. Stuff ..[104X
    [4X[104X
    [4X#! @Description[104X
    [4X#!  Third sentence.[104X
    [4X#! @Group Group1[104X
    [4XKeyDependentOperation( "ThirdOperation", IsGroup, IsInt, "prime );[104X
  [4X[32X[104X
  
  [33X[0;0Yproduces the following:[133X
  
  
  [1X2.5-1 [33X[0;0YA family of operations[133X[101X
  
  [33X[1;0Y[29X[2XFirstOperation[102X( [3Xarg[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XSecondOperation[102X( [3Xarg1[103X, [3Xarg2[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XThirdOperation[102X( [3Xarg1[103X, [3Xarg2[103X ) [32X operation[133X
  
  [33X[0;0YFirst sentence. Second sentence. Third sentence.[133X
  
  
  [1X2.6 [33X[0;0YLevel[133X[101X
  
  [33X[0;0YLevels can be set to not write certain parts in the manual by default. Every
  entry  has by default the level 0. The command [10X@Level[110X 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 [5XAutoDoc[105X, the parts will be
  included in the manual at the specific place.[133X
  
  [4X[32X[104X
    [4X#! This text will be printed to the manual.[104X
    [4X#! @Level 1[104X
    [4X#! This text will be printed to the manual if created with level 1 or higher.[104X
    [4X#! @Level 2[104X
    [4X#! This text will be printed to the manual if created with level 2 or higher.[104X
    [4X#! @ResetLevel[104X
    [4X#! This text will be printed to the manual.[104X
  [4X[32X[104X
  
  
  [1X2.7 [33X[0;0YMarkdown-like formatting of text in [5XAutoDoc[105X[101X[1X[133X[101X
  
  [33X[0;0Y[5XAutoDoc[105X  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.[133X
  
  
  [1X2.7-1 [33X[0;0YLists[133X[101X
  
  [33X[0;0YOne 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:[133X
  
  [4X[32X[104X
    [4X#! The list starts in the next line[104X
    [4X#! * item 1[104X
    [4X#! * item 2[104X
    [4X#!   which is a bit longer[104X
    [4X#!   * and also contains a nested list[104X
    [4X#!   * with two items[104X
    [4X#! * item 3 of the outer list[104X
    [4X#! This does not belong to the list anymore.[104X
  [4X[32X[104X
  
  [33X[0;0YThis is the output:[133X
  [33X[0;0YThe list starts in the next line[133X
  
  [30X    [33X[0;6Yitem 1[133X
  
  [30X    [33X[0;6Yitem 2 which is a bit longer[133X
  
        [30X    [33X[0;12Yand also contains a nested list[133X
  
        [30X    [33X[0;12Ywith two items[133X
  
  [30X    [33X[0;6Yitem 3 of the outer list[133X
  
  [33X[0;0YThis does not belong to the list anymore.[133X
  [33X[0;0YThe  *,  -,  and + are fully interchangeable and can even be used mixed, but
  this is not recommended.[133X
  
  
  [1X2.7-2 [33X[0;0YMath modes[133X[101X
  
  [33X[0;0YOne  can start an inline formula with a $, and also end it with $, just like
  in  LaTeX.  This  will  translate  into [5XGAPDoc[105Xs inline math environment. For
  display mode one can use $$, also like LaTeX.[133X
  
  [4X[32X[104X
    [4X#! This is an inline formula: $1+1 = 2$.[104X
    [4X#! This is a display formula:[104X
    [4X#! $$ \sum_{i=1}^n i. $$[104X
  [4X[32X[104X
  
  [33X[0;0Yproduces the following output:[133X
  [33X[0;0YThis is an inline formula: [23X1+1 = 2[123X. This is a display formula:[133X
  
  
  [24X[33X[0;6Y\sum_{i=1}^n i.[133X
  
  [124X
  
  
  [1X2.7-3 [33X[0;0YEmphasize[133X[101X
  
  [33X[0;0YOne  can  emphasize text by using two asterisks (**) or two underscores (__)
  at  the  beginning  and  the  end  of  the  text which should be emphasized.
  Example:[133X
  
  [4X[32X[104X
    [4X#! **This** is very important.[104X
    [4X#! This is __also important__.[104X
    [4X#! **Naturally, more than one line[104X
    [4X#! can be important.**[104X
  [4X[32X[104X
  
  [33X[0;0YThis produces the following output:[133X
  [33X[0;0Y[13XThis[113X  is  very  important.  This is [13Xalso important[113X. [13XNaturally, more than one
  line can be important.[113X[133X
  
  
  [1X2.7-4 [33X[0;0YInline code[133X[101X
  
  [33X[0;0YOne  can  mark  inline code snippets by using backticks (`) at the beginning
  and the end of the text which should be marked as code. Example:[133X
  
  [4X[32X[104X
    [4X#! Call function `foobar()` at the start.[104X
  [4X[32X[104X
  
  [33X[0;0YThis produces the following output:[133X
  [33X[0;0YCall function [10Xfoobar()[110X at the start.[133X
  
  
  [1X2.8 [33X[0;0YDeprecated commands[133X[101X
  
  [33X[0;0YThe following commands used to be supported, but are not anymore.[133X
  
  [8X[10X@EndSection[110X[8X[108X
        [33X[0;6YYou  can  simply  remove  any  use  of  this,  [5XAutoDoc[105X  ends  sections
        automatically at the start of any new section or chapter.[133X
  
  [8X[10X@EndSubsection[110X[8X[108X
        [33X[0;6YYou  can  simply  remove  any  use  of  this, [5XAutoDoc[105X ends subsections
        automatically at the start of any new subsection, section or chapter.[133X
  
  [8X[10X@BeginAutoDoc[110X[8X and [10X@EndAutoDoc[110X[8X[108X
        [33X[0;6YIt  suffices to prepend each declaration that is meant to be appear in
        the manual with a minimal [5XAutoDoc[105X comment [10X#![110X.[133X
  
  [8X[10X@BeginSystem [3Xname[103X[8X[10X[110X[8X, [10X@EndSystem[110X[8X, and [10X@InsertSystem [3Xname[103X[8X[10X[110X[8X[108X
        [33X[0;6YPlease use the chunk commands from subsection [14X2.2-14[114X instead.[133X
  
  [8X[10X@AutoDocPlainText[110X[8X and [10X@EndAutoDocPlainText[110X[8X[108X
        [33X[0;6YUse [10X.autodoc[110X files or [5XAutoDoc[105X comments instead.[133X
  
