<Chapter Label="Tutorials">
<Heading>Getting started using &AutoDoc;</Heading>

&AutoDoc; is a &GAP; package which is meant to aide &GAP; package
authors in creating and maintaing the documentation of their packages.
In this capacity it builds upon &GAPDoc; (and hence is not a replacement
for it, but rather a complement).

In this chapter we describe how you can get started using &AutoDoc; for
your package. To this end, we will assume from now on that your package
is called &SomePackage;.

<Section Label="Tut:Scratch">
<Heading>Creating a package manual from scratch</Heading>

Suppose your package is already up and running, but so far has no
manual. Then you can rapidly generate a <Q>scaffold</Q> for a manual using the
<Ref Func="AutoDoc"/> command like this:
<Listing>
LoadPackage( "AutoDoc" );
AutoDoc( "SomePackage" : scaffold := true );
</Listing>
This creates two XML files <F>doc/SomePackage.xml</F> and
<F>doc/title.xml</F> insider the package directory and then runs
&GAPDoc; on them to produce a nice initial PDF and HTML version of your
fresh manual.
<P/>

To ensure that the &GAP; help system picks up your package manual, you
should also add the following (or a variation of it) to your
<F>PackageInfo.g</F>:
<Listing>
PackageDoc := rec(
  BookName  := ~.PackageName,
  ArchiveURLSubset := ["doc"],
  HTMLStart := "doc/chap0.html",
  PDFFile   := "doc/manual.pdf",
  SixFile   := "doc/manual.six",
  LongTitle := ~.Subtitle,
),
</Listing>

Congratulations, your package now has a minimal working manual. Of
course it will be mostly empty for now, but it already should contain
some useful information, based on the data in your <F>PackageInfo.g</F>.
This includes your package's name, version and description as well as
information about its authors. And if you ever change the package data,
(e.g. because your email address changed), just re-run the above command
to regenerate the two main XML files with the latest information.
<P/>

Next of course you need to provide actual content (unfortunately, we were
not yet able to automate <E>that</E> for you, more research on artificial intelligence
is required).
To add more content, you have several options: You could add further &GAPDoc;
XML files containing extra chapters, sections and so on. Or you could use classic &GAPDoc;
source comments (in either case, see Section <Ref Sect="Tut:IntegrateExisting"/> on
how to teach the <Ref Func="AutoDoc"/> command to include this extra documentation).
Or you could use the special documentation facilities &AutoDoc; provides (see Section
<Ref Sect="Tut:AdvancedAutoDoc"/>).
<P/>

You may also wish to consult Section <Ref Sect="Tut:AutoRegenerate"/> for hints
on automatically re-generating your package manual when necessary.

</Section>


<Section Label="Tut:AdvancedAutoDoc">
<Heading>Documenting code with &AutoDoc;</Heading>

To get one of your global functions, operations, attributes
etc. to appear in the package manual, simply insert an &AutoDoc; comment
of the form <C>#!</C> directly in front of it. For example:
<Listing>
#!
DeclareOperation( "ToricVariety", [ IsConvexObject ] );
</Listing>

This tiny change is already sufficient to ensure that the operation
appears in the manual. In general, you will want to add further
information about the operation, such as in the following example:

<Listing><![CDATA[
#! @Arguments conv
#! @Returns a toric variety
#! @Description
#!  Creates a toric variety out
#!  of the convex object <A>conv</A>.
DeclareOperation( "ToricVariety", [ IsConvexObject ] );
]]></Listing>

For a thorough description of what you can do with &AutoDoc;
documentation comments, please refer to chapter <Ref Chap="Comments"/>.
<P/>

<!--
Once we switched AutoDoc itself to use AutoDoc comments,
mention that, i.e. point out that all operations and functions
documented in this manual are documented exactly like
described here, and that one can hence use that as examples.
-->

<!-- 

#  <#GAPDoc Label="ToricVarietyConst">
#  <ManSection>
#    <Oper Arg="conv" Name="ToricVariety"
#          Label="for IsConvexObject"/>
#    <Returns>a toric variety</Returns>
#    <Description>
#      Creates a toric variety out 
#      of the convex object <A>conv</A>.
#    </Description>
#  </ManSection>
#  <#/GAPDoc>
DeclareOperation( "ToricVariety",
                  [ IsConvexObject ] );
 -->


Suppose you have not been using &GAPDoc; before but instead used the process
described in section <Ref Sect="Tut:Scratch"/> to create your manual.
Then the following &GAP; command will regenerate the manual and automatically
include all newly documented functions, operations etc.:

<Listing>
LoadPackage("AutoDoc");
AutoDoc("SomePackage" : scaffold := true, autodoc := true );
</Listing>

If you are not using the scaffolding feature, e.g. because you already
have an existing &GAPDoc; based manual, then you can still use &AutoDoc;
documentation comments. Just make sure to first edit the main XML
file of your documentation, and insert the line
<Listing>
#Include SYSTEM "AutoDocMainFile.xml"
</Listing>
in a suitable place. This means that you can mix &AutoDoc; documentation
comment freely with your existing documentation; you can even still make
use of any existing &GAPDoc; documentation comments in your code.

The following command should be useful for you in this case; it
still scans the package code for &AutoDoc; documentation comments
and the runs &GAPDoc; to produce HTML and PDF output, but does not
touch your documentation XML files otherwise.
<Listing>
LoadPackage("AutoDoc");
AutoDoc("SomePackage" : autodoc := true );
</Listing>


<!--
TODO: Explain how to mix this with existing &GAPDoc; XML files.
-->

</Section>


<Section Label="Tut:IntegrateExisting">
<Heading>Using &AutoDoc; in an existing &GAPDoc; manual</Heading>

TODO: Explain that it might still be interesting to switch to using scaffolding?
<P/>

TODO: Demonstrate how to add / mix your own XML files, &AutoDoc; generated
XML files, and &GAPDoc; stuff...


</Section>


<Section Label="Tut:AutoRegenerate">
<Heading>Automatic regeneration of the manual</Heading>

You will probably want to re-run the  <Ref Func="AutoDoc"/> command
frequently, e.g. whenever you modified your documentation or your
<F>PackageInfo.g</F>. To make this more convenient and reproducible, we
recommend putting its invocation into a file <F>makedoc.g</F> in your package
directory. Then you can regenerate the manual from the command line with the
following simple command (assuming you are in the package directory):
<Listing>
gap makedoc.g
</Listing>

</Section>

<Section Label="Tut:PackageInfo">
<Heading>What is taken from <F>PackageInfo.g</F></Heading>

&AutoDoc; can extract data from <F>PackageInfo.g</F> in order to
generate a title page. Specifically, the following components
of the package info record are looked at:

<List>

<Mark>Version</Mark><Item>
This is used to set the <C>&lt;Version></C> element of the
title page, with the string <Q>Version </Q> prepended.
</Item>

<Mark>Date</Mark><Item>
This is used to set the <C>&lt;Date></C> element of the
title page.
</Item>

<Mark>Subtitle</Mark><Item>
This is used to set the <C>&lt;Subtitle></C> element of the
title page (the <C>&lt;Title></C> is set to the package name).
</Item>

<Mark>Persons</Mark><Item>
This is used to generate <C>&lt;Author></C> elements in the
generated title page.
</Item>

<Mark>PackageDoc</Mark><Item>
This is a record (or a list of records) which is used to tell the
&GAP; help system about the package manual. Currently &AutoDoc;
extracts the value of the <C>PackageDoc.BookName</C> component
and then passes that on to &GAPDoc; when creating the HTML, PDF
and text versions of the manual.
</Item>

<Mark>AutoDoc</Mark><Item>
This is a record which can be used to control the scaffolding performed by
&AutoDoc;, specifically to provide extra information for the title page. For
example, you can set <C>AutoDoc.TitlePage.Copyright</C> to a string which will
then be inserted on the generated title page. Using this method you can
customize the following title page elements: <C>TitleComment</C>,
<C>Abstract</C>, <C>Copyright</C>, <C>Acknowledgements</C> and <C>Colophon</C>.

<P/>
Note that <C>AutoDoc.TitlePage</C> behaves exactly the same
as the <C>scaffold.TitlePage</C> parameter of the <Ref Func="AutoDoc"/>
function.
</Item>

</List>

</Section>

</Chapter>
