Hi Karl, At 2026-04-27T14:18:08-0600, Karl Berry wrote: > 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.
Cool. Is this maintained some place on the Web I can check it out?
Incidentally, I wasn't trying to persuade you of anything but the
non-portability of what the document was attempting. While I have style
preferences and have tried to document in groff_man_style(7) what
appear to me as best practices from clearly well-composed man pages,
preferences _do_ differ. I'd say much of the history of the
man(7) package's growth--even before groff--partly in macros but
especially in registers and a bit in strings, has been driven by "house
styles" that, rightly or wrongly, found McIlroy's man(7) of Seventh
Edition Unix (1979) limiting.
> So that's fine. But I can't help but make just a few more remarks ...
I know that temptation well, and seldom resist it... ;-)
> 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.
I agree, and am unsure that it is a good idea. Apart from the
provocative and sadistic practice of expecting the reader to distinguish
spaces in Times from spaces in Courier--a prospect that seems to leave
mdoc(7) partisans either unmoved or downright excited--I feel that too
many man page authors expect typeface changes and symbols borrowed from
Backus-Naur form to accomplish what their craftsmanship of English prose
doesn't.
I further observe that man page authors who seem most reliant on
frequent changes of font or thrusting angle brackets into the face of
the reader also, when tasked with drafting a Unix command or C function
synopsis, which have their own little domain-specific markup languages,
exhibit underwhelming competence with those as well.
> 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.
Not every single tiny code fragment in bash(1) _does_ have quotes around
it. Checking Bash 5.3's page real quick:
$ grep '\.QN*' $(man -w bash) | wc -l
159
$ wc -l $(man -w bash)
13495 /home/branden/share/man/man1/bash.1
...so a little over 1% of its input lines employ one of its page-local
macro calls. I admit, that's higher than I expected.
On the other hand,
$ grep '\.\([LP]*P\>\|S[HS]\)' $(man -w bash) | wc -l
500
There are fully 500 paragraphs in the document, so you're going to hit
one of these quotation mark pairs only about once every 3 paragraphs.
That doesn't feel too bad to my belly. It's nothing like what
groff_mdoc(7) puts you through with Courier and bold in groff 1.23.0 and
earlier.
> (Aside: It's one of the things I dislike most about Info output, all
> those darn quotes.)
The profusion of them mildly annoys me. Its cheerful use of
apostrophes/single quotes to quote the same _really_ annoys me. I think
more recent versions of Texinfo have surmounted the problem by going
UTF-8. But to make sure I don't carelessly adopt a too-new feature in
groff's Texinfo manual, I keep a pretty old version on my system.
> 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.
I agree, which is why I recommend quotation only for multi-word inline
literals and for disambiguation with English.
groff_diff(7):
Conditional expressions
More conditions can be tested with the “if” and ie requests, as
well as the new “while” request.
> 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 guess there's no accounting for taste. ;-) Even to the extent one
could call me a champion of or advocate for *roff, I don't find the
foregoing to be appealing markup.
If your target audience doesn't use pre-groff troffs, you don't need the
foregoing syntax, and can use \f[I]this\f[P] syntax.
> 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.
Well, `I` is a macro. If you fire up a troff without loading a macro
package, you'll find that it does nothing.
The `\f` escape sequence and `ft` request are built in to the formatter.
> 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.
Yes, certainly! I concede that, but on a terminal, it _fails to perform
a change of typeface just as the others would fail_.
> But whatever, you've made your stance clear.
I'm not sure I have. A repeated problem I face when people complain
about this diagnostic is how often they don't seem to realize that groff
is not suddenly deciding to not do something it was doing before.
They're shooting the messenger: groff was _always_ failing to change the
typeface when a nonexistent one was selected, and it is only since groff
1.23.0 that it has started _telling_ the user of the failure.
Background for the (morbidly?) curious:
https://github.com/Perl/perl5/issues/21239#issuecomment-1773706021
https://github.com/rra/podlators/issues/43
I get it, kind of. There used to be a large faction of C programmers
who deeply resented lint(1) having anything to say about their code,
like some supercilious twit trying to take points off of their bro
scoreboard. If it ran okay on a PDP-11 (or, later, a VAX) for a user
who made all the same assumptions as the author, then why's it kicking
up such a fuss?
I can't improve on an old classic...
http://www.literateprogramming.com/ten-commandments.pdf
> 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.)
These are recurring issues, and they _are_ (in groff's man(7)
implementation) configurable at rendering time, but most of the people
who write the most passionately about them seem to be unaware of that.
Practices among Unix vendors split a long time ago, and so even people
who wouldn't be animated about the issue from first esthetic or
typographical principles show up with guns blazing because groff doesn't
conform to the configuration used by the old *nix box they grew up on
and which manifested the only way things were ever done. (It didn't.)
Here's some stuff from our man pages you might have overlooked.
groff_man(7):
Options
The following groff options set registers (with -r) and strings
(with -d) recognized and used by the man macro package. To ensure
rendering consistent with output device capabilities and reader
preferences, man pages should never manipulate them.
-dAD=adjustment‐mode
Set line adjustment to adjustment‐mode, which is typically
“b” for adjustment to both margins (the default), or “l”
for left alignment (ragged right margin). Any valid
argument to groff’s “ad” request may be used; see
groff(7).
...
-rHY=0 Disable automatic hyphenation. Normally, it is
enabled (1). The hyphenation mode is determined by the
groff locale; see section “Localization“ of groff(7).
Authors
... Larry Kollar ⟨[email protected]⟩ added the FT, HY, and SN
registers; the HF string; and the PT and BT macros in groff 1.19
(2003). ... G. Branden Robinson ⟨[email protected]⟩
implemented the AD and MF strings; CS, CT, and U registers; and the
MR macro for groff 1.23 (2023), ...
groff_man_style(7):
Files
...
/usr/local/share/groff/site-tmac/man.local
Put site‐local changes and customizations into this file.
.\" Put only one space after the end of a sentence.
.ss 12 0 \" See groff(7).
.\" Keep pages narrow even on wide terminals.
.if n .if \n[LL]>80n .nr LL 80n
You might add:
.ds AD l
.nr HY 0
...to manifest your preferences in that file. (On a Debian-based
system, it lives at "/etc/groff/man.local".)
Further background, with a historical study in the third link:
https://savannah.gnu.org/bugs/?53781
https://cgit.git.savannah.gnu.org/cgit/groff.git/commit/?id=e7094b209f0f39fc16de687f116ea9a9c1ba0364
https://lists.gnu.org/archive/html/groff/2025-05/msg00001.html
https://savannah.gnu.org/bugs/?67363
> 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.
I have no objection to you configuring your system to present man pages
in a way that pleases you. However, because of the history of multi-way
conflict between (1) macro package support for configuration of these
parameters; (2) OS/troff vendor style mandates; (3) software project
style mandates;[1] and (4) individual user preferences, it has proven
tricky to get all of this working reliably.
So I must warn you--putting these:
> 1) disable filling (.ad l / .na, I think).
> 2) disable hyphenation (.nh, I think), and
...in your "man.local" might work, but is not supported. Much depends
on how hard a man(7) document tries to impose its own preferences. And,
to be fair, for _brief_ stretches of text, disabling adjustment can make
sense. I don't know of a use case where trying to disable hyphenation
is anything less than rude. In groff man(7), macros that know that
hyphenation will be inappropriate shut it off themselves. In other
cases, the author is simply lazy or doesn't want to be bothered to mark
unhyphenable literals with a prefixed `\%` or to specify hyphenation
exception words with the `hw` request (better supported in the
forthcoming groff 1.25[2]).
Please use the string and register settings documented above.
> 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.
Huh! News to me.
> 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".
Always good to hear of one fewer capital offense. ;-P
> * 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.
I believe I've read the material before. The thing is, *roff doesn't
foreclose that. _Nearly_ all formatter features are concerned with
"presentation" as opposed to semantics because the formatter's job is to
drive a typesetter.
It is the role of macro packages, in *roff just as in TeX, to manifest a
discipline of separation between presentation and semantics, where that
is valuable and appropriate to the package's mission.
That's one of the areas where mdoc(7) shines. Unfortunately, the
presentation/semantics dichotomy was only one fish that the people
directing/funding mdoc had in mind to fry. For one thing, the emphasis
on semantics led to a proliferation of macro names--the language has a
milder case of the ailment that fatally crippled DocBook (which I think
ended up with on the order of 400 tags/elements). For another, because
the mdoc initiative started when the blood between the Berkeley CSRG and
AT&T USG (later USL) was already bad, I _surmise_ that a goal of the
mdoc(7) macro language was to be droppable-in-place onto some other
formatting system to be designed later. That's the only explanation I
can think of compelling enough to drive its implementation of a macro
expansion system, in *roff, _on top of *roff_. Yes, in *roff there are
occasional annoyances like having to type `\c`, but they are truly
uncommon. mdoc(7) solves the same problem with a lot of rules about how
to spell adjacent pieces of punctuation one-by-one, having them
specially recognized, and contriving a business of "parsed" vs.
"callable" macros, a distinction as unintelligible to people trained in
parser theory as to those who aren't.
A drawback to mdoc(7) is that, having learned it, you'll find that
little of your knowledge "ports" to composition of *roff documents using
any other macro package.
*** BEGIN POLITICAL DIGRESSION ***
I surmise again that this trait was seen as a plus by certain
luminaries in the CSRG, unknown to me, who wanted to see a stake driven
through troff's heart--because they disliked it as software, because
AT&T demanded a king's ransom to license it, or both.
If I'm right, it must have been with some horror that these luminaries
greeted the advent of James Clark's groff. Highly compatible. You
really could drop mdoc right on top of it; people did so at once. Free
software. (This is before the BSD/GNU "schism".) The CSRG embraced
groff as readily as they did GCC, G++ (once separate), GDB, and GAS.
https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/usr.bin/groff
https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/usr.bin/gcc
https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/usr.bin/gdb
https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/usr.bin/g++
https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/usr.bin/gas
Embraced?
Well, almost--it seems. mandoc(1) maintainer Ingo Schwarze, a definite
mdoc(7) advocate, has shared more than once the fascinating story that
Cynthia Livingston offered to throw over some pretzel-riffic contortions
into which mdoc's tmac files twisted themselves to get along with the
limitations of AT&T troff. With groff available, she reportedly said to
management, that stuff could be thrown over and mdoc improved in several
respects in usability and maintainability.
The answer from (some subset of) CSRG luminaries?
"No."
Whoever the unnamed party was, I suspect played a major role in
_creating_--I believe consciously--the BSD/GNU schism over what "free
software" means. And that disagreement, I conjecture, arose because the
writing was on the wall that the CSRG was going to be winding down
someday. Jobs were going to go away at the University, and had to be
found elsewhere. Berkeley Unix was going to have to pay for itself.
Well, Bill Joy had made a bundle on commercializing BSD at Sun, and even
if one were only half as clever as he, one rightfully deserved half of
his total career compensation. The test of one's entrepreneurial acumen
was how to get it. I think the plan was simple and obvious, and
copyleft was a great big problem right in the middle of it. One thing
AT&T had made certain of was to leave plenty of room to undercut them on
price.
But, jeez, if the GNU guys had trouble coming up with a kernel, they
sure did have one heck of a nice toolchain. One might need to be more
than half as clever as Bill Joy to reimplement the whole thing as "truly
free" (not copyleft) software.
I guess, at this point, folks' self-confidence failed to match their
pecuniary ambitions. (Many years Chris Lattner showed up and proved to
possess the snazziest black turtleneck ever, save one only.)
Thus was the myth of "true freedom" in software licensing born. If I
cannot extract rent from my neighbor, I am not truly free. I can't say
that this crop didn't find fertile soil in the Bay Area. Eric Raymond
might have been the most prominent in his time, but was neither the
first nor the last to find concord between entrepreneurial capitalistic
glibertarianism and the derogation of the communitarian copyleft idea.
Free Software advocates did admittedly have a habit of advocating for
the freedom of every computer user to study, share and improve software.
The Open Source movement had a response.
"Let's not do that."
So while I would guess that schism would have occurred anyway, because
one should not attribute to conspiracy that which is adequately
explained by fiscal incentive$, I've twigged that it had played out
already within the CSRG.
There were some people who aimed to get rich or die tryin', and then
there were more or less well-adjusted human beings.
As we've seen repeatedly over the past century, a politics that is
"neither left nor right" consistently forms the veneer of the hard
right.[2][3] Another reliable principle is that, in any forum where you
find a person anxiously--or angrily--insisting that politics not be
discussed, there you will find a person whose own politics are regnant.
To conclude this digression, I observe that the Linux kernel has sucked
up much oxygen in the highly niche field of Unix software development
history. I hope someone will write an unimpeachably well-sourced
monograph, with primary sources and archival materials, about the CSRG
and BSDI, of Bill Jolitz's time with that firm and his departure, of the
schisms that created the *BSDs, and so on until Steve Jobs returned to
Apple and all right-thinking people flooded into the world's most
beautiful and beneficent walled garden, where they could carry on in
eternal childhood. Then everybody can laugh about how wrong I have it.
*** END POLITICAL DIGRESSION ***
> * 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 :).
Did I say "merely"? I don't _think_ I did...
No, I didn't. But I intuit it was a sufficient condition under the
circumstances, and if I'm correct, that was a superficial judgment.
> They are fundamentally different.
They're both Turing-complete languages. Which says a lot and very
little at the same time.
Anyway, I'm not here to win any coverts to groff from TeX. I'm utter
crap at sales and promotion. I see my job as making groff as good as it
can be without fundamentally changing it. (This occasionally leads to
conflict because views abound regarding what is "fundamental".)
> 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.
Granted. There was definite historical inertia.
> 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.
Right. If so then I think RMS overestimated the contribution of
syntactical ergonomic factors--even if identified with perfect
accuracy--to the production of good software documentation. It sounds
like he thought that putting a system that he judged as elegant into the
hands of the hackers would lead to an irruption of pedagogical talent.
It wasn't to be.
I remember visiting the FSF booth at LWCE-NY in 2000 or 2001, opening up
a copy of the printed and bound glibc manual (already in two volumes
even back then), and pointing out to Bob Chassell a few instances of
what I regarded as content that was well below professional editorial
standards you'd find at, notionally, competing publishing houses like
O'Reilly (I can hear RMS hissing even now), Prentice Hall, or Addison-
Wesley.
I don't remember Bob's response. He neither frustrated me nor gave me
hope. Likely he managed to blend candor and tact. But I might have
been struggling to convince myself I wasn't talking to Gabe Kaplan.
On a positive note, I've noticed Sandra Loosemore (likely NOT
responsible for any of the stuff I griped about) cracking the whip on
the GCC manual over the past year or more. Her efforts are heartening
to see. But I think the community could stand to be more frank with
itself about why 30+ years work by highly capable (and, often, highly
paid) compiler engineers did not render her efforts unnecessary.
> 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.
Well, for a start, consider both editions of _The C Programming
Language_ by Kernighan & Ritchie, W. Richard Stevens's _Advanced
Programming in the UNIX [sic] Environment_, and several other books by
Kernighan and Rob Pike, alone or in combination.
There is also essentially all of the documentation that traditionally
shipped with BSD.
https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/share/doc/psd
https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/share/doc/smm
https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/share/doc/usd
Going back further, there's everything in Volume 2 of the Unix
Programmer's Manual, whence some of the BSD docs derive.
https://archive.org/details/unix-programmers-manual-seventh-edition-vol-2-1983
> (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.)
Does the foregoing help?
> 3) As I recall, there was no free implementation of roff until James
> Clark started GNU groff, as described in the groff manual :).
Right. 1989.
> Texinfo was developed a number of years before that.
I confess I know nothing of its early history.
It would seem unwise to overstate RMS's pro-TeX partisanship, as my
understanding is that the FSF sponsored Clark to write groff, from
scratch, for a period of about (or at least?) a year. Speaking for
myself, I appreciate RMS taking that leap. The TeX community later came
to flirt fairly seriously with non-free licensing out of a concern for
achieving ends that copyright law is not well suited to, like
administration of software project maintenance, and, for want of a
better term, "rights of personality" in the software. People just can't
seem to resist trying to combine copyright law with patent law and
trademark law.
That story had a happy ending though. For a TeXnician's account, which
I find fair and reasonable, see Mittelbach.
https://www.tug.org/TUGboat/tb32-1/tb100mitt.pdf
> TeX was always free software (and predates everything else discussed
> here).
Even apart from the foregoing, it's had its difficulties.
Knuth's license at one time--I have no idea if he's superseded
it--required files to be renamed if someone other than he changed them.
When you consider the file system an API (hello /proc, 9P, and NFS),
that spells trouble.
> At any rate, thanks for all the advice and experience about this
> (seemingly :) tiny issue. --best, karl.
And thank you in turn. I don't often get to pick the brain of a veteran
of wars adjacent to and contemporaneous with the ones I was in.
Regards,
Branden
[1] I am morally obliged at this point to cite The Worst-Written Man
Page Ever in the History of the World.
https://gitlab.com/procps-ng/procps/blob/7ac9a0e1f5606696dc799b773d5ec70183ca91a3/ps/ps.1
(Fortunately, it got better.)
[2]
https://cgit.git.savannah.gnu.org/cgit/groff.git/commit/tmac/an.tmac?id=39d2cefa07d58c856e9e7b0b5f5e8380e949727d
There is, however, a portability hazard with use of `hw`.
groff_diff(7):
Other differences
...
GNU troff does not always hyphenate words as AT&T troff does. The
AT&T implementation uses a set of hard‐coded rules specific to U.S.
English, while GNU troff uses language‐specific hyphenation pattern
files derived from TeX. Some versions of troff reserved meager
storage for hyphenation exception words (arguments to the hw
request); GNU troff has no such restriction. When the hy request
is invoked without an argument, GNU troff sets the automatic
hyphenation mode to the value of the .hydefault register; the AT&T
implementation sets it to “1”, which is not suitable in GNU troff
for some languages, including English.
signature.asc
Description: PGP signature
