RE: Re: Modernizing Documentation format?

[zeurkous@xxxxxxxxxxxxxxx]

On Thu, 21 Aug 2025 12:30:24 -0500, Clinton Bunch <cdb_zsh@xxxxxxxxxxx> wrote:
> nroff is an adaptation of troff,

Wrong, it's the other way around.

> Given the number of packages I've seen build their man pages with=20
> sphinx, I think pretty good.

Given the number of people that use their hands to wipe their butts
after done deeds, I think pretty good.

> HTML is not painful and it is essential to modern documentation.

*What*?

> The FAQ

Can you confirm that this wouldn't be feasible to generate with any
of roff's macro packages? (This need not be a show-stopper anyhow,
but it's a valid consideration.)

> The FAQ.=C2=A0 And again, groff (whether it's ms, man, or mandoc) does no=
> t=20
> produce good HTML

mandoc(1) does. (and it's not groff(1)). Did you even try it?

> and that is important for a modern project.

s/modern/retarded/, but YMMV :)

> I've=20
> actually had to fix groff HTML output to fit a simple modern CSS design=20
> that will also look good on a text based web browser. Our own intro.ms.

Me believes you.

> So is python.=C2=A0 I'm not dead set on rst, but it's a really good=20
> candidate.=C2=A0 I'm willing to change my mind on mandoc if you can find =
> a=20
> processor better than groff to translate mandoc into non man format=20
> documentation. (And I don't mean linux.die.net)

Again: mandoc(1) is not mdoc(7)! mandoc(1) is a roff replacement w/
the rendering of manual pages as its primary goal (although more and
more general roff stuff has sneaked in). mdoc(7) is the macro set a sane
manual page writer would use these days, but that's actually orthogonal.

> As far as your concern that moving to rst will put us in the same boat=20
> as YODL, when fundamental projects like BIND

Influential? Sure. Historically significant? Absolutely. Fundamental? No
longer. People have largely moved on.

> use it and multiple=20
> document processors support it, I find it hard to believe that there=20
> won't be a considerable overlap period to transition to the next format=20
> if python dies and takes rst with it.=C2=A0

That next format will likely be mdoc(7). Why? 'cause it works!

> The yodl processor appears to=
> =20
> have been a one person project without a large community around it.=C2=A0=
> =20

Granted. Me's not impressed w/ it.

        --zeurkous.

-- 
Friggin' Machines!