Re: mksh manpage

[Thorsten Glaser <tg%mirbsd.de@localhost>]

Hello dfjoerg,

thanks for keeping us out of the loop, so I have to discover
this message on GMane.

Joerg Sonnenberger dixit:

>I would call a man page that redefines .Dd just broken. There is no
>point in it. Depending on Mdocdate is just a bug, not a feature.

You don’t get the point, at all. The issue at hand is not defining
the Dd macro but that the manual page uses roff instructions, not
just for that. There are string definitions, if-else blocks and other
somewhat dynamic content. (In the case of paxmirabilis, even more:
the .Nm changes depending on a set register.) This is fully valid,
it’s just a corner case not handled in mdocml, which is also fully
valid.

mdocml is a tool to interpret documents that use the mdoc macro
package (and possibly s̲o̲m̲e̲ roff features) into text documents.

Manual pages are, per sé, roff documents that just happen to use,
by convention, a macropackage (nowadays mdoc, in ancient times man).
They are free to use any functionality of the roff typesetter (and
-man pages often do, for example I’ve seen them use \f to select the
font). Most manual pages are content with the functionality offered
by their macropackage, or generated from something ugly like pod or
docbook-xml, or the writer just couldn’t bother to learn roff.

The manual pages for portable software by The MirOS Project contain
code to buffer the differences between both the GNU and AT&T *roff
implementations, as well as the UCB and GNU mdoc macropackages, so
the result isn’t just legible on both (with the usual errors, such
as 「^」 being superscripted in PS/PDF output, and 「echo ’foo’」
and 「ls ‑l」 not being safe for copy-and-paste), but c̲o̲r̲r̲e̲c̲t̲ and
g̲o̲o̲d̲-̲l̲o̲o̲k̲i̲n̲g̲. It’s just not in the target group for mdocml, and this
is something I informed the mdocml people right from the start.

So an mdocml user *must* use a heuristic, like grepping for ^\.\.$,
to determine if a manual page is suitable for mdocml or not. (Or some
kind of tagging mechanism.) They also ought to provide an nroff im‐
plementation for those (Benny said something about there being none
in pkgsrc®, I wonder why).

bye,
//mirabilos
-- 
<Natureshadow> Dann mach ich git annex copy --to shore und fertig ist das
<Natureshadow> das ist ja viel cooler als ownCloud ...
<mirabilos> sag ich doch
<Natureshadow> ja wieso stimmt das denn immer was du sagst ...