  
  [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 [5XAutoDoc[105X 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
  
  
  [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@Description [3Xdescr[103X[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@Returns [3Xret_val[103X[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 retuned by the documented function.[133X
  
  
  [1X2.1-3 [33X[0;0Y@Arguments [3Xargs[103X[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@Group [3Xgrpname[103X[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@Label [3Xlabel[103X[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
  
  [29X[2XAProperty[102X( [3Xarg[103X ) [32X property
  [6XReturns:[106X  [33X[0;10Y[10Xtrue[110X or [10Xfalse[110X[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
  
  [29X[2XAProperty[102X( [3Xarg[103X ) [32X property
  [6XReturns:[106X  [33X[0;10Y[10Xtrue[110X or [10Xfalse[110X[133X
  
  
  [1X2.1-8 [33X[0;0Y@ChapterInfo [3Xchapter, section[103X[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 for 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 <A>p</A>-blocks of the group <A>G</A>[104X
    [4X#! with <A>p</A>-modular character table <A>modtbl</A>[104X
    [4X#! and underlying ordinary character table <A>ordtbl</A>.[104X
    [4X#! @Returns a list[104X
    [4X#! @Arguments modtbl[104X
    [4X#! @Group CharacterDegreesOfBlocks[104X
    [4X#! @FunctionLabel 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@Chapter [3Xname[103X[101X[1X[133X[101X
  
  [33X[0;0YSets  a  chapter,  all functions without seperate info 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. 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
  
  
  [1X2.2-2 [33X[0;0Y@Section [3Xname[103X[101X[1X[133X[101X
  
  [33X[0;0YSets a section like chapter sets a chapter.[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
  
  
  [1X2.2-3 [33X[0;0Y@EndSection[133X[101X
  
  [33X[0;0YCloses the current section. Please be careful here. Closing a section before
  opening it might cause unexpected errors.[133X
  
  [4X[32X[104X
    [4X#! @EndSection[104X
    [4X#### The following text again belongs to the chapter[104X
    [4X#! Now we could start a second section if we want to.[104X
  [4X[32X[104X
  
  
  [1X2.2-4 [33X[0;0Y@Subsection [3Xname[103X[101X[1X[133X[101X
  
  [33X[0;0YSets a subsection like chapter sets a chapter.[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
  
  
  [1X2.2-5 [33X[0;0Y@EndSubsection[133X[101X
  
  [33X[0;0YCloses  the current subsection. Please be careful here. Closing a subsection
  before opening it might cause unexpected errors.[133X
  
  [4X[32X[104X
    [4X#! @EndSubsection[104X
    [4X#### The following text again belongs to the section[104X
    [4X#! Now we are in the section again[104X
  [4X[32X[104X
  
  
  [1X2.2-6 [33X[0;0Y@BeginAutoDoc[133X[101X
  
  [33X[0;0YCauses   all  subsequent  declarations  to  be  documented  in  the  manual,
  regardless of whether they have an [5XAutoDoc[105X comment in front of them or not.[133X
  
  
  [1X2.2-7 [33X[0;0Y@EndAutoDoc[133X[101X
  
  [33X[0;0YEnds  the  affect of [10X@BeginAutoDoc[110X. So from here on, again only declarations
  with an explicit [5XAutoDoc[105X comment in front are added to the manual.[133X
  
  [4X[32X[104X
    [4X#! @BeginAutoDoc[104X
    [4X[104X
    [4XDeclareOperation( "Operation1", [ IsList ] );[104X
    [4X[104X
    [4XDeclareProperty( "IsProperty", IsList );[104X
    [4X[104X
    [4X#! @EndAutoDoc[104X
  [4X[32X[104X
  
  [33X[0;0YBoth, [10XOperation1[110X and [10XIsProperty[110X would appear in the manual.[133X
  
  
  [1X2.2-8 [33X[0;0Y@BeginGroup [3X[grpname][103X[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-9 [33X[0;0Y@EndGroup[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-10 [33X[0;0Y@Level [3Xlvl[103X[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 groups.[133X
  
  
  [1X2.2-11 [33X[0;0Y@ResetLevel[133X[101X
  
  [33X[0;0YResets the current level to 0.[133X
  
  
  [1X2.2-12 [33X[0;0Y@BeginExample and @EndExample[133X[101X
  
  [33X[0;0Y@BeginExample  inserts  an  example  into the manual. The syntax is like the
  example  enviroment  in  GAPDoc.  This examples can be tested by GAPDoc, and
  also  stay  readable by GAP. The GAP prompt is added by AutoDoc. @EndExample
  ends the example block.[133X
  
  [4X[32X[104X
    [4X#! @BeginExample[104X
    [4XS3 := SymmetricGroup(5);[104X
    [4X#! Sym( [ 1 .. 5 ] )[104X
    [4XOrder(S3);[104X
    [4X#! 120[104X
    [4X#! @EndExample[104X
  [4X[32X[104X
  
  
  [1X2.2-13 [33X[0;0Y@BeginLog and @EndLog[133X[101X
  
  [33X[0;0YWorks  just  like the @BeginExample command, but the example wont be testet.
  See the GAPDoc manual for more information.[133X
  
  
  [1X2.2-14 [33X[0;0Y@DoNotReadRestOfFile[133X[101X
  
  [33X[0;0YPrevents  the rest of the file from being read by the parser. Useful for not
  finished or temporary files.[133X
  
  [4X[32X[104X
    [4X#! This will appear in the manual[104X
    [4X[104X
    [4X#! @DoNotReadRestOfFile[104X
    [4X[104X
    [4X#! This wont.[104X
  [4X[32X[104X
  
  
  [1X2.2-15 [33X[0;0Y@BeginChunk [3Xname[103X[101X[1X, @EndChunk, and @InsertChunk [3Xname[103X[101X[1X[133X[101X
  
  [33X[0;0Y@BeginChunk  causes  the  next documentation parts not to be inserted in the
  documentation  at  it's  point  in  the  file,  but  at  the point where the
  @InsertChunk  [3Xname[103X  command  is.  This  can  be used to insert examples from
  different  files  at  a  specific point in the documentation. A normal chunk
  ends at the end of the file. You can also end a system with @EndChunk.[133X
  
  [4X[32X[104X
    [4X#! @BeginChunk MyChunk[104X
    [4X#! This is some text.[104X
    [4X#! @EndChunk[104X
    [4X[104X
    [4X#! @InsertChunk MyChunk[104X
    [4X## Text is inserted here.[104X
  [4X[32X[104X
  
  [4X[32X[104X
    [4X#! @BeginChunk Example_Symmetric_Group[104X
    [4X#! @BeginExample[104X
    [4XS3 := SymmetricGroup(5);[104X
    [4X#! Sym( [ 1 .. 5 ] )[104X
    [4XOrder(S3);[104X
    [4X#! 120[104X
    [4X#! @EndExample[104X
    [4X#! @EndChunk[104X
  [4X[32X[104X
  
  [4X[32X[104X
    [4X#! @InsertChunk Example_Symmetric_Group[104X
  [4X[32X[104X
  
  
  [1X2.2-16 [33X[0;0Y@BeginSystem [3Xname[103X[101X[1X, @EndSystem, and @InsertSystem [3Xname[103X[101X[1X[133X[101X
  
  [33X[0;0YSame  as  @BeginChunk  etc.  This  command  is  deprecated. Please use chunk
  instead.[133X
  
  
  [1X2.2-17 [33X[0;0Y@BeginCode [3Xname[103X[101X[1X, @EndCode, and @InsertCode [3Xname[103X[101X[1X[133X[101X
  
  [33X[0;0YInserts the code between @BeginCode and @EndCode verbatim at the point where
  @InsertCode  is called. This is useful to insert your programm code 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-18 [33X[0;0Y@LatexOnly [3Xtext[103X[101X[1X, @BeginLatexOnly , and @EndLatexOnly[133X[101X
  
  [33X[0;0YCode  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.[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.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, in case the scaffolding is enabled.[133X
  
  [30X    [33X[0;6Y@Title[133X
  
  [30X    [33X[0;6Y@Subtitle[133X
  
  [30X    [33X[0;6Y@Version[133X
  
  [30X    [33X[0;6Y@TitleComment[133X
  
  [30X    [33X[0;6Y@Author[133X
  
  [30X    [33X[0;6Y@Date[133X
  
  [30X    [33X[0;6Y@Address[133X
  
  [30X    [33X[0;6Y@Abstract[133X
  
  [30X    [33X[0;6Y@Copyright[133X
  
  [30X    [33X[0;6Y@Acknowledgements[133X
  
  [30X    [33X[0;6Y@Colophon[133X
  
  [30X    [33X[0;6Y@URL[133X
  
  [33X[0;0YThose  add  the following lines at the corresponding point of the titlepage.
  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.[133X
  
  
  [1X2.4 [33X[0;0YPlain text files[133X[101X
  
  [33X[0;0YAutoDoc plain text files work exactly like AutoDoc comments, except that the
  #!  is  unnecessary  at  the beginning of a line which should be documented.
  Files  that  have  the  suffix .autodoc will automatically regarded as plain
  text  files  while  the  commands @AutoDocPlainText and @EndAutoDocPlainText
  mark  parts  in  plain text files which should be regarded as AutoDoc parts.
  All commands can be used like before.[133X
  
  
  [1X2.5 [33X[0;0YGrouping[133X[101X
  
  [33X[0;0YTODO:  explain  more  about  groups  and  what they do, how they look in the
  generated output etc.[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. The
  following code[133X
  
  [4X[32X[104X
    [4X#! @BeginGroup Group1[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 FirstOperation[101X
  
  [29X[2XFirstOperation[102X( [3Xarg[103X ) [32X operation
  [29X[2XSecondOperation[102X( [3Xarg1[103X, [3Xarg2[103X ) [32X operation
  [29X[2XThirdOperation[102X( [3Xarg1[103X, [3Xarg2[103X ) [32X operation
  
  [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 [10XAutoDoc[110X, 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;0YSome syntax for [5XAutoDoc[105X[101X[1X text[133X[101X
  
  [33X[0;0Y[5XAutoDoc[105X  offers  some  useful syntax extensions which can be used in [5XAutoDoc[105X
  plain  text  files  and  [5XAutoDoc[105X  comments.  The  syntax  is inspired by the
  Markdown language, but it does not implement all features, neither is strict
  Markdown,   but   tries  to  be  as  straight  as  possible.  The  following
  constructions are possible right now:[133X
  
  
  [1X2.7-1 [33X[0;0YLists[133X[101X
  
  [33X[0;0YOne can create items lists 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 curse 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 enviroment. 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
  
  
        [33X[1;6Y[24X[33X[0;0Y\sum_{i=1}^n i.[133X [124X[133X
  
  
  
  [1X2.7-3 [33X[0;0YEmphasize[133X[101X
  
  [33X[0;0YOne can emphasize text by using two asteriks (**) 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
  
