GAP (AutoDoc) - Chapter 1: What AutoDoc offers

Goto Chapter: Top 1 2 3 4 Bib Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax on]

1 What AutoDoc offers
1.1 Core features
1.2 Adopting AutoDoc incrementally
1.3 Where to continue

### 1 What AutoDoc offers

AutoDoc helps you create and maintain package manuals for GAP. It is built on top of GAPDoc and generates the XML input that GAPDoc consumes. So AutoDoc complements GAPDoc instead of replacing it.

The package is designed for a mix and match workflow: you can adopt only the parts that help you today, and add more over time.

#### 1.1 Core features

- Build package manuals via one reproducible command, usually `gap makedoc.g`.

- Generate and maintain a title page from metadata in `PackageInfo.g`.

- Generate and maintain a main XML file that includes your chapters.

- Extract manual examples into `.tst` files via `extract_examples := true`.

- Document declarations directly in source files via AutoDoc comments beginning with `#!`.

- Organize chapter and section text either in source comments or in standalone `.autodoc` files.

- Combine AutoDoc comments, classic GAPDoc source comments, and hand-written XML chapters in one manual.

#### 1.2 Adopting AutoDoc incrementally

You do not have to switch everything at once. Typical adoption paths include:

- Use only `AutoDoc` (4.2-1) to rebuild an existing GAPDoc manual.

- Enable only title-page generation, while keeping your custom main XML.

- Keep your existing title page but use generated entities such as `&VERSION;`, `&RELEASEYEAR;`, and `&RELEASEDATE;`.

- Add AutoDoc comments only for new code, and leave old documentation as-is.

- Keep existing XML chapters, or gradually add source comments and `.autodoc` files where they fit your preferred workflow.

- Later, gradually move chapters or source documentation to your preferred style.

This flexibility is central: AutoDoc should make your current setup better, without forcing a full rewrite first.

#### 1.3 Where to continue

For practical setup and migration workflows, continue with chapter 2. For the command reference of documentation comments, including standalone `.autodoc` files, see chapter 3.

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 Bib Ind

generated by GAPDoc2HTML