RE: Re: Modernizing Documentation format?

[zeurkous@xxxxxxxxxxxxxxx]

On Thu, 21 Aug 2025 13:12:48 +0200, Marc Chantreux <mc@xxxxxxxxxx> wrote:
> On Mon, Aug 18, 2025 at 05:58:22PM -0500, Clinton Bunch wrote:
> * You don't need you system to support html and pdf: roff does it for
>   you (also postscript)
> * don't you think the natural format for a unix shell should be the unix
>   typesetting system?

Hear, hear!

> 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/)

While not entirely pleased w/ the design of mandoc(1) from a systems
point of view, me experiences w/ it from an OpenBSD luser's point of
view have been fairly positive.

>> Sphinx will generate man, html, pdf, and texi formats from rst
>
> which is complete redundant with man format.

Yeah.

> mandoc is weird in the first hours but it's worth it because now I
> realize how simple manpages are simple to read.

You mean s/mandoc/mdoc/, right? mdoc(7) predates mandoc(1).

Me's used mdoc(7) since the moment me became aware of its existence,
and me never looked back. (Although there are warts.)

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

A decent summary, me'd say.

        --zeurkous.

-- 
Friggin' Machines!