Re: Modernizing Documentation format?
Clinton Bunch <[email protected]>
| Newsgroups | gmane.comp.shells.zsh.devel |
|---|---|
| Message-ID | <[email protected]> |
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.