manpages is mdoc(7)

[Jan Stary]

On Apr 01 14:24:42, raimue at macports.org wrote:
> > 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.

Let me give a very short xample trying to illustrate the difference.
This is a line from the current port-load(1).

  \fBport\fR [\fB\-D\fR \fIportdir\fR]

What it says, in low-level roff typesetting commands, is this:

  Switch to bold and type "port", then witch back to roman.
  Type a left bracket, switch to bold, type "-D' and switch back to roman.
  hen switch to italics, type "portdir", swith back to roman,
  and type a right bracket.

An equivaent in mdoc(7) is this:

  .Nm
  .Op Fl D Ar portdir

which says, describing clearly the semantics:

  The utility takes an optional flag 'D' with a 'portdir' argument.

That's not "equally bad", that fundamentally better.
That's why I offered to rewrite the manpages into mdoc(7).

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

It's not necessarily a problem, but it is
a disadvantage with respect to having a simple manpage.1

> I fully agree that XSL is
> horrendous, but we do not maintain this XSL, it is provided by DocBook.

How is "it's horrendous, but we did not write it"
a reason to use horrendous software?

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

They do _not_ use roff. Thats the whole point.
There is not a single roff command in the entirety
of e.g. the OpenBSD base system.

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

I care. The manpage formatter cares,
and has to _parse_ 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?

Of course not. But that does not make shitty html page equal
to a good html page _even_if_they_looked_almost_the_same in the
browser (to stick to your analogy which does not really work).

	Jan