Comments.xml

<Chapter Label="Comments">
<Heading>&AutoDoc; documentation comments</Heading>

You can document declarations of global functions and variables, operations,
attributes etc. by inserting <E>&AutoDoc;</E> comments into your sources before these declaration.
An &AutoDoc; comment always starts with <C>#!</C>. This is also the smallest possible
&AutoDoc; command. If you want your declaration documented, just write
<C>#!</C> at the line before the documentation. For example:

<Listing><![CDATA[
#!
DeclareOperation( "AnOperation",
                  [ IsList ] );
]]></Listing>

This will produce a manual entry for the operation <C>AnOperation</C>.
<P/>

Inside of &AutoDoc; comments, <E>&AutoDoc; commands</E>
starting with <C>@</C> can be used to control the output &AutoDoc; produces.


<Section>
<Heading>Documenting declarations</Heading>

In the bare form above, the manual entry for <C>AnOperation</C> 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:

<Subsection Label="@Description">
<Index Key="@Description"><C>@Description</C></Index>
<Heading>@Description <A>descr</A></Heading>
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.
</Subsection>

<Subsection Label="@Returns">
<Index Key="@Returns"><C>@Returns</C></Index>
<Heading>@Returns <A>ret_val</A></Heading>
The string <A>ret_val</A> is added to the documentation, with the text <Q>Returns: </Q>
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.
</Subsection>

<Subsection Label="@Arguments">
<Index Key="@Arguments"><C>@Arguments</C></Index>
<Heading>@Arguments <A>args</A></Heading>
The string <A>args</A> 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 <Q>grp[, elm]</Q> or
<Q>xx[y[z] ]</Q>. If &GAP; options are used, this can be followed by a colon :
and one or more assignments, like <Q>n[, r]: tries := 100</Q>.
</Subsection>

<Subsection Label="@Group">
<Index Key="@Group"><C>@Group</C></Index>
<Heading>@Group <A>grpname</A></Heading>
Adds the following method to a group with the given name.
See section <Ref Sect="Groups"/> for more information about groups.
</Subsection>

<Subsection Label="@Label">
<Index Key="@Label"><C>@Label</C></Index>
<Heading>@Label <A>label</A></Heading>
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 <C>DeclareOperation</C>, <C>DeclareAttribute</C>, etc.),
a default label is generated from this filter list.
</Subsection>

<Listing><![CDATA[
#! @Label testlabel
DeclareProperty( "AProperty",
                 IsObject );
]]></Listing>
leads to this:
<ManSection>
  <Prop Arg="arg" Name="AProperty" Label="testlabel"/>
 <Returns> <C>true</C> or <C>false</C>
</Returns>
 <Description>
 </Description>
</ManSection>
while
<Listing><![CDATA[
#!
DeclareProperty( "AProperty",
                 IsObject );
]]></Listing>
leads to this:
<ManSection>
  <Prop Arg="arg" Name="AProperty" Label="for IsObject"/>
 <Returns> <C>true</C> or <C>false</C>
</Returns>
 <Description>
 </Description>
</ManSection>


<Subsection Label="@ChapterInfo">
<Index Key="@ChapterInfo"><C>@ChapterInfo</C></Index>
<Heading>@ChapterInfo <A>chapter, section</A></Heading>
Adds the entry to the given chapter and section. Here,
<A>chapter</A> and <A>section</A> are the respective
titles.
</Subsection>


As an example, a full &AutoDoc; comment for with all options could look like this:

<Listing><![CDATA[
#! @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 );
]]></Listing>

</Section>

<Section>
<Heading>Other documentation comments</Heading>

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..

<Subsection Label="@Chapter">
<Index Key="@Chapter"><C>@Chapter</C></Index>
<Index Key="@ChapterLabel"><C>@ChapterLabel</C></Index>
<Heading>@Chapter <A>name</A></Heading>
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:

<Listing><![CDATA[
#! @Chapter My chapter
#!  This is my chapter.
#!  I document my stuff in it.
]]></Listing>

The <C>@ChapterLabel</C> <A>label</A> command
can be used to set the label of the chapter to <C>Chapter_</C><A>label</A>.

Additionally, the chapter will be stored as <C>_Chapter_</C><A>label</A><C>.xml</C>.


</Subsection>

<Subsection Label="@Section">
<Index Key="@Section"><C>@Section</C></Index>
<Index Key="@SectionLabel"><C>@SectionLabel</C></Index>
<Heading>@Section <A>name</A></Heading>
Sets a section like chapter sets a chapter.

<Listing><![CDATA[
#! @Section My first manual section
#!  In this section I am going to document my first method.
]]></Listing>

The <C>@SectionLabel</C> <A>label</A> command
can be used to set the label of the section to <C>Section_</C><A>label</A>.
</Subsection>

<Subsection Label="@EndSection">
<Index Key="@EndSection"><C>@EndSection</C></Index>
<Heading>@EndSection</Heading>
Closes the current section. Please be careful here. Closing a section before
opening it might cause unexpected errors.

<Listing><![CDATA[
#! @EndSection
#### The following text again belongs to the chapter
#! Now we could start a second section if we want to.
]]></Listing>
</Subsection>

<Subsection Label="@Subsection">
<Index Key="@Subsection"><C>@Subsection</C></Index>
<Index Key="@SubsectionLabel"><C>@SubsectionLabel</C></Index>
<Heading>@Subsection <A>name</A></Heading>
Sets a subsection like chapter sets a chapter.

<Listing><![CDATA[
#! @Subsection My first manual subsection
#!  In this subsection I am going to document my first example.
]]></Listing>

The <C>@SubsectionLabel</C> <A>label</A> command
can be used to set the label of the subsection to <C>Subsection_</C><A>label</A>.

</Subsection>

<Subsection Label="@EndSubsection">
<Index Key="@EndSubsection"><C>@EndSubsection</C></Index>
<Heading>@EndSubsection</Heading>
Closes the current subsection. Please be careful here. Closing a subsection before
opening it might cause unexpected errors.
<Listing><![CDATA[
#! @EndSubsection
#### The following text again belongs to the section
#! Now we are in the section again
]]></Listing>
</Subsection>

<Subsection Label="@BeginAutoDoc">
<Index Key="@BeginAutoDoc"><C>@BeginAutoDoc</C></Index>
<Heading>@BeginAutoDoc</Heading>
Causes all subsequent declarations to be documented in the manual,
regardless of whether they have an &AutoDoc; comment in front of
them or not.
</Subsection>

<Subsection Label="@EndAutoDoc">
<Index Key="@EndAutoDoc"><C>@EndAutoDoc</C></Index>
<Heading>@EndAutoDoc</Heading>
Ends the affect of <C>@BeginAutoDoc</C>. So from here on, again only declarations
with an explicit &AutoDoc; comment in front are added to the manual.

<Listing><![CDATA[
#! @BeginAutoDoc

DeclareOperation( "Operation1", [ IsList ] );

DeclareProperty( "IsProperty", IsList );

#! @EndAutoDoc
]]></Listing>
Both, <C>Operation1</C> and <C>IsProperty</C> would appear in the manual.
</Subsection>

<Subsection Label="@BeginGroup">
<Index Key="@BeginGroup"><C>@BeginGroup</C></Index>
<Heading>@BeginGroup <A>[grpname]</A></Heading>
Starts a group. All following documented declarations without an
explicit <C>@Group</C> 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 <C>@EndGroup</C> command
is reached.
<P/>

See section <Ref Sect="Groups"/> for more information about groups.
</Subsection>

<Subsection Label="@EndGroup">
<Index Key="@EndGroup"><C>@EndGroup</C></Index>
<Heading>@EndGroup</Heading>
Ends the current group.

<Listing><![CDATA[
#! @BeginGroup MyGroup
#!
DeclareAttribute( "GroupedAttribute",
                  IsList );

DeclareOperation( "NonGroupedOperation",
                  [ IsObject ] );

#!
DeclareOperation( "GroupedOperation",
                  [ IsList, IsRubbish ] );
#! @EndGroup
]]></Listing>
</Subsection>

<Subsection Label="@Level">
<Index Key="@Level"><C>@Level</C></Index>
<Heading>@Level <A>lvl</A></Heading>
Sets the current level of the documentation. All items created after this,
chapters, sections, and items, are given the level <A>lvl</A>,
until the <C>@ResetLevel</C> command resets the level to 0 or another level
is set.
<P/>

See section <Ref Sect="Level"/> for more information about groups.
</Subsection>

<Subsection Label="@ResetLevel">
<Index Key="@ResetLevel"><C>@ResetLevel</C></Index>
<Heading>@ResetLevel</Heading>
Resets the current level to 0.
<P/>
</Subsection>


<Subsection Label="@BeginExample">
<Index Key="@BeginExample"><C>@BeginExample and @EndExample</C></Index>
<Heading>@BeginExample and @EndExample</Heading>
@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.
<Listing><![CDATA[
#! @BeginExample
S5 := SymmetricGroup(5);
#! Sym( [ 1 .. 5 ] )
Order(S5);
#! 120
#! @EndExample
]]></Listing>
</Subsection>


<Subsection Label="@ExampleSession">
<Index Key="@ExampleSession"><C>@ExampleSession, @BeginExampleSession, and @EndExampleSession</C></Index>
<Heading>@ExampleSession and @EndExampleSession</Heading>
@ExampleSession inserts an example into the manual, but in a different syntax.
For example, consider
<Listing><![CDATA[
#! @BeginExample
S5 := SymmetricGroup(5);
#! Sym( [ 1 .. 5 ] )
Order(S5);
#! 120
#! @EndExample
]]></Listing>
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:
<Listing><![CDATA[
#! @ExampleSession
#! gap> S5 := SymmetricGroup(5);
#! Sym( [ 1 .. 5 ] )
#! gap> Order(S5);
#! 120
#! @EndExampleSession
]]></Listing>
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.
</Subsection>



<Subsection Label="@BeginLog">
<Index Key="@BeginLog"><C>@BeginLog and @EndLog</C></Index>
<Heading>@BeginLog and @EndLog</Heading>
Works just like the @BeginExample command, but the example
will not be tested. See the GAPDoc manual for more information.
</Subsection>

<Subsection Label="@BeginLogSession">
<Index Key="@BeginLogSession"><C>@BeginLogSession and @EndLogSession</C></Index>
<Heading>@BeginLogSession and @EndLogSession</Heading>
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.
</Subsection>

<Subsection Label="@DoNotReadRestOfFile">
<Index Key="DoNotReadRestOfFile"><C>@DoNotReadRestOfFile</C></Index>
<Heading>@DoNotReadRestOfFile</Heading>
Prevents the rest of the file from being read by the parser. Useful for
not finished or temporary files.

<Listing><![CDATA[
#! This will appear in the manual

#! @DoNotReadRestOfFile

#! This will not appear in the manual.
]]></Listing>
</Subsection>

<Subsection Label="@BeginChunk">
<Index Key="@BeginChunk"><C>@BeginChunk, @EndChunk, and @InsertChunk</C></Index>
<Heading>@BeginChunk <A>name</A>, @EndChunk, and @InsertChunk <A>name</A></Heading>
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 <A>name</A> command.

If you do not provide an @EndChunk, the chunk ends at the end of the file.
<Listing><![CDATA[
#! @BeginChunk MyChunk
#! Hello, world.
#! @EndChunk

#! @InsertChunk MyChunk
## The text "Hello, world." is inserted right before this.
]]></Listing>

You can use this to define an example like this in one file:

<Listing><![CDATA[
#! @BeginChunk Example_Symmetric_Group
#! @BeginExample
S5 := SymmetricGroup(5);
#! Sym( [ 1 .. 5 ] )
Order(S5);
#! 120
#! @EndExample
#! @EndChunk
]]></Listing>

And then later, insert the example in a different file, like this:

<Listing><![CDATA[
#! @InsertChunk Example_Symmetric_Group
]]></Listing>

</Subsection>

<Subsection Label="@BeginSystem">
<Index Key="@BeginSystem"><C>@BeginSystem, @EndSystem, and @InsertSystem</C></Index>
<Heading>@BeginSystem <A>name</A>, @EndSystem, and @InsertSystem <A>name</A></Heading>
Same as @BeginChunk etc. This command is deprecated. Please use chunk instead.
</Subsection>

<Subsection Label="@BeginCode">
<Index Key="@BeginCode"><C>@BeginCode, @EndCode, and @InsertCode</C></Index>
<Heading>@BeginCode <A>name</A>, @EndCode, and @InsertCode <A>name</A></Heading>
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.
<Listing><![CDATA[
#! @BeginCode Increment
i := i + 1;
#! @EndCode

#! @InsertCode Increment
## Code is inserted here.
]]></Listing>
</Subsection>

<Subsection Label="@LatexOnly">
<Index Key="@LatexOnly"><C>@@LatexOnly, @BeginLatexOnly, and @EndLatexOnly</C></Index>
<Heading>@LatexOnly <A>text</A>, @BeginLatexOnly , and @EndLatexOnly</Heading>
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.
<Listing><![CDATA[
#! @BeginLatexOnly
#! \include{picture.tex}
#! @EndLatexOnly

#! @LatexOnly \include{picture.tex}
]]></Listing>
</Subsection>

</Section>


<Section Label="TitlepageCommands">
<Heading>Title page commands</Heading>

The following commands can be used to add the corresponding parts to the title page of
the document, in case the scaffolding is enabled.
<List>
  <Item>
    @Title
  </Item>
  <Item>
    @Subtitle
  </Item>
  <Item>
    @Version
  </Item>
  <Item>
    @TitleComment
  </Item>
  <Item>
    @Author
  </Item>
  <Item>
    @Date
  </Item>
  <Item>
    @Address
  </Item>
  <Item>
    @Abstract
  </Item>
  <Item>
    @Copyright
  </Item>
  <Item>
    @Acknowledgements
  </Item>
  <Item>
    @Colophon
  </Item>
</List>
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 <Ref Func="AutoDocWorksheet"/>,
since they do not have a PackageInfo to extract those information.
</Section>

 <Section Label="PlainText">
   <Heading>Plain text files</Heading>
   
   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.

</Section>

<Section Label="Groups">
<Heading>Grouping</Heading>

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.
<P/>

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 <C>@BeginGroup</C> / <C>@EndGroup</C> pairs using the
same group name, in different places, and these all will refer to the same group.
<P/>

Moreover, this means that you can add items to a group via the <C>@Group</C> command
in the &AutoDoc; comment of an arbitrary declaration, at any time.

The following code
<Listing><![CDATA[
#! @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 );
]]></Listing>

produces the following:

<ManSection Label="Group1">
  <Oper Arg="arg" Name="FirstOperation" Label="for IsInt"/>
  <Oper Arg="arg1,arg2" Name="SecondOperation" Label="for IsInt, IsGroup"/>
  <Oper Arg="arg1,arg2" Name="ThirdOperation" Label="for IsGroupIsGroup, "/>
 <Returns></Returns>
 <Description>
 First sentence.
 Second sentence.
 Third sentence.
 </Description>
</ManSection>

</Section>

<Section Label="Level">
<Heading>Level</Heading>
  Levels can be set to not write certain parts in the manual by default.
  Every entry has by default the level 0. The command <C>@Level</C> 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
  <C>AutoDoc</C>, the parts will be included in the manual at the specific place.

<Listing><![CDATA[
#! 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.
]]></Listing>
</Section>

<Section Label="MarkdownExtension">
<Heading>Markdown-like formatting of text in &AutoDoc;</Heading>

&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.

<Subsection Label="MarkdownExtensionList">
  <Heading>Lists</Heading>
  
  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:

<Listing><![CDATA[
#! 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.
]]></Listing>

This is the output:<Br/>
The list starts in the next line
  <List>
    <Item>
      item 1
    </Item>
    <Item>
      item 2
      which is a bit longer
        <List>
          <Item>
            and also contains a nested list
          </Item>
          <Item>
            with two items
          </Item>
        </List>
    </Item>
    <Item>
      item 3 of the outer list
    </Item>
  </List>
This does not belong to the list anymore.<Br/>


The *, -, and + are fully interchangeable and can even be used mixed, but this is not recommended.

</Subsection>

 <Subsection Label="MarkdownExtensionMath">
   <Heading>Math modes</Heading>
   
   One can start an inline formula with a $, and also end it with $, just like in &LaTeX;. This will translate into
   &GAPDoc;s inline math environment. For display mode one can use $$, also like &LaTeX;.
   
<Listing><![CDATA[
#! This is an inline formula: $1+1 = 2$.
#! This is a display formula:
#! $$ \sum_{i=1}^n i. $$
]]></Listing>

   produces the following output:<Br/>
   This is an inline formula: <Math>1+1 = 2</Math>.
   This is a display formula:
     <Display> \sum_{i=1}^n i. </Display>
     
</Subsection>

 <Subsection Label="MarkdownExtensionEmph">
   <Heading>Emphasize</Heading>
   
   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:
   
<Listing><![CDATA[
#! **This** is very important.
#! This is __also important__.
#! **Naturally, more than one line
#! can be important.**
]]></Listing>

 This produces the following output:<Br/>
<E>This</E> is very important.
This is <E>also important</E>.
<E>Naturally, more than one line
can be important.</E>

</Subsection>
</Section>

</Chapter>