Zsh Mailing List Archive
Messages sorted by: Reverse Date, Date, Thread, Author

Re: Modernizing Documentation format?



On Mon 18 Aug 2025, at 17:58, Clinton Bunch wrote:
> I have gotten some ideas for converting our YODL (and Intro.ms) to
> reStructuredText which requires some python modules (sphinx, rst2pdf) to
> generate the output formats.  Python seems like a much more common
> dependency than yodl, and I think we may be the last project using the
> format.  Sphinx will generate man, html, pdf, and texi formats from
> rst.  rst is not too step of a learning curve and is the de facto
> standard for python documentation.
>
> Any interest in seeing if I can get something usable converting the
> format of record?

i looked into this myself, briefly, a few months ago

i think you're right that zsh is the last project that uses yodl,
besides the author's own. certainly the only one with a large user base

the dependency on it has been a long-time annoyance on macos because
homebrew doesn't package it (due to issues with one of its own
dependencies, another of the author's projects, icmake)

anyway the main concern i identified is maintaining the functionality of
the macros that allow for things like different wording depending on the
export format. they're fairly simple so i don't think it's a major
technical issue. but i didn't actually try to re-implement them

imo rst's syntax is awful, but it's what everybody uses so oh well

dana




Messages sorted by: Reverse Date, Date, Thread, Author