Re: man(7), hyphen, and minus

[Russ Allbery]

Just a quick reply on one part of this with more to come later.

"G. Branden Robinson" <g.branden.robinson@gmail.com> writes:

> Oh, I know.  I've seen Pod::Man's preamble.  I think what distressed me
> originally about it was that, like docbook-to-man, it seemed to make
> man(7) seem like a write-only language.

This bothers me too, and I made some choices for ease of implementation
rather than readability of output.  (I generally like to prioritize
readability of output; my static site generator cares more about the
readability of the HTML than any sane person probably should.)

The biggest loss there is that I always use font escapes (with elaborate
workarounds for font strangeness in both Solaris nroff and in groff)
rather than what any sane human would do, which is use .B, .BI, .BR, etc.
The specific problem that I have is that I was trying to avoid doing
whole-tree transformations on the POD parse tree, so the transformation is
done locally.  In other words, in something like B<< bold I<italic> >>, I
first get a function invocation of cmd_i with text "italic", and then an
invocation of cmd_b with text "bold <whatever I turned italic into>".
It's a bit tricky to turn that into "\fBbold \fBIitalic\fR" but it doesn't
require any state tracking.  But if I transform I<italic> into
".I italic", life felt rather complicated and I wasn't sure if I was going
to be able to figure out where to go from there, particularly because
there's a bunch of weird complexity about quote escaping required to use
the macros.

I'm also trying to stay very portable and for a long time I knew there
were a bunch of proprietary implementations out there that did random
things (never mind Solaris, what about HP-UX which does some other weird
things).  So for example I don't use .EE/.EX and instead roll my own,
which is kind of sad, let alone stuff like .TQ, .UR, or .SY.

-- 
Russ Allbery (eagle@eyrie.org)             <https://www.eyrie.org/~eagle/>