I actually considered re-implementing a YODL parser, but one would we really want to own that code? and two, YODL is a very niche metadoc language with little editing tooling and a learning curve. This makes it a little intimidating for new contributors. Granted rST has a learning curve and is ugly, but thousands of people already know it. And there isn't much out there that gives us our 3 core documentation formats: man, info, and HTML.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 <cdb_zsh@xxxxxxxxxxx> 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