manpages is mdoc(7)

[Rainer Müller]

On 2017-04-01 10:28, Jan Stary wrote:
> But the age of the asciidoc rewrite has nothing to do with it, right?
> 
> I'm not hoping to change the course here,
> but what were the manpages written in before this?
> porthier.7 is in mdoc(7), with .Dd June 1, 2007
> - were all the base manpages im mdoc(7) before?

Back when the NewHelpSystem [1] was started, the man pages were in roff
format and rarely received updates. No idea if it was mdoc(7), because
for someone not knowing the syntax at all, it looks equally bad.

> Now that they are in asciidoc,
> 
>  * the actual man(7)page needs to be generated
>  * the generating requires horrendous xsl transformations

Why are generated man pages a problem? I fully agree that XSL is
horrendous, but we do not maintain this XSL, it is provided by DocBook.

Many open source projects generate their man pages from a high-level
markup language. I am only aware of the various *BSD systems that keep
writing roff directly.

>  * both the asciidoc source and the generated man(7) need to be in the repo
>  * the result is this:

[...]

> That's right: let's start in each and every manpage
> with a workaround to a 2009 bug in docbook-xsl.

Who cares? Nobody looks at the roff input...

Do you also look at generated HTML in your browser and complain about
all the hacks and workarounds that are necessary for certain browsers?

Rainer

[1] https://trac.macports.org/wiki/NewHelpSystem