docs: migrate remaining trees + man-page generation (Phase 2+3 of N)

[gburd]

Phase 2 + 3 of the documentation modernization (Phase 1 landed in #119). Everything is confined to docs-src/; docs/ and the gitignored docs-build/ are untouched.

Phase 2 — migrate the remaining doc trees

Ran the reverse-DocBook extract.py + the verify.py no-loss gate on every tree. All 13 trees pass: >=99.98% mean word retention, 0 outliers, 0 hard drops.

tree	pages	retention	outliers	hard drops
api/c	470	100.00%	0	0
api/stl	322	100.00%	0	0
guides/programmer_reference	203	99.98%	0	0
guides/upgrading	180	100.00%	0	0
guides/installation	101	99.99%	0	0
guides/porting	16	100.00%	0	0
guides/gsg (C)	37	100.00%	0	0
guides/gsg_txn (C)	38	100.00%	0	0
guides/gsg_db_rep (C)	26	100.00%	0	0
guides/collections	37	99.98%	0	0
guides/bdb-sql	30	100.00%	0	0
guides/articles	2	100.00%	0	0

Pipeline changes (shared, regression-safe)

The extractor and gate needed generalizing for the chaptered guides. The C API tree was re-verified after every change and went from 99.98% -> 100.00%, so no regression:

• extract.py: body-level fallback for the couple of div-less guide article pages (embedded/witold); source: front-matter derived from the SRC arg.
• verify.py: fixed three measurement bugs that were undercounting retention (the extracted content was correct all along) — the TAG regex now matches only real HTML tags (a bare \< in prose like operator\<= no longer swallows the following words); gfm punctuation escapes (\_ \< \>) are neutralized before tag-stripping; the code-fence counter now sees fences after list markers (1. \`` c). Added OLD/NEW dir args + --selfcheck`.
• migrate_tree.py: per-tree driver (extract + _meta.toml reading-order from the index TOC + image copy).
• fix_xrefs.py: remaps ~3000 cross-tree links from the old docs/ layout to the new docs-src/ layout (unmigrated CXX/TCL links intentionally left pointing at the archived tree).

Layout: API trees -> docs-src/api/{c,stl}/; guides -> docs-src/guides/<name>/, each with an _meta.toml and an img/ for preserved images. gsg/gsg_txn/gsg_db_rep migrated from their C sub-variant (core-engine focus).

Phase 3 — man pages

Implemented build_man() in build.py. Every C/STL refentry .md -> a section-3 man page via pandoc + _templates/man.tmpl, mapping the API schema (Description/Parameters/Errors/Class/See Also) to man sections (NAME/SYNOPSIS/DESCRIPTION/.SH ...). Plus one synthesized libdb.3 overview (NAME + a library DESCRIPTION — embedded, ACID, WAL, 4 access methods, multi-process — + API GROUPS + SEE ALSO, all pulled from existing content).

• 787 *.3 generated -> docs-build/man/man3/.
• mandoc -Tlint: 0 ERRORS across all 785 files. Remaining: 80 WARNINGs (pandoc empty-autolink .UR/.MT artifacts, inherent) + 773 STYLE (mostly lowercase page-name titles, conventional for library functions).
• libdb.3 renders sensibly under mandoc.

API coverage (measure-only; the CI gate is phase 5)

• 100% of the documented public C/STL refentry pages became a man page.
• 86.6% (350/404) of the raw db.h method-pointer + ext_prot.in function surface name-matches a page (via man_coverage.py). The ~13% "unmatched" is not missing docs: 25 are get_* getters documented on their set_* page, ~27 are paired setters / *_stat_print variants / getters documented on a shared page. Only 2 are genuinely undocumented in the source: db_env_set_func_assert, db_env_set_win_security (Windows/debug setup functions Oracle never gave a page).

Deferred: docs/csharp (38 MB) + docs/java (12 MB)

Assessed, deliberately not migrated. Neither is DocBook, so the extractor doesn't apply: csharp is a compiled Sandcastle/MS-Help-Viewer tree (.chm/.aspx/JS, 2457 files, 1 real HTML); java is standard Javadoc (525 files). Both are language-binding docs, enormous, and lower-value for the core C engine. A future phase can regenerate them from source with their native doc tools.

What later phases still need

• Phase 4 (PDF): build_pdf() stub left intact — pandoc per book + shared LaTeX header.
• Phase 5 (CI): docs.yml wiring verify.py per tree + man_coverage.py as hard gates, plus spelling/link/man-lint.
• Phase 6 (Publish): gh-pages from docs-build/html, update the landing page.

Validation

• cd docs-src && python3 build.py -> 1463 HTML + 787 man, 0 errors, version 5.3.33 throughout.
• verify.py passes on all 13 trees (table above); C API tree re-verified at 100.00% after every extractor change.
• mandoc -Tlint: 0 errors on all 785 *.3.
• docs/ untouched; docs-build/ stays gitignored.

[github-actions]

Coccinelle convention checks

No new violations. ✅

Resolved since baseline (2) -- update dist/cocci/baseline.txt to lock these in.

rule_mutex_unbalanced|MUTEX_UNBALANCED|src/crypto/mersenne/mt19937db.c|return (ret);
rule_mutex_unbalanced|MUTEX_UNBALANCED|src/mp/mp_register.c|return (ret);

[github-actions]

ABI diff vs v5.3.33 (libabigail — authoritative)

Removed exported symbols (nm -D, _NNNN version suffix normalized)

None.

---

Advisory: libabigail/nm is the authoritative binary-ABI check; Coccinelle is complementary source-level early warning. See dist/cocci/README.md.