On Apr 01 14:24:42, rai...@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
