Re: Modernizing Documentation format?

[Clinton Bunch <cdb_zsh@xxxxxxxxxxx>]

The Doc conversion project has reached a point where all rST and output 
formats have been generated, but now the output needs to be checked for 
artifacts.  A sample tarball is available at 
http://zsh.clintonbunch.name/zsh-docs-rst-preview-20260808.tar.xz

README found in the tarball:

Zsh documentation preview (Yodl → rST / Sphinx)
================================================

As of:  master  9a9af70296bfbdb5be1d9521415d87fd4accaa34
        (9a9af7029  55021: prevent segfault upon "typeset -U" …)
Zsh version string:  5.9.999.3-test
Date:  2026-08-08

This is an experimental conversion of the zsh manual, intro_zsh tutorial,
and FAQ.  rST here is conversion output, not yet the format of truth.
Please report artifacts; do not treat this tree as a parallel source.

What is in this tarball
-----------------------

preview/     Built products (no html-web / Furo theme)

  html/                      Distro HTML (basic theme): manual + 
intro_zsh + FAQ
  intro_zsh.html             Single-file intro_zsh
  intro_zsh.fallback.a4.pdf  intro_zsh PDF (rst2pdf fallback A4)
  faq-html/                  Isolated multipage FAQ
  faq.txt                    Concatenated FAQ plaintext (Usenet-style)
  man/*.1                    Man pages
  texinfo/zsh.texi           Texinfo
  texinfo/zsh.info           Info (makeinfo --no-split)

rebuild/     Enough to rebuild without Yodl

  source/                    Generated rST (Zsh/, intro_zsh/, faq/)
  sphinx-config/             Sphinx conf, extensions, static assets
  sphinx.mk                  Standalone makefile

Rebuild (optional)
------------------

  cd rebuild
  python3 -m venv .venv
  .venv/bin/pip install -r sphinx-config/requirements.txt
  make -f sphinx.mk html man info intro_zsh.html faq.html faq.txt

html-web (Furo) is intentionally omitted from this preview.

How to report artifacts
-----------------------

Please include:

  1. Artifact (what looks wrong)
  2. Path or URL + nearby heading
  3. Expected vs actual (compare to current Yodl man/info/FAQ if useful)
  4. A guess at the bucket below

Buckets
-------

  Yodl pipeline     Same glitch in many chapters (lists, tt, example,
                    :var:, quotes).  Fix converter once.

  rST / Yodl source One chapter or FAQ question wrong (nesting, missing
                    label, typo).  Fix upstream .yo and reconvert.

  Sphinx / custom   Theme, toctree, man-only Overview, Info <2> node
                    names, :zshsectref: bridge.

  Live with         Not bit-identical to yodl2html/yodl2txt; Sphinx Info
                    node uniquification; FAQ toctree vs hand-written TOC.

Known conversion notes (not a complete list)
--------------------------------------------

  - FAQ.yo is still the FAQ source; source/faq/ is generated.
  - intro_zsh comes from Doc/intro.ms via a separate converter.
  - :zshsectref: is a deprecated Yodl sectref/subref bridge.
  - faq.txt will not match classic yodl2txt character-for-character.