---
name: swig-doc
description: 'Author and edit chapters of the SWIG Users Manual under Doc/Manual: chapter conventions, manual heading anchors, the four content `<div>` styles (code / targetlang / shell / diagram), the auto generated section TOC, the `make` targets that renumber headings and validate HTML, and the rules for cross document anchored links.'
argument-hint: 'Optionally specify the chapter file (e.g. CPlusPlus20.html) to edit'
---

# Authoring the SWIG Users Manual

## When to use
- Adding a new chapter, section, or paragraph to `Doc/Manual/*.html`
- Documenting a new feature, language target, or compiler flag
- Fixing a heading, link, or example block in the existing manual

The reference manual is hand written HTML4 Transitional. There is no Markdown / Sphinx / Doxygen layer for the user manual — edit the `.html` files directly.

## Source of truth
- `Doc/Manual/chapters` — newline separated list of chapter filenames included in the rendered single page doc.
- `Doc/Manual/index.html`, `Doc/Manual/Sections.html` — top level navigation, hand maintained.
- `Doc/Manual/Contents.html` — **generated** by `maketoc.py`; never hand edit, never commit unrelated diffs.
- `Doc/Manual/style.css` — sole authority on the colour/border styling described below.

## The default `make` target

From `Doc/Manual/`:

```bash
make            # = maketoc check generate (full build, needs htmldoc + patched-qt wkhtmltopdf)
make maketoc    # renumber headings, regenerate <!-- INDEX --> blocks, write Contents.html
make check      # tab detection (tabs fail the build) + HTML tidy on every chapter
make clean-baks # delete all *.bak files left by maketoc
```

For ordinary authoring, `make maketoc check` is what you run after every edit. `make generate` is only needed for the single page HTML and PDF artefacts and pulls in `htmldoc` and a patched-qt build of `wkhtmltopdf` — usually skip it unless explicitly producing the release docs.

What `maketoc` does, per chapter (via `makechap.py`):
1. Numbers `<H1>`–`<H5>` from the chapter's position in `chapters` (e.g. `10.2.1 ...`).
2. Adds an `<a name="...">` anchor inside each heading **only if one is not already present**.
3. Rewrites the `<!-- INDEX -->...<!-- INDEX -->` block at the top of the chapter as a `<div class="sectiontoc">` table of contents.
4. Backs up the original to `*.bak` (delete with `make clean-baks` before committing).

Side effects to be aware of:
- Tabs anywhere in a chapter break `make check` (and silently break PDF rendering). Use spaces only.
- HTML tidy runs in error only mode; tidy errors must be fixed before the build is clean. CCache.html is generated from yodl and is excluded.
- `Contents.html` is rebuilt on every `maketoc` run; it should only ever appear in a commit when chapter numbering or chapter list changes are intended.

## Heading anchors — always name them by hand

The auto generator falls back to anchors of the form `<filebase>_nn<index>` (e.g. `CPlusPlus20_nn7`). **Do not rely on these** — they shift whenever a heading is added or removed above them, silently breaking every existing link.

Always author headings with a meaningful, stable, lower snake case anchor derived from the heading title and prefixed with the chapter base name:

```html
<H1><a name="CPlusPlus20">10 SWIG and C++20</a></H1>
<H2><a name="CPlusPlus20_introduction">10.1 Introduction</a></H2>
<H3><a name="CPlusPlus20_spaceship_operator">10.2.1 Spaceship operator</a></H3>
```

Rules:
- Anchor name = `<ChapterBase>_<topic>` (snake_case after the chapter prefix). The chapter base is the filename stem (`CPlusPlus20.html` → `CPlusPlus20`).
- Put the anchor **inside** the heading element, wrapping the visible text: `<H2><a name="X">Text</a></H2>`. The older `<H2><a name="X"></a>Text</H2>` form is tolerated by `makechap.py` but breaks PDF generation under `wkhtmltopdf` — see the comment at the top of the Makefile.
- `makechap.py` keeps any non-auto anchor (anything that does not match the regex `<filebase>_nn\d+`), so once you give a heading a manual anchor it survives every future renumber.
- The numeric prefix (`10.2.1`) is regenerated by `makechap.py`; do not type it in by hand. Just write `<H3><a name="...">Spaceship operator</a></H3>` and let `make maketoc` add the number.

If you must rename an anchor, grep the entire `Doc/` tree for the old name and update every reference in the same commit — there is no automated rewriter.

## Cross references and links

- **When prose mentions another section, make it an explicit anchored link — never a vague reference.** Phrases like "see the manual section on lambda templates", "the C++14 chapter section 'Return type deduction'", or "as documented elsewhere" force the reader to grep for the target. Replace them with `<a href="...#anchor">visible text</a>` pointing at the actual heading. If the target doesn't have a stable anchor yet, add one (see "Heading anchors" above) and link to it in the same commit.
- All inter chapter links must be anchored: `href="CPlusPlus20.html#CPlusPlus20_spaceship_operator"`. A bare `href="CPlusPlus20.html"` works in the per chapter HTML but breaks the merged PDF (`linkchecker3` flags this).
- Same chapter links use just the fragment: `href="#CPlusPlus20_introduction"`.
- External links use full `https://…` URLs.

## Content `<div>` classes

Pick the class by the language of the snippet, not by what it is *about*:

| class | use for | visual |
|---|---|---|
| `code` | C / C++ source — including SWIG `.i` interface input | aqua background, monospace, framed |
| `targetlang` | code in the wrapped language target (Python, Java, Ruby, C#, …) | light green background, monospace, framed |
| `shell` | shell command lines, `swig` invocations, build output | grey background, monospace, framed |
| `diagram` | ASCII diagrams, parse tree dumps, file layout sketches | peach background, monospace, framed |
| `indent` | plain indented prose / list, no border or background | margin only |
| `table` | bordered HTML tables | — |
| `sectiontoc` | per chapter TOC — **generated** by `maketoc`, never hand written | dotted border |

Compound forms in use across the manual: `code shell`, `code targetlang`, `code diagram`, `indent code`. These combine the framing of the first class with the styling of the second; use sparingly and only where the existing chapters already do.

Pattern:

```html
<div class="code">
<pre>
%module example
int gcd(int x, int y);
</pre>
</div>

<div class="targetlang">
<pre>
import example
print(example.gcd(12, 18))
</pre>
</div>

<div class="shell">
<pre>
$ swig -python -c++ example.i
$ python -c "import example; print(example.gcd(12, 18))"
6
</pre>
</div>
```

Always wrap the snippet in `<pre>` inside the `<div>`. Tabs inside the `<pre>` will fail `make check`; expand to spaces.

Inside `<pre>` blocks, the C++ angle brackets and ampersands must be escaped (`&lt;`, `&gt;`, `&amp;`). HTML tidy in `make check` will catch most violations but not all.

Do not collapse a class or struct definition onto a single line in a code example. Put the body members on their own lines as you would in real source, so the example reads as idiomatic C++:

```html
<div class="code">
<pre>
template&lt;typename T&gt; struct Adder {
  T add(T a, T b) { return a + b; }
};
</pre>
</div>
```

## Prefer ASCII

Default to plain ASCII characters in prose: ` - ` rather than `&mdash;` for inline dashes, straight quotes rather than smart quotes, etc. The existing chapters are overwhelmingly ASCII (e.g. ` - ` outnumbers `&mdash;` ~10:1); new prose should match.

## Hyphenation

Only hyphenate compounds the C++ standard hyphenates (`using-declaration`, `type-constraint`, `requires-clause`, etc.). Drop the hyphen on everything else. See **Hyphenation** in `AGENTS.md`.

## Compatibility notes

For "first version to..." or "added in SWIG-X.Y.Z" wording:

```bash
git tag --sort=-v:refname | head -5
```

gives the actually released versions. Cross check `CHANGES` / `CHANGES.current` for the landing point of the feature. Match the wording style of nearby compatibility notes — the canonical patterns in `Doc/Manual/Library.html` are short factual statements like *"Support for X was first added in SWIG-A.B.C. Support for Y was added in SWIG-D.E.F."*. Don't editorialise about what older versions did unless verified.

Standard format:

```html
<p>
<b>Compatibility note:</b> SWIG-A.B.C is the first version to ...
</p>
```

## Validating example code

Doc comment examples (in `Lib/*.i` files and the manual) should be runnable. Quick validation loop:

```bash
mkdir -p /tmp/check && cd /tmp/check
# Write a minimal .i that mirrors the comment, plus a runme for one target
preinst-swig -c++ -java -outdir . check.i
g++ -shared -fPIC -std=c++20 -I"$(JAVA_HOME)/include" -I"$(JAVA_HOME)/include/linux" check_wrap.cxx -o libcheck.so
javac -d . *.java && LD_LIBRARY_PATH=. java -cp . check_runme
```

Before claiming the example works, also check whether an existing test under `Examples/test-suite/` already exercises the same pattern - if so, no new test is needed; reference it from the docs.

## Adding a new chapter

1. Create `Doc/Manual/<NewChapter>.html` from an existing chapter as the template — at minimum: HTML4 Transitional doctype, `<H1><a name="NewChapter">New Chapter</a></H1>`, an empty `<!-- INDEX -->` / `<!-- INDEX -->` pair, and content.
2. Append the filename to `Doc/Manual/chapters` in the position where the new chapter should be numbered. Order in this file determines the chapter number.
3. Add the chapter to `Doc/Manual/index.html` and `Doc/Manual/Sections.html` so it appears in the navigation.
4. Run `make maketoc check` and inspect `Contents.html` and the new chapter's `*.bak` to confirm only the expected lines changed.

## Editing checklist

- [ ] Manual heading anchors used everywhere (no `_nnN` left in your diff).
- [ ] Anchors prefixed with the chapter base name (`<filebase>_topic`).
- [ ] Cross document links include `#anchor`, not bare `Foo.html`.
- [ ] Snippets wrapped in the right `<div class="...">` — `code` for C/C++/SWIG input, `targetlang` for the wrapped language, `shell` for command lines, `diagram` for ASCII art.
- [ ] Angle brackets and `&` in `<pre>` blocks escaped as `&lt;`, `&gt;`, `&amp;`.
- [ ] ASCII characters preferred in prose (no `&mdash;` etc.).
- [ ] Compatibility note (if any) version verified via `git tag --sort=-v:refname` and styled to match neighbours.
- [ ] No tabs in the file (spaces only).
- [ ] `make maketoc check` clean.
- [ ] `*.bak` files removed (`make clean-baks`) before staging.
- [ ] `Contents.html` only changed if you intended a numbering or chapter list change.

## Authoritative references

- `Doc/Manual/Makefile` — full target list, build prerequisites, link checker variants
- `Doc/Manual/makechap.py` — heading regex, `_nnN` auto anchor logic
- `Doc/Manual/maketoc.py` — Contents.html regeneration
- `Doc/Manual/fixstyle.py` — stylesheet swap during single page generation
- `Doc/Manual/style.css` — ground truth for the `<div>` classes above
- `Doc/Manual/chapters` — chapter ordering
