# Swig Doc > Author and edit chapters of the SWIG Users Manual under Doc/Manual: chapter conventions, manual heading anchors, the four content `
` 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. - Skill: `swig/swig-doc` (Agent Skill) - Install (CLI): `npx skillmds@latest add swig/swig-doc` - Raw SKILL.md: https://api.skillmd.com/api/skills/swig/swig-doc/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: swig (https://skillmd.com/u/swig) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/swig/swig-doc --- # 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 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 `

`–`

` from the chapter's position in `chapters` (e.g. `10.2.1 ...`). 2. Adds an `` anchor inside each heading **only if one is not already present**. 3. Rewrites the `...` block at the top of the chapter as a `
` 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 `_nn` (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

10 SWIG and C++20

10.1 Introduction

10.2.1 Spaceship operator

``` Rules: - Anchor name = `_` (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: `

Text

`. The older `

Text

` 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 `_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 `

Spaceship operator

` 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 `visible text` 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 `
` 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 
%module example
int gcd(int x, int y);

import example
print(example.gcd(12, 18))

$ swig -python -c++ example.i
$ python -c "import example; print(example.gcd(12, 18))"
6
``` Always wrap the snippet in `
` inside the `
`. Tabs inside the `
` will fail `make check`; expand to spaces.

Inside `
` blocks, the C++ angle brackets and ampersands must be escaped (`<`, `>`, `&`). 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



template<typename T> struct Adder {
  T add(T a, T b) { return a + b; }
};




```

## Prefer ASCII

Default to plain ASCII characters in prose: ` - ` rather than `—` for inline dashes, straight quotes rather than smart quotes, etc. The existing chapters are overwhelmingly ASCII (e.g. ` - ` outnumbers `—` ~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


Compatibility note: SWIG-A.B.C is the first version to ...


```

## 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/.html` from an existing chapter as the template — at minimum: HTML4 Transitional doctype, `
New Chapter
`, an empty `` / `` 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 (`_topic`).
- [ ] Cross document links include `#anchor`, not bare `Foo.html`.
- [ ] Snippets wrapped in the right `
` — `code` for C/C++/SWIG input, `targetlang` for the wrapped language, `shell` for command lines, `diagram` for ASCII art.
- [ ] Angle brackets and `&` in `
` blocks escaped as `<`, `>`, `&`.
- [ ] ASCII characters preferred in prose (no `—` 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 `
` classes above
- `Doc/Manual/chapters` — chapter ordering