Re: Modernizing Documentation format?

On 8/8/2026 09:37, Vin Shelton wrote:
> 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.
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.
>
>  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 <http://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 <http://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 <http://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 <http://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