Re: Modernizing Documentation format?

I haven't evaluated the patch at all, but FWIW, I think tying ourselves to
yodl is a poor choice. Incorporating yodl into zsh would be an alternative,
but not better than sphinx, IMO.

 Vin Shelton

On Sat, Aug 8, 2026 at 6:06 AM Clinton Bunch <[email protected]> wrote:

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

-- 
Never for money, always for love