Re: Modernizing Documentation format?

["Daniel Shahaf" <d.s@xxxxxxxxxxxxxxxxxx>]

Clinton Bunch wrote on Sat, 08 Aug 2026 06:05 +00:00:
> 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

Might want to go through Util/zyodl.vim and review at least one sample
of each syntax group defined there.

In that file syntax groups are defined by :syn-keyword, :syn-match, and
:syn-region commands.  (Normally it'd be easier to just go through the test
cases on lines 21–41, but they don't cover all syntax groups defined.)

Cheers,

Daniel
(zyodl.vim was written specifically for zsh's use of yodl, so
everything in it is things zsh's docs use.)

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