Re: Modernizing Documentation format?

[Clinton Bunch <cdb_zsh@xxxxxxxxxxx>]

On 8/19/2025 2:40 PM, dana wrote:
> 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)
I also had to build it on EL (8, IIRC) and it was a pain.
> 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
The only place I've noticed is in the TOC to the FAQ for the text 
version.  Have I just not seen the others?
> imo rst's syntax is awful, but it's what everybody uses so oh well
I have yet to see a meta-doc format who's syntax I didn't think was 
awful. :)
> dana