chap2.txt

  
  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 retuned 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 for with all options could look like
  this:
  
  
    #! @Description
    #! Computes the list of lists of degrees of ordinary characters
    #! associated to the <A>p</A>-blocks of the group <A>G</A>
    #! with <A>p</A>-modular character table <A>modtbl</A>
    #! and underlying ordinary character table <A>ordtbl</A>.
    #! @Returns a list
    #! @Arguments modtbl
    #! @Group CharacterDegreesOfBlocks
    #! @FunctionLabel 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  a  chapter,  all functions without separate 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:
  
  
    #! @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.   Additionally,   the   chapter   will   be   stored  as
  _Chapter_label.xml.
  
  
  2.2-2 @Section name
  
  Sets a section like chapter sets a chapter.
  
  
    #! @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.
  
  
  2.2-3 @EndSection
  
  Closes the current section. Please be careful here. Closing a section before
  opening it might cause unexpected errors.
  
  
    #! @EndSection
    #### The following text again belongs to the chapter
    #! Now we could start a second section if we want to.
  
  
  
  2.2-4 @Subsection name
  
  Sets a subsection like chapter sets a chapter.
  
  
    #! @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.
  
  
  2.2-5 @EndSubsection
  
  Closes  the current subsection. Please be careful here. Closing a subsection
  before opening it might cause unexpected errors.
  
  
    #! @EndSubsection
    #### The following text again belongs to the section
    #! Now we are in the section again
  
  
  
  2.2-6 @BeginAutoDoc
  
  Causes   all  subsequent  declarations  to  be  documented  in  the  manual,
  regardless of whether they have an AutoDoc comment in front of them or not.
  
  
  2.2-7 @EndAutoDoc
  
  Ends  the  affect of @BeginAutoDoc. So from here on, again only declarations
  with an explicit AutoDoc comment in front are added to the manual.
  
  
    #! @BeginAutoDoc
    
    DeclareOperation( "Operation1", [ IsList ] );
    
    DeclareProperty( "IsProperty", IsList );
    
    #! @EndAutoDoc
  
  
  Both, Operation1 and IsProperty would appear in the manual.
  
  
  2.2-8 @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-9 @EndGroup
  
  Ends the current group.
  
  
    #! @BeginGroup MyGroup
    #!
    DeclareAttribute( "GroupedAttribute",
                      IsList );
    
    DeclareOperation( "NonGroupedOperation",
                      [ IsObject ] );
    
    #!
    DeclareOperation( "GroupedOperation",
                      [ IsList, IsRubbish ] );
    #! @EndGroup
  
  
  
  2.2-10 @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 groups.
  
  
  2.2-11 @ResetLevel
  
  Resets the current level to 0.
  
  
  2.2-12 @BeginExample and @EndExample
  
  @BeginExample inserts an example into the manual. The syntax for examples is
  different  from GAPDocs example syntax in order to have a file that contains
  the  example  and  is  GAP  readable.  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.
  
  
    #! @BeginExample
    S5 := SymmetricGroup(5);
    #! Sym( [ 1 .. 5 ] )
    Order(S5);
    #! 120
    #! @EndExample
  
  
  
  2.2-13 @ExampleSession and @EndExampleSession
  
  @ExampleSession  inserts  an  example  into  the  manual, but in a different
  syntax. For example, consider
  
  
    #! @BeginExample
    S5 := SymmetricGroup(5);
    #! Sym( [ 1 .. 5 ] )
    Order(S5);
    #! 120
    #! @EndExample
  
  
  As  you  can see, the commands are not commented and hence are executed when
  the  file  containing the example block is read. To insert examples directly
  into source code files, one can instead use @ExampleSession:
  
  
    #! @ExampleSession
    #! gap> S5 := SymmetricGroup(5);
    #! Sym( [ 1 .. 5 ] )
    #! gap> Order(S5);
    #! 120
    #! @EndExampleSession
  
  
  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.
  
  
  2.2-14 @BeginLog and @EndLog
  
  Works  just  like  the  @BeginExample  command,  but the example will not be
  tested. See the GAPDoc manual for more information.
  
  
  2.2-15 @BeginLogSession and @EndLogSession
  
  Works  just  like the @BeginExampleSession command, but the example will not
  be  tested  if  manual  examples  are  run.  See  the GAPDoc manual for more
  information.
  
  
  2.2-16 @DoNotReadRestOfFile
  
  Prevents  the rest of the file from being read by the parser. Useful for not
  finished or temporary files.
  
  
    #! This will appear in the manual
    
    #! @DoNotReadRestOfFile
    
    #! This will not appear in the manual.
  
  
  
  2.2-17 @BeginChunk name, @EndChunk, and @InsertChunk name
  
  Text insider of 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-18 @BeginSystem name, @EndSystem, and @InsertSystem name
  
  Same  as  @BeginChunk  etc.  This  command  is  deprecated. Please use chunk
  instead.
  
  
  2.2-19 @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-20 @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.3 Title page commands
  
  The  following  commands  can  be used to add the corresponding parts to the
  title page of the document, in case the 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  they do not have a PackageInfo to extract
  those information.
  
  
  2.4 Plain text files
  
  AutoDoc 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.
  
  
  2.5 Grouping
  
  In GAPDoc, it is possible to make groups of ManItems, 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. Note that it is currently
  not  possible to give a header to the Group in the manual, but the generated
  ManItem heading of the first entry will be used.
  
  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
    
    #! @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 FirstOperation
  
  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.