Hi Branden - Thanks. After reading your mail, I switched to using quotes
and roman for the few instances of inline "typewriter" in my problematic
(makeindex) man page. So that's fine. But I can't help but make just a
few more remarks ...
So, what happens to text marked up [with .CW] when it's rendered in
nroff mode? [...]
What's the _right_ thing to do? Depends on the document.
Agreed, and I think that's an important point to make in the
documentation around this monospaced font stuff.
Although, for man pages, my personal opinion is that nroff output is
most often best served by "nothing". I used quoting for makeindex
because there are only a couple of instances. But it is not uncommon for
man pages to switch back and forth between code and text multiple times
in a single sentence, let alone paragraph.
You mentioned a quote macro for the bash man page. Personally I would
find the bash man page (the terminal version) next to unreadable if
every single tiny code fragment had quotes around it. (Aside: It's one
of the things I dislike most about Info output, all those darn quotes.)
Yes, it's technically "correct" to distinguish, but usually it is
obvious from context, and wading through all the quote chars to get to
the context is a drag on what few brain cells I still have.
eschewing
.I this
kind of emphasis in favor of \fIthis\fP.
It doesn't seem surprising. For single words or short texts, inline font
switches make the source more readable. I, for one, had no idea that .I
was so different (in the implementation) than \fI, even after 40 years
of writing and revising man pages. All I knew was that they both produce
italics. Nothing to do with being lower level.
But, on terminals, the same "right thing" would happen with \fQ, \fJ, or
\f(ZZ, so that observation doesn't feel weighty to me. There are lots
But there aren't lots of existing man pages that use \f<randomletter>,
while there are that use \fC. But whatever, you've made your stance
clear.
groff_man_style(7) adds concrete examples addressing issues about which
users have complained:
I have two other suggestions for groff_man_style (sorry if they are
there, I didn't see them, but didn't closely read that dense 20 page
document), though they may be too draconian for you. Both for terminal
output only, not typeset:
1) disable filling (.ad l / .na, I think).
2) disable hyphenation (.nh, I think), and
(I won't be surprised if you tell me there are new and/or better ways to
specify these things, those are just what have worked for me.)
I do this for myself because 1) the "justification" of output on
terminals makes the output far less readable (IMHO), what with the
resulting zillions of spaces everywhere. Terminals are not made for
justified text. Ragged right is so much clearer.
2) hyphenation creates ambiguity, breaks copy/paste of code, and is
conventionally not used with ragged-right.
Granted these are system decisions, not individual man page decisions --
I don't advocate putting these commands in individual man pages. (I put
them into my site-tmac/* files.) But still, mentioning them for you to
do with as you will.
Finally, on history:
[2] Maybe "presumption" would be a better term than "mandate".
Yes. There have plenty of GNU packages that didn't have (or still don't
have) Texinfo manuals. Bash was one, for many years. As far as I know,
rms never ousted a package from GNU for failing to have a Texinfo manual,
even though they are "supposed to".
* As I understand it, the reason for GNU's selection of Texinfo as its
official documentation format was because it was capable of targeting
multiple output formats using a single master document,
Yes.
I've gotten the impression that a contributing factor was
that the syntax of Brian Reid's Scribe was thought important to clone.
The idea was never to "clone" Scribe, though that's where @ as escape
character came from. The crucial point was to separate content from
formatting. If you don't know it already, see the History section in the
Texinfo manual for a few brief remarks.
* That's exactly how groff works, too. But I guess not syntactically
resembling Scribe led to its neglect or derogation.
Saying the difference between *roff and TeX is merely "syntactic" seems
a bit disingenous :). They are fundamentally different. But anyway,
1) syntax is important. For me and plenty of others I know, those
pervasive leading periods make roff source rather hard to read. Of
course, that syntax could hardly have been anything else at the time of
invention, being inherited from runoff, etc.
2) But I don't think syntax was the main factor for rms to create
Texinfo. He disliked (dislikes) man pages, especially of that time,
because while they covered the single function or command in a
reference-material sort of way (granted this is why many people *prefer*
them), they rarely explained how to use things together, or gave
examples, tutorials or other non-reference material. He wanted GNU
documentation to be better. How well that worked out in practice is
debatable, but that was the idea.
Although theoretically one can argue that those complaints are about man
pages, not roff, I don't recall much if any discussion of non-man page
documentation written in roff. (Even today, they are barely known by the
general programmer, as far as I've seen. I myself don't think I could
name three such non-man page roff manuals, without looking them up.)
3) As I recall, there was no free implementation of roff until James
Clark started GNU groff, as described in the groff manual :). Texinfo
was developed a number of years before that. TeX was always free
software (and predates everything else discussed here).
At any rate, thanks for all the advice and experience about this
(seemingly :) tiny issue. --best, karl.
