@Chapter Comments
@ChapterTitle &AutoDoc; documentation comments


You can document declarations of global functions and variables, operations,
attributes etc. by inserting <E>&AutoDoc;</E> comments into your sources before these declarations.
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
#!
DeclareOperation( "AnOperation",
                  [ IsList ] );
```

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

For declaration documentation, the associated declaration must appear
immediately after the &AutoDoc; comment block. In particular, do not insert
other code (such as <C>if false then</C> or assignments) between the comment
block and the <C>Declare...</C> statement.

This also works for <C>InstallMethod</C> and <C>InstallOtherMethod</C>.
In that case, &AutoDoc; uses the installed method's name and filter list to
create a manual entry for the implemented item.

Inside of &AutoDoc; comments, <E>&AutoDoc; commands</E>
starting with <C>@</C> can be used to control the output &AutoDoc; produces.
Any comment line that does <E>not</E> start with an &AutoDoc; command is treated
as regular documentation text and may contain (almost) arbitrary &GAPDoc; XML
markup, such as `<Ref>`, `<A>`, `<List>`, and similar tags.
This lets you use the normal &GAPDoc; formatting toolbox directly inside
&AutoDoc; comments.

For example:
```@listing
#! @Description
#!  See <Ref Chap="Chapter_Tutorials"/> for setup details.
#!  The argument <A>obj</A> must satisfy <K>IsObject</K>.
```

As explained in chapter <Ref Chap="Chapter_Overview"/>, you can combine &AutoDoc;
comments with hand-written XML and classic &GAPDoc; comments. For practical
setup and migration workflows, see chapter <Ref Chap="Chapter_Tutorials"/>.


@Section Documenting declarations

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 <C>@Description <A>descr</A></C>
@SubsectionLabel @Description

@Index "@Description" <C>@Description <A>descr</A></C>
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 <C>@Returns <A>ret_val</A></C>
@SubsectionLabel @Returns

@Index "@Returns" <C>@Returns <A>ret_val</A></C>
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 returned by the documented function.

@Subsection <C>@Arguments <A>args</A></C>
@SubsectionLabel @Arguments

@Index "@Arguments" <C>@Arguments <A>args</A></C>
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>.

For <C>DeclareGlobalName</C>, using <C>@Arguments</C> or <C>@Returns</C> also
makes &AutoDoc; document the item as a function. This is useful because
<C>DeclareGlobalName</C> itself does not reveal whether the name denotes a
function or a variable.

@Subsection <C>@ItemType <A>kind</A></C>
@SubsectionLabel @ItemType

@Index "@ItemType" <C>@ItemType <A>kind</A></C>
Overrides the kind of manual item created for the following declaration or
installed method. The supported values are <C>Attr</C>, <C>Cat</C>,
<C>Coll</C>, <C>Constr</C>, <C>Fam</C>, <C>Filt</C>, <C>Func</C>,
<C>InfoClass</C>, <C>Meth</C>, <C>Oper</C>, <C>Prop</C>, <C>Repr</C>,
and <C>Var</C>.

The values <C>Cat</C>, <C>Coll</C>, and <C>Repr</C> are &AutoDoc;-specific
aliases. They emit <C>Filt</C> entries with the corresponding &GAPDoc; filter
type.

This is useful when the source code alone does not determine which manual item
kind should be emitted. For many declarations such as <C>DeclareAttribute</C>
or <C>DeclareProperty</C>, &AutoDoc; already knows the intended type from the
declaration itself.

It is useful for <C>DeclareGlobalName</C>, because that declaration can
refer to either a function or a variable. &AutoDoc; defaults such entries to
<C>Var</C>, but switches to <C>Func</C> as soon as <C>@Arguments</C> or
<C>@Returns</C> indicates function-style documentation. You can still use
<C>@ItemType</C> to override this explicitly.

It is useful for <C>DeclareSynonym</C>, because that declaration can
document a function synonym or one of several filter-like synonyms. Use
<C>@ItemType Filt</C>, <C>Cat</C>, <C>Coll</C>, or <C>Repr</C> to control which
kind of filter entry should be emitted.

For example:

```@listing
#! @ItemType Repr
DeclareSynonym( "IsSomethingRep", IsComponentObjectRep );
```

This makes &AutoDoc; emit a
<C>&lt;Filt Type="Representation" .../&gt;</C> manual entry.

@Subsection <C>@Group <A>grpname</A></C>
@SubsectionLabel @Group

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

@Subsection <C>@Label <A>label</A></C>
@SubsectionLabel @Label

@Index "@Label" <C>@Label <A>label</A></C>
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.
```@listing
#! @Label testlabel
DeclareProperty( "AProperty",
                 IsObject );
```
leads to this:
```@listing
<ManSection>
  <Prop Arg="arg" Name="AProperty" Label="testlabel"/>
 <Returns> <K>true</K> or <K>false</K>
</Returns>
 <Description>
 </Description>
</ManSection>
```
while
```@listing
#!
DeclareProperty( "AProperty",
                 IsObject );
```
leads to this:
```@listing
<ManSection>
  <Prop Arg="arg" Name="AProperty" Label="for IsObject"/>
 <Returns> <K>true</K> or <K>false</K>
</Returns>
 <Description>
 </Description>
</ManSection>
```


@Subsection <C>@ChapterInfo <A>chapter</A>, <A>section</A></C>
@SubsectionLabel @ChapterInfo

@Index "@ChapterInfo" `@ChapterInfo`
Adds the entry to the given chapter and section. Here,
<A>chapter</A> and <A>section</A> are the respective
titles.
As an example, a full &AutoDoc; comment with all options could look like this:

```@listing
#! @Description
#! Computes the list of lists of degrees of ordinary characters
#! associated to the $p$-blocks of the group $G$
#! with $p$-modular character table <A>modtbl</A>
#! and underlying ordinary character table `ordtbl`.
#! @Returns a list
#! @Arguments modtbl
#! @Group CharacterDegreesOfBlocks
#! @Label chardegblocks
#! @ChapterInfo Blocks, Attributes
DeclareAttribute( "CharacterDegreesOfBlocks",
        IsBrauerTable );
```

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

@Subsection <C>@Chapter <A>name</A></C>
@SubsectionLabel @Chapter

@Index "@Chapter" `@Chapter`
@Index "@ChapterLabel" `@ChapterLabel`
@Index "@ChapterTitle" `@ChapterTitle`
Sets the active chapter, all subsequent functions which do not have an explicit chapter
declared in their &AutoDoc; comment via <C>@ChapterInfo</C> 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 <C>@Description</C>, will be added to the chapter as regular text. Additionally,
the chapters label will be set to <C>Chapter_</C><A>name</A>.

Example:

```@listing
#! @Chapter My chapter
#!  This is my chapter.
#!  I document my stuff in it.
```

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> instead of
<C>Chapter_</C><A>name</A>.

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

The <C>@ChapterTitle</C> <A>title</A> command
can be used to set a heading for the chapter that is different from <A>name</A>.
Note that the title does not affect the label.

If you use all three commands, i.e.,
```@listing
#! @Chapter name
#! @ChapterLabel label
#! @ChapterTitle title
```
<C>title</C> is used for the headline, <C>label</C> for cross-referencing, and <C>name</C>
for setting the same chapter as active chapter again.

@Subsection <C>@Appendix <A>name</A></C>
@SubsectionLabel @Appendix

@Index "@Appendix" `@Appendix`
This is analogous to <C>@Chapter</C>, but generates `Appendix`
elements instead of `Chapter` elements. When scaffolding generates the main
XML file, appendices created this way are included automatically after any
files listed in `scaffold.appendix`.

Example:

```@listing
@Appendix Supplementary material

@Section Additional tables
```

@Subsection <C>@Section <A>name</A></C>
@SubsectionLabel @Section

@Index "@Section" `@Section`
@Index "@SectionLabel" `@SectionLabel`
@Index "@SectionTitle" `@SectionTitle`
Sets an active section like <C>@Chapter</C> sets an active chapter.
The section automatically ends with the next <C>@Section</C> or <C>@Chapter</C> command.

```@listing
#! @Section My first manual section
#!  In this section I am going to document my first method.
```

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> instead of
<C>Chapter_chaptername_Section_</C><A>name</A>.

The <C>@SectionTitle</C> <A>title</A> command
can be used to set a heading for the section that is different from <A>name</A>.

@Subsection <C>@Subsection <A>name</A></C>
@SubsectionLabel @Subsection

@Index "@Subsection" `@Subsection`
@Index "@SubsectionLabel" `@SubsectionLabel`
@Index "@SubsectionTitle" `@SubsectionTitle`
Sets an active subsection like <C>@Section</C> sets an active section.
The subsection automatically ends with the next <C>@Subsection</C>,
<C>@Section</C> or <C>@Chapter</C> command. It also ends with the
next documented function. Indeed, internally each function <Q>manpage</Q>
is treated like a subsection.

```@listing
#! @Subsection My first manual subsection
#!  In this subsection I am going to document my first example.
```

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> instead of
<C>Chapter_chaptername_Section_sectionname_Subsection_</C><A>name</A>.

The <C>@SubsectionTitle</C> <A>title</A> command
can be used to set a heading for the subsection that is different from <A>name</A>.

@Subsection <C>@BeginGroup <A>[grpname]</A></C>
@SubsectionLabel @BeginGroup

@Index "@BeginGroup" `@BeginGroup`
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.

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

@Subsection <C>@EndGroup</C>
@SubsectionLabel @EndGroup

@Index "@EndGroup" `@EndGroup`
Ends the current group.

```@listing
#! @BeginGroup MyGroup
#!
DeclareAttribute( "GroupedAttribute",
                  IsList );

DeclareOperation( "NonGroupedOperation",
                  [ IsObject ] );

#!
DeclareOperation( "GroupedOperation",
                  [ IsList, IsRubbish ] );
#! @EndGroup
```

@Subsection @GroupTitle <A>title</A>
@SubsectionLabel @GroupTitle

@Index "@GroupTitle" `@GroupTitle`
Sets the subsection heading for the current group to <A>title</A>. In the
absence of any <C>@GroupTitle</C> command, the heading will be the name of the
first entry in the group. See <Ref Sect="Section_Groups"/> for more information.

@Subsection <C>@BeginExample</C> and <C>@EndExample</C>
@SubsectionLabel @BeginExample

@Index "@BeginExample" `@BeginExample`
@Index "@EndExample" `@EndExample`
<C>@BeginExample</C> marks the start of an example to be put into the manual.
It differs from &GAPDoc;'s `<Example>` (see <Ref Subsect="Log" BookName="gapdoc"/>),
in that it expects actual code (not in a comment) interspersed with comments,
to allow for examples files that can be both executed by &GAP;, and parsed
by &AutoDoc;. To achieve this, &GAP; commands are not preceded by a comment,
while output has to be preceded by an &AutoDoc; comment.
The <C>gap&gt;</C> prompt for the display in the manual is added by &AutoDoc;.
<C>@EndExample</C> ends the example block.

To illustrate this command, consider this input:
```@listing
#! @BeginExample
S5 := SymmetricGroup(5);
#! Sym( [ 1 .. 5 ] )
Order(S5);
#! 120
#! @EndExample
```
This results in the following output:
<Example>
gap> S5 := SymmetricGroup(5);
Sym( [ 1 .. 5 ] )
gap> Order(S5);
120
</Example>
The &AutoDoc; command <C>@Example</C> is an alias of <C>@BeginExample</C>.
If you enable <C>extract_examples := true</C> when calling <Ref Func="AutoDoc"/>,
these examples can also be turned into <F>.tst</F> files (see
Section <Ref Sect="Subsection_Tut:IntegrateExisting:EverythingThere"/>).

@Subsection <C>@BeginExampleSession</C> and <C>@EndExampleSession</C>
@SubsectionLabel @BeginExampleSession

@Index "@BeginExampleSession" `@BeginExampleSession`
@Index "@EndExampleSession" `@EndExampleSession`
<C>@BeginExampleSession</C> marks the start of an example to be put into the manual,
while <C>@EndExampleSession</C> ends the example block.
It is the direct analog of &GAPDoc;'s `<Example>` (see <Ref Subsect="Log" BookName="gapdoc"/>).

To illustrate this command, consider this input:
```@listing
#! @BeginExampleSession
#! gap> S5 := SymmetricGroup(5);
#! Sym( [ 1 .. 5 ] )
#! gap> Order(S5);
#! 120
#! @EndExampleSession
```
This results in the following output:
<Example>
gap> S5 := SymmetricGroup(5);
Sym( [ 1 .. 5 ] )
gap> Order(S5);
120
</Example>

It inserts an example into the manual just as <C>@Example</C> 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 &AutoDoc; comment (<C>#!</C>).
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 <C>#!</C> and the <C>gap&gt;</C> prompt.
The &AutoDoc; command <C>@ExampleSession</C> is an alias of <C>@BeginExampleSession</C>.

@Subsection <C>@BeginLog</C> and <C>@EndLog</C>
@SubsectionLabel @BeginLog

@Index "@BeginLog" `@BeginLog`
@Index "@EndLog" `@EndLog`
Works just like the <C>@BeginExample</C> command, but the example
will not be tested. See the &GAPDoc; manual for more information.
The &AutoDoc; command <C>@Log</C> is an alias of <C>@BeginLog</C>.

@Subsection <C>@BeginLogSession</C> and <C>@EndLogSession</C>
@SubsectionLabel @BeginLogSession

@Index "@BeginLogSession" `@BeginLogSession`
@Index "@EndLogSession" `@EndLogSession`
Works just like the <C>@BeginExampleSession</C> command, but the example
will not be tested if manual examples are run. It is the direct analog of
&GAPDoc;'s `<Log>` (see <Ref Subsect="Log" BookName="gapdoc"/>).
The &AutoDoc; command <C>@LogSession</C> is an alias of <C>@BeginLogSession</C>.

@Subsection <C>@DoNotReadRestOfFile</C>
@SubsectionLabel @DoNotReadRestOfFile

@Index "@DoNotReadRestOfFile" `@DoNotReadRestOfFile`
Prevents the rest of the file from being read by the parser. Useful for
unfinished or temporary files.

```@listing
#! This will appear in the manual

#! @DoNotReadRestOfFile

#! This will not appear in the manual.
```

@Subsection <C>@BeginChunk <A>name</A></C>, <C>@EndChunk</C>, and <C>@InsertChunk <A>name</A></C>
@SubsectionLabel @BeginChunk

@Index "@BeginChunk" <C>@BeginChunk <A>name</A></C>
@Index "@EndChunk" `@EndChunk`
@Index "@EndChunk" <C>@InsertChunk <A>name</A></C>
Text inside a <C>@BeginChunk</C> / <C>@EndChunk</C> 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
<C>@InsertChunk <A>name</A></C> command.

If you do not provide an <C>@EndChunk</C>, the chunk ends at the end of the file.
```@listing
#! @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:

```@listing
#! @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:

```@listing
#! @InsertChunk Example_Symmetric_Group
```

@Subsection <C>@BeginCode <A>name</A></C>, @EndCode, and <C>@InsertCode <A>name</A></C>
@SubsectionLabel @BeginCode

@Index "@BeginCode" <C>@BeginCode <A>name</A></C>
@Index "@EndCode" `@EndCode`
@Index "@InsertCode" <C>@InsertCode <A>name</A></C>
Inserts the text between <C>@BeginCode</C> and <C>@EndCode</C> verbatim at the point where
<C>@InsertCode</C> is called. This is useful to insert code excerpts
directly into the manual.
```@listing
#! @BeginCode Increment
i := i + 1;
#! @EndCode

#! @InsertCode Increment
## Code is inserted here.
```

@Subsection <C>@LatexOnly <A>text</A></C>, <C>@BeginLatexOnly</C>, and <C>@EndLatexOnly</C>
@SubsectionLabel @LatexOnly

@Index "@LatexOnly" <C>@LatexOnly <A>text</A></C>
@Index "@BeginLatexOnly" `@BeginLatexOnly`
@Index "@EndLatexOnly" `@EndLatexOnly`
Code inserted between <C>@BeginLatexOnly</C> and <C>@EndLatexOnly</C> or after <C>@LatexOnly</C> is only inserted
in the PDF version of the manual or worksheet. It can hold arbitrary &LaTeX;-commands.
```@listing
#! @BeginLatexOnly
#! \include{picture.tex}
#! @EndLatexOnly

#! @LatexOnly \include{picture.tex}
```

@Subsection <C>@NotLatex <A>text</A></C>, <C>@BeginNotLatex</C>, and <C>@EndNotLatex</C>
@SubsectionLabel @NotLatex

@Index "@NotLatex" <C>@NotLatex <A>text</A></C>
@Index "@BeginNotLatex" `@BeginNotLatex`
@Index "@EndNotLatex" `@EndNotLatex`
Code inserted between <C>@BeginNotLatex</C> and <C>@EndNotLatex</C> or after <C>@NotLatex</C> is inserted
in the HTML and text versions of the manual or worksheet, but not in the PDF version.
```@listing
#! @BeginNotLatex
#! For further information see the PDF version of this manual.
#! @EndNotLatex

#! @NotLatex For further information see the PDF version of this manual.
```

@Subsection <C>@Index <A>key</A> [<A>entry text</A>]</C>
@SubsectionLabel @Index

@Index "@Index" <C>@Index <A>key</A> [<A>entry text</A>]</C>
Adds an index entry to the current documentation text.
The command <C>@Index key entry text</C> generates
`<Index Key="key">entry text</Index>`.
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.
<C>@Index "my key" entry text</C>.
The entry text is processed like normal documentation text, so markdown-like
inline code such as `true` is supported.

@Section Title page commands
@SectionLabel TitlepageCommands

The following commands can be used to add corresponding parts to the
title page of a document generated by &AutoDoc;.
<List>
  <Item>
    <C>@Title</C>
  </Item>
  <Item>
    <C>@Subtitle</C>
  </Item>
  <Item>
    <C>@Version</C>
  </Item>
  <Item>
    <C>@TitleComment</C>
  </Item>
  <Item>
    <C>@Author</C>
  </Item>
  <Item>
    <C>@Date</C>
  </Item>
  <Item>
    <C>@Address</C>
  </Item>
  <Item>
    <C>@Abstract</C>
  </Item>
  <Item>
    <C>@Copyright</C>
  </Item>
  <Item>
    <C>@Acknowledgements</C>
  </Item>
  <Item>
    <C>@Colophon</C>
  </Item>
</List>
Many of these values can (and for package manuals typically should) be
extracted from <F>PackageInfo.g</F>. If you set them explicitly in comments,
they override extracted or scaffold-defined values. This is usually most useful
for worksheets created with <Ref Func="AutoDocWorksheet"/>,
since worksheets do not have a <F>PackageInfo.g</F> file from which this information could be extracted.

@Section Plain text files
@SectionLabel PlainText

Files that have the suffix <C>.autodoc</C> and are listed in the
<C>autodoc.files</C> option of <Ref Func="AutoDoc"/>, resp. are contained in
one of the directories listed in <C>autodoc.scan_dirs</C> or one of their
subdirectories, are treated as
standalone &AutoDoc; 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.

Conceptually, a <F>.autodoc</F> file uses the same parser as &AutoDoc;
comments, but without the comment marker. In a <F>.autodoc</F> file, lines do
not need to start with <C>#!</C> and in fact usually should not. This makes
<F>.autodoc</F> files one convenient way to replace hand-written XML chapters
when you prefer &AutoDoc;'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 &AutoDoc; itself still uses that
style in files such as <F>gap/Magic.gd</F>. For the surrounding workflow, see
Chapter <Ref Chap="Chapter_Tutorials"/>.

The most important difference from declaration comments is that a plain text
file does <E>not</E> document a declaration by adjacency. There is no following
<C>Declare...</C> or <C>InstallMethod</C> statement for &AutoDoc; to inspect.
So commands whose meaning depends on such a declaration only make sense in
source comments immediately before that declaration.

In practice, this gives the following rule of thumb.

<List>
  <Item>
    Use source comments beginning with <C>#!</C> to document declarations.
    This is the mode for <C>@Description</C>, <C>@Returns</C>,
    <C>@Arguments</C>, <C>@Label</C>, <C>@Group</C>, and <C>@ChapterInfo</C>.
  </Item>
  <Item>
    Use either <F>.autodoc</F> files or source comments for standalone manual
    structure and prose. Commands such as <C>@Chapter</C>, <C>@Section</C>,
    <C>@Subsection</C>, grouping commands, examples and logs, chunks and code
    insertion, <C>@Index</C>, title-page commands, Markdown-style headings,
    fenced code blocks, and ordinary &GAPDoc; XML markup work in both styles.
  </Item>
</List>

As a concrete example, the following file can serve as a complete chapter
written in <F>.autodoc</F> format.

```@listing
@Chapter Test
@Section First Section
@Subsection First Subsection

This text belongs directly to the manual chapter.
It can use XML tags such as <A>arg</A> or <Ref .../>.

@BeginExampleSession
gap> S5 := SymmetricGroup(5);
Sym( [ 1 .. 5 ] )
gap> Size(S5);
120
@EndExampleSession

@Index "Worksheet Autoplain" Plain worksheet index entry with `true`
```

This is essentially the style used in the worksheet fixture
<F>tst/worksheets/autoplain.sheet/plain.autodoc</F>.

The same structural commands can also be used inside source comments, for
example:

```@listing
#! @Chapter Reference
#! @Section The AutoDoc() function
#! Some introductory text for this section.
```

This source-comment style is still fully supported and is used in
<F>gap/Magic.gd</F>.

The 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 <F>_AutoDocMainFile.xml</F> from the main XML
file as described in Chapter <Ref Chap="Chapter_Tutorials"/>, and add one or
more <F>.autodoc</F> files via <C>autodoc.files</C> or <C>autodoc.scan_dirs</C>.
Those files can provide tutorial chapters or appendices, while declaration
documentation continues to live in source comments and older XML chapters remain
unchanged.

One caveat is worth keeping in mind. If you want a standalone
<F>.autodoc</F> 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 <C>#60</C> in the
AutoDoc issue tracker.

So, while <F>.autodoc</F> 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.

@Section Grouping
@SectionLabel Groups

In &GAPDoc;, 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 <C>@GroupTitle</C>
command; if that is not supplied, then the heading of the first  manual item
in the group will be used as the heading.

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.

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
#! @BeginGroup Group1
#! @GroupTitle A family of operations

#! @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:

```@listing
<ManSection Label="Group1">
<Heading>A family of operations</Heading>
  <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 IsGroup, IsInt"/>
 <Description>
First sentence.
Second sentence.
Third sentence.
 </Description>
</ManSection>
```

@Section Markdown-like formatting of text in &AutoDoc;
@SectionLabel MarkdownExtension

&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 Lists
@SubsectionLabel MarkdownExtensionList

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
#! 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:<Br/>
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.<Br/>

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

@Subsection Math modes
@SubsectionLabel MarkdownExtensionMath

One can start an inline formula with a &#36;, and also end it with &#36;, just like in &LaTeX;. This will translate into
   &GAPDoc;s inline math environment. For display mode one can use &#36;&#36;, also like &LaTeX;.
   
```@listing
#! This is an inline formula: $1+1 = 2$.
#! This is a display formula:
#! $$ \sum_{i=1}^n i. $$
```

   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 Emphasize
@SubsectionLabel MarkdownExtensionEmph

One can emphasize text by using two asterisks (&#42;&#42;) or two underscores (&#95;&#95;) at the
   beginning and the end of the text which should be emphasized. Example:
   
```@listing
#! **This** is very important.
#! This is __also important__.
#! **Naturally, more than one line
#! can be important.**
```

 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 Inline code
@SubsectionLabel MarkdownExtensionInlineCode

One can mark inline code snippets by using backticks (&#96;) at the
   beginning and the end of the text which should be marked as code. Example:

```@listing
#! Call function `foobar()` at the start.
```

    This produces the following output:<Br/>
    Call function <C>foobar()</C> at the start.

@Subsection Fenced code blocks
@SubsectionLabel MarkdownExtensionFencedCode

One 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
   <C>@listing</C>, <C>@example</C>, and <C>@log</C> select the corresponding
   GAPDoc element; any other value is currently ignored. If nothing is specified
   the default is to generate `<Listing>`. Example:

````@listing
#! ```@listing
#! if x = 2 then
#!   Print("1 + 1 = 2 holds, all is good\n");
#! fi;
#! ```
#! ~~~@example
#! gap> [ 1 .. 3 ] ^ 2;
#! [ 1, 4, 9 ]
#! ~~~
#! ```@log
#! #I  some log message
#! ```
````

    This produces the following output:<Br/>
```@listing
if x = 2 then
  Print("1 + 1 = 2 holds, all is good\n");
fi;
```
~~~@example
gap> [ 1 .. 3 ] ^ 2;
[ 1, 4, 9 ]
~~~
```@log
#I  some log message
```


@Section Deprecated commands
@SectionLabel Deprecated

The following commands used to be supported, but are not supported anymore.

<List>
<Mark><C>@EndSection</C></Mark>
<Item>You can simply remove any use of this, &AutoDoc; ends sections automatically
at the start of any new section or chapter.</Item>
<Mark><C>@EndSubsection</C></Mark>
<Item>You can simply remove any use of this, &AutoDoc; ends subsections automatically
at the start of any new subsection, section or chapter.</Item>
<Mark><C>@BeginAutoDoc</C> and <C>@EndAutoDoc</C></Mark>
<Item>It suffices to prepend each declaration that is meant to appear in the
    manual with a minimal &AutoDoc; comment <C>#!</C>.</Item>
<Mark><C>@BeginSystem <A>name</A></C>, <C>@EndSystem</C>, and <C>@InsertSystem <A>name</A></C></Mark>
<Item>Please use the chunk commands from subsection <Ref Subsect="Subsection_@BeginChunk"/> instead.</Item>
<Mark><C>@AutoDocPlainText</C> and <C>@EndAutoDocPlainText</C></Mark>
<Item>Use <C>.autodoc</C> files or &AutoDoc; comments instead.</Item>
</List>
