  
  [1X3 [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
  declarations.  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;0YFor  declaration  documentation,  the  associated  declaration  must  appear
  immediately  after  the  [5XAutoDoc[105X comment block. In particular, do not insert
  other  code (such as [10Xif false then[110X or assignments) between the comment block
  and the [10XDeclare...[110X statement.[133X
  
  [33X[0;0YThis  also  works  for  [10XInstallMethod[110X  and [10XInstallOtherMethod[110X. In that case,
  [5XAutoDoc[105X  uses the installed method's name and filter list to create a manual
  entry for the implemented item.[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. Any comment line that does [13Xnot[113X start
  with  an  [5XAutoDoc[105X  command  is treated as regular documentation text and may
  contain  (almost)  arbitrary  [5XGAPDoc[105X XML markup, such as [10X<Ref>[110X, [10X<A>[110X, [10X<List>[110X,
  and  similar  tags.  This  lets you use the normal [5XGAPDoc[105X formatting toolbox
  directly inside [5XAutoDoc[105X comments.[133X
  
  [33X[0;0YFor example:[133X
  
  [4X[32X[104X
    [4X#! @Description[104X
    [4X#!  See <Ref Chap="Chapter_Tutorials"/> for setup details.[104X
    [4X#!  The argument <A>obj</A> must satisfy <K>IsObject</K>.[104X
  [4X[32X[104X
  
  [33X[0;0YAs   explained   in  chapter  [14X1[114X,  you  can  combine  [5XAutoDoc[105X  comments  with
  hand-written  XML  and  classic  [5XGAPDoc[105X  comments.  For  practical setup and
  migration workflows, see chapter [14X2[114X.[133X
  
  
  [1X3.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
  
  
  [1X3.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
  
  
  [1X3.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
  
  
  [1X3.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
  
  [33X[0;0YFor  [10XDeclareGlobalName[110X,  using  [10X@Arguments[110X  or  [10X@Returns[110X  also makes [5XAutoDoc[105X
  document  the  item  as a function. This is useful because [10XDeclareGlobalName[110X
  itself does not reveal whether the name denotes a function or a variable.[133X
  
  
  [1X3.1-4 [33X[0;0Y[10X@ItemType [3Xkind[103X[101X[1X[10X[110X[101X[1X[133X[101X
  
  [33X[0;0YOverrides  the  kind of manual item created for the following declaration or
  installed  method.  The  supported  values are [10XAttr[110X, [10XCat[110X, [10XColl[110X, [10XConstr[110X, [10XFam[110X,
  [10XFilt[110X, [10XFunc[110X, [10XInfoClass[110X, [10XMeth[110X, [10XOper[110X, [10XProp[110X, [10XRepr[110X, and [10XVar[110X.[133X
  
  [33X[0;0YThe  values [10XCat[110X, [10XColl[110X, and [10XRepr[110X are [5XAutoDoc[105X-specific aliases. They emit [10XFilt[110X
  entries with the corresponding [5XGAPDoc[105X filter type.[133X
  
  [33X[0;0YThis  is  useful  when the source code alone does not determine which manual
  item  kind should be emitted. For many declarations such as [10XDeclareAttribute[110X
  or  [10XDeclareProperty[110X,  [5XAutoDoc[105X  already  knows  the  intended  type  from the
  declaration itself.[133X
  
  [33X[0;0YIt  is  useful  for [10XDeclareGlobalName[110X, because that declaration can refer to
  either  a  function or a variable. [5XAutoDoc[105X defaults such entries to [10XVar[110X, but
  switches  to [10XFunc[110X as soon as [10X@Arguments[110X or [10X@Returns[110X indicates function-style
  documentation. You can still use [10X@ItemType[110X to override this explicitly.[133X
  
  [33X[0;0YIt  is  useful  for  [10XDeclareSynonym[110X, because that declaration can document a
  function synonym or one of several filter-like synonyms. Use [10X@ItemType Filt[110X,
  [10XCat[110X, [10XColl[110X, or [10XRepr[110X to control which kind of filter entry should be emitted.[133X
  
  [33X[0;0YFor example:[133X
  
  [4X[32X[104X
    [4X#! @ItemType Repr[104X
    [4XDeclareSynonym( "IsSomethingRep", IsComponentObjectRep );[104X
  [4X[32X[104X
  
  [33X[0;0YThis makes [5XAutoDoc[105X emit a [10X<Filt Type="Representation" .../>[110X manual entry.[133X
  
  
  [1X3.1-5 [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 [14X3.5[114X
  for more information about groups.[133X
  
  
  [1X3.1-6 [33X[0;0Y[10X@Label [3Xlabel[103X[101X[1X[10X[110X[101X[1X[133X[101X
  
  [33X[0;0YAdds label to the function as label.[133X
  
  [33X[0;0YIf 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
  
  [4X[32X[104X
    [4X<ManSection>[104X
    [4X  <Prop Arg="arg" Name="AProperty" Label="testlabel"/>[104X
    [4X <Returns> <K>true</K> or <K>false</K>[104X
    [4X</Returns>[104X
    [4X <Description>[104X
    [4X </Description>[104X
    [4X</ManSection>[104X
  [4X[32X[104X
  
  [33X[0;0Ywhile[133X
  
  [4X[32X[104X
    [4X#![104X
    [4XDeclareProperty( "AProperty",[104X
    [4X                 IsObject );[104X
  [4X[32X[104X
  
  [33X[0;0Yleads to this:[133X
  
  [4X[32X[104X
    [4X<ManSection>[104X
    [4X  <Prop Arg="arg" Name="AProperty" Label="for IsObject"/>[104X
    [4X <Returns> <K>true</K> or <K>false</K>[104X
    [4X</Returns>[104X
    [4X <Description>[104X
    [4X </Description>[104X
    [4X</ManSection>[104X
  [4X[32X[104X
  
  
  [1X3.1-7 [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. As 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
  
  
  [1X3.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
  
  
  [1X3.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.[133X
  
  [33X[0;0YExample:[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.[133X
  
  [33X[0;0YAdditionally, the chapter will be stored as [10X_Chapter_[110X[3Xlabel[103X[10X.xml[110X.[133X
  
  [33X[0;0YThe [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.[133X
  
  [33X[0;0YIf 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
  
  
  [1X3.2-2 [33X[0;0Y[10X@Appendix [3Xname[103X[101X[1X[10X[110X[101X[1X[133X[101X
  
  [33X[0;0YThis  is  analogous  to [10X@Chapter[110X, but generates [10XAppendix[110X elements instead of
  [10XChapter[110X  elements.  When scaffolding generates the main XML file, appendices
  created  this  way  are  included  automatically  after  any files listed in
  [10Xscaffold.appendix[110X.[133X
  
  [33X[0;0YExample:[133X
  
  [4X[32X[104X
    [4X@Appendix Supplementary material[104X
    [4X[104X
    [4X@Section Additional tables[104X
  [4X[32X[104X
  
  
  [1X3.2-3 [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.[133X
  
  [33X[0;0YThe [10X@SectionTitle[110X [3Xtitle[103X command can be used to set a heading for the section
  that is different from [3Xname[103X.[133X
  
  
  [1X3.2-4 [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.[133X
  
  [33X[0;0YThe  [10X@SubsectionTitle[110X  [3Xtitle[103X  command  can  be used to set a heading for the
  subsection that is different from [3Xname[103X.[133X
  
  
  [1X3.2-5 [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 [14X3.5[114X for more information about groups.[133X
  
  
  [1X3.2-6 [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
  
  
  [1X3.2-7 [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 [14X3.5[114X for more information.[133X
  
  
  [1X3.2-8 [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. If you enable
  [10Xextract_examples  :=  true[110X  when calling [2XAutoDoc[102X ([14X4.2-1[114X), these examples can
  also be turned into [11X.tst[111X files (see Section [14X2.4-1[114X).[133X
  
  
  [1X3.2-9 [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
  
  
  [1X3.2-10 [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
  
  
  [1X3.2-11 [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
  
  
  [1X3.2-12 [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
  
  
  [1X3.2-13 [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.[133X
  
  [33X[0;0YThat chunk of text can then later on be inserted in any other place by using
  the [10X@InsertChunk [3Xname[103X[10X[110X command.[133X
  
  [33X[0;0YIf 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
  
  
  [1X3.2-14 [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
  
  
  [1X3.2-15 [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
  
  
  [1X3.2-16 [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
  
  
  [1X3.2-17 [33X[0;0Y[10X@Index [3Xkey[103X[101X[1X[10X [[3Xentry text[103X[101X[1X[10X][110X[101X[1X[133X[101X
  
  [33X[0;0YAdds  an  index  entry to the current documentation text. The command [10X@Index
  key  entry  text[110X  generates [10X<Index Key="key">entry text</Index>[110X. If no entry
  text  is  provided,  then  the  entry  text is empty. To use keys containing
  spaces,  wrap the key in double quotes, e.g. [10X@Index "my key" entry text[110X. The
  entry  text  is  processed  like normal documentation text, so markdown-like
  inline code such as [9Xtrue[109X is supported.[133X
  
  
  [1X3.3 [33X[0;0YTitle page commands[133X[101X
  
  [33X[0;0YThe  following  commands can be used to add corresponding parts to the title
  page of a document generated by [5XAutoDoc[105X.[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;0YMany  of  these  values  can  (and  for package manuals typically should) be
  extracted  from  [11XPackageInfo.g[111X. If you set them explicitly in comments, they
  override  extracted  or scaffold-defined values. This is usually most useful
  for  worksheets  created  with [2XAutoDocWorksheet[102X ([14X4.1-1[114X), since worksheets do
  not  have  a  [11XPackageInfo.g[111X  file  from  which  this  information  could  be
  extracted.[133X
  
  
  [1X3.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.2-1[114X),  resp. are contained in one of the directories
  listed  in  [10Xautodoc.scan_dirs[110X or one of their subdirectories, are treated as
  standalone [5XAutoDoc[105X input files. They are meant for manual text that does not
  belong  next  to a single declaration: chapters, sections, tutorials, worked
  examples,   index   entries,   chunks,   title-page  metadata,  and  similar
  prose-heavy material.[133X
  
  [33X[0;0YConceptually,  a [11X.autodoc[111X file uses the same parser as [5XAutoDoc[105X comments, but
  without  the  comment marker. In a [11X.autodoc[111X file, lines do not need to start
  with  [10X#![110X  and  in  fact  usually  should  not. This makes [11X.autodoc[111X files one
  convenient  way  to  replace  hand-written  XML  chapters  when  you  prefer
  [5XAutoDoc[105X's command syntax and Markdown-like text features. However, it is not
  the  only  supported  style:  chapter  and  section  commands  inside source
  comments remain fully supported, and [5XAutoDoc[105X itself still uses that style in
  files such as [11Xgap/Magic.gd[111X. For the surrounding workflow, see Chapter [14X2[114X.[133X
  
  [33X[0;0YThe most important difference from declaration comments is that a plain text
  file  does  [13Xnot[113X  document  a declaration by adjacency. There is no following
  [10XDeclare...[110X  or  [10XInstallMethod[110X  statement for [5XAutoDoc[105X to inspect. So commands
  whose  meaning  depends  on  such  a  declaration  only make sense in source
  comments immediately before that declaration.[133X
  
  [33X[0;0YIn practice, this gives the following rule of thumb.[133X
  
  [30X    [33X[0;6YUse  source  comments beginning with [10X#![110X to document declarations. This
        is  the  mode  for [10X@Description[110X, [10X@Returns[110X, [10X@Arguments[110X, [10X@Label[110X, [10X@Group[110X,
        and [10X@ChapterInfo[110X.[133X
  
  [30X    [33X[0;6YUse  either  [11X.autodoc[111X  files  or source comments for standalone manual
        structure and prose. Commands such as [10X@Chapter[110X, [10X@Section[110X, [10X@Subsection[110X,
        grouping  commands,  examples  and  logs,  chunks  and code insertion,
        [10X@Index[110X,  title-page  commands,  Markdown-style  headings,  fenced code
        blocks, and ordinary [5XGAPDoc[105X XML markup work in both styles.[133X
  
  [33X[0;0YAs  a  concrete  example, the following file can serve as a complete chapter
  written in [11X.autodoc[111X format.[133X
  
  [4X[32X[104X
    [4X@Chapter Test[104X
    [4X@Section First Section[104X
    [4X@Subsection First Subsection[104X
    [4X[104X
    [4XThis text belongs directly to the manual chapter.[104X
    [4XIt can use XML tags such as <A>arg</A> or <Ref .../>.[104X
    [4X[104X
    [4X@BeginExampleSession[104X
    [4Xgap> S5 := SymmetricGroup(5);[104X
    [4XSym( [ 1 .. 5 ] )[104X
    [4Xgap> Size(S5);[104X
    [4X120[104X
    [4X@EndExampleSession[104X
    [4X[104X
    [4X@Index "Worksheet Autoplain" Plain worksheet index entry with `true`[104X
  [4X[32X[104X
  
  [33X[0;0YThis   is   essentially   the   style   used   in   the   worksheet  fixture
  [11Xtst/worksheets/autoplain.sheet/plain.autodoc[111X.[133X
  
  [33X[0;0YThe  same  structural  commands can also be used inside source comments, for
  example:[133X
  
  [4X[32X[104X
    [4X#! @Chapter Reference[104X
    [4X#! @Section The AutoDoc() function[104X
    [4X#! Some introductory text for this section.[104X
  [4X[32X[104X
  
  [33X[0;0YThis   source-comment  style  is  still  fully  supported  and  is  used  in
  [11Xgap/Magic.gd[111X.[133X
  
  [33X[0;0YThe  mixed-workflow case is equally common. Suppose an existing manual still
  has a hand-written main XML file and perhaps some hand-written XML chapters.
  Then  you  can  keep those files, include [11X_AutoDocMainFile.xml[111X from the main
  XML  file  as described in Chapter [14X2[114X, and add one or more [11X.autodoc[111X files via
  [10Xautodoc.files[110X   or  [10Xautodoc.scan_dirs[110X.  Those  files  can  provide  tutorial
  chapters or appendices, while declaration documentation continues to live in
  source comments and older XML chapters remain unchanged.[133X
  
  [33X[0;0YOne  caveat is worth keeping in mind. If you want a standalone [11X.autodoc[111X file
  to  pause  and  resume  around  declaration documentation that is written in
  source  comments, the current workaround is to use chunks. That interleaving
  workflow is currently limited; see issue [10X#60[110X in the AutoDoc issue tracker.[133X
  
  [33X[0;0YSo,  while  [11X.autodoc[111X  files  and source comments share most of the same text
  syntax,  they  can  be  combined freely. The main distinction is simply that
  declaration-bound commands attach metadata to a following declaration, while
  standalone manual text can live wherever you find it most convenient.[133X
  
  
  [1X3.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
  
  [4X[32X[104X
    [4X<ManSection Label="Group1">[104X
    [4X<Heading>A family of operations</Heading>[104X
    [4X  <Oper Arg="arg" Name="FirstOperation" Label="for IsInt"/>[104X
    [4X  <Oper Arg="arg1,arg2" Name="SecondOperation" Label="for IsInt, IsGroup"/>[104X
    [4X  <Oper Arg="arg1,arg2" Name="ThirdOperation" Label="for IsGroup, IsInt"/>[104X
    [4X <Description>[104X
    [4XFirst sentence.[104X
    [4XSecond sentence.[104X
    [4XThird sentence.[104X
    [4X </Description>[104X
    [4X</ManSection>[104X
  [4X[32X[104X
  
  
  [1X3.6 [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
  
  
  [1X3.6-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
  
  
  [1X3.6-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
  
  
  [1X3.6-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
  
  
  [1X3.6-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
  
  
  [1X3.6-5 [33X[0;0YFenced code blocks[133X[101X
  
  [33X[0;0YOne  can  insert  verbatim  code  blocks  by  placing the code between lines
  containing  at  least  three backticks or at least three tildes. The opening
  fence  may  optionally  be  followed by an info string. The values [10X@listing[110X,
  [10X@example[110X,  and [10X@log[110X select the corresponding GAPDoc element; any other value
  is  currently  ignored.  If  nothing is specified the default is to generate
  [10X<Listing>[110X. Example:[133X
  
  [4X[32X[104X
    [4X#! ```@listing[104X
    [4X#! if x = 2 then[104X
    [4X#!   Print("1 + 1 = 2 holds, all is good\n");[104X
    [4X#! fi;[104X
    [4X#! ```[104X
    [4X#! ~~~@example[104X
    [4X#! gap> [ 1 .. 3 ] ^ 2;[104X
    [4X#! [ 1, 4, 9 ][104X
    [4X#! ~~~[104X
    [4X#! ```@log[104X
    [4X#! #I  some log message[104X
    [4X#! ```[104X
  [4X[32X[104X
  
  [33X[0;0YThis produces the following output:[133X
  
  [4X[32X[104X
    [4Xif x = 2 then[104X
    [4X  Print("1 + 1 = 2 holds, all is good\n");[104X
    [4Xfi;[104X
  [4X[32X[104X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27X[ 1 .. 3 ] ^ 2;[127X[104X
    [4X[28X[ 1, 4, 9 ][128X[104X
  [4X[32X[104X
  
  [4X[32X  Example  [32X[104X
    [4X[28X#I  some log message[128X[104X
  [4X[32X[104X
  
  
  [1X3.7 [33X[0;0YDeprecated commands[133X[101X
  
  [33X[0;0YThe following commands used to be supported, but are not supported 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 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 [14X3.2-13[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
  
