swig-doc

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/:

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:

<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:

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:

<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 (<, >, &). 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++:

<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 — 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:

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:

<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:

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 <, >, &.
• 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 <div> classes above
• Doc/Manual/chapters — chapter ordering