Re: Modernizing Documentation format?

[Clinton Bunch <cdbunch@xxxxxxxxxxx>]

On 8/21/2025 06:12, Marc Chantreux wrote:
> hello Clinton,
>
> On Mon, Aug 18, 2025 at 05:58:22PM -0500, Clinton Bunch wrote:
> > I have gotten some ideas for converting our YODL (and Intro.ms) to
> > reStructuredText which requires some python modules (sphinx, rst2pdf)
> This feels weird to me so I share about it
>
> * the only person using rst around me just hate it :)
All documentation formats are horrible, because writing documentation is 
horrible. :)
> * You don't need you system to support html and pdf: roff does it for
>    you (also postscript)
roff produces horrible HTML with no styling capability.  It's a 
typesetter not a documentation format.  It is meant for printed pages.
> * don't you think the natural format for a unix shell should be the unix
>    typesetting system?
No.  Because typesetting is about presentation, not documentation.
> * will we loose semantic using RST?
RST has much richer semantics than roff.
> also: installing the whole python thing just to fix typos could be a bit
> boring.
>
> I started to use [mandoc](https://mandoc.bsd.lv/)
> (from the openBSD project, with people related
> to GNU troff project) and I really like the fact that:
>
> * the troff syntax is simple, yet powerful enough and extendable
> * the mandoc requests add semantic to everything we need (flags,
>    subcommands, parameters, ...) which appears in output formats
>    (give a look at https://man.openbsd.org/)
We need a lot more than flags, subcommands, and parameters.
> > Sphinx will generate man, html, pdf, and texi formats from rst
> which is complete redundant with man format.
Not all documentation is a man page.
> > rst is not too step of a learning curve and is the de facto standard for
> > python documentation.
> mandoc is weird in the first hours but it's worth it because now I
> realize how simple manpages are simple to read. plus: troff is blazing
> fast and I started to use it instead of latex.
I've been reading man pages for more than three decades,  they lack 
internal cross referencing and indexes, it's hard to find the specific 
information you need quickly.  Especially in a large man page like a shell.
> > Any interest in seeing if I can get something usable converting the format
> > of record?
> removing yodl is a good thing (thanks for coming with this topic) but I
> have the feeling you're just replacing one problem with another one.
>
> regards