Hi Morten, I agree that there is sometimes an inconsistency here; sometimes it's real, sometimes it's only apparent, and sometimes it's a deliberate fib for ergonomic reasons.
At 2026-02-21T13:41:33+0100, Morten Bo Johansen wrote:
> In some manual pages, macros are (IMO, correctly) prefixed with a dot.
My opinion is different. Dots are not part of (most) macros' names.
The dot is a control character, which makes it part of a macro's _call
syntax_.
*roff has two control characters, the regular one, a dot, and the
"no-break control character", which is an apostrophe (').
Each is configurable, with the `cc` and `c2` requests, respectively.
In any document, you can call macros just as well with the no-break
control character as with the regular one. Historically, this was not
done because it gained nothing. In AT&T troff there was no way for a
macro to tell which control character was used to call it.
GNU troff is little more sophisticated.
groff(7):
Control characters
The formatter recognizes a control character only at the beginning
of an input line, or at the beginning of a branch of a control
structure request; see section “Control structures” below.
A few requests cause a break implicitly; use the no‐break control
character to prevent the break. Break suppression is its sole
behavioral distinction. Employing the no‐break control character
to invoke requests that don’t cause breaks is harmless but poor
style.
The control character “.” and the no‐break control character “'”
can be changed with the cc and c2 requests, respectively. Within a
macro definition, register .br indicates the control character used
to call it.
...
Read‐only registers
Predefined registers whose identifiers start with a dot are read‐
only. Many are Boolean‐valued.
...
\n[.br] The normal control character was used to call the
macro being interpreted (Boolean‐valued).
...
Nevertheless, in practice, _most_ macro definitions in groff's macro
packages don't bother to see which control character was used to call
them. Often, it doesn't matter.
Notice how, in the foregoing, the leading dot _is_ part of the
register's name. It has nothing to do with control characters.
All of the following are valid macro _and_ register names.
.foo
..foo
...
foo.bar
When you use requests to create, rename, delete, or alias them, _you
must use their names precisely as-is_.
Not with a leading dot you propose to be correct.
> In others such as groff_mm, groff_me and groff_www, the macros are
> written without the leading dot. I should say that the former notation
> is correct because that is how they are actually written: ".AL" is a
> macro "AL" is not.
But that's not how they're actually written _when not calling them_.
> I have made a small convenience function in a groff editing mode I
> have made for my editor whereby I may just hit <F1> in a line with a
> macro and then the corresponding manual page will pop up and show the
> first match of the macro (often its definition), but this is rather
> dependent on the leading dot being present in the search pattern,
> otherwise it is anyone's guess what will actually be matched.
Yes! That's not a bad idea at all, and it lies behind the discipline I
have tried to adopt for groff_man(7) and groff_man_style(7), where you
find the dot prefix only in (1) examples of *roff input ("how do I use
this?"); (2) the macro summary table at the top of the man page ("remind
me what this thing is?"); and (3) the _definition entry for the macro_
("give me all the deets, bro.").
I made that choice for largely the same reasons you wrote your editor
extension. When hunting for a macro name, people generally want to find
one of the 3 foregoing resources, not passing mentions. If the want to
find every occurrence, they can omit the leading dot.
_However_, this same convention would be invalid and/or ineffectual for,
say, groff_mdoc(7), which implements its own macro processing system on
top of *roff's, and you commonly encounter the Black Speech of Mordor.
.It Li ".Op Fl I Ns Ar directory"
Because of that bespoke macro processing system, though, mdoc(7) is kind
of a worst case for the documentary reform you seek. No other macro
package bends accepted *roff idioms as hard.
But, once we get away from man pages and the restricted conventions on
their content imposed initially by a mushroom field of poorly written
"man to HTML" converters and (my surmise) mdoc's design goal of being
able to kick away *roff completely from underneath itself,[1] which
after about 20 years Krisaps Dzonsons and later Ingo Schwarze took it
upon themselves to fulfill with mdocml/mandoc(1), we encounter the full
diversity of macro packages and the full power of the *roff system laid
bare and at the fingertips of the document composer.
Which leads me to your final question.
> Would you agree that the manual pages that do not adhere to the
> leading dot notation ought to be changed?
I am not sure that I do. Once we climb out of the man page kiddie pool
and go swimming in the *roff ocean, we seize more power and take on more
responsibility. As I hinted above, we can:
* define our own macros;
* rename macros;
* delete macros; and
* (in GNU troff) alias macros.
It is then important for us to have our wits about us and not confuse
macro names with macro call syntax.
For the mundane purpose of locating macro definitions in a man page,
I'll tell you what I do. Since I'm usually in the pager, I simply do a
regex search including word boundary operators.
For example, I recently had reason to look up mm(7)'s `LB` macro.[5]
When consulting the groff_mm(7) man page, here's what I typed.
/\<LB\>
...and then "n", until I found what I wanted. It came up on the second
match.
> I am willing to do the work, in that case.
I hope the foregoing explains why I am not convinced that this is
something we should do on a blanket basis.
Regards,
Branden
[1] mdoc was initially written at about the same time James Clark was
first writing groff. I'm not sure he and the relevant people in the
CSRG were aware of each other's efforts. They arose for similar
reasons: AT&T had a monopoly on troff and it was proprietary,
commercial, expensive software. (This stroke of strategic market
brilliance also contributed massively to TeX's success.) The CSRG
innovated the mdoc language for much the same reason (or so I infer)
they embraced Eric Allman's "me" alternative to "ms". Especially
after about 1982, they could see that AT&T was going to be nasty
about things, and it would be decades before the _Oracle v. Google_
case would (largely) settle the question of API copyright in the
United States. So man(7) needed to be replaced just as ms(7) had.
The CSRG furthermore knew that *roff itself presented the same
problem as AT&T's macro package for it. So the charter given to
mdoc's designers, I surmise, was to charge headlong into the
"second-system effect".[2] And that they did, with fleet feet.
The availability of groff, which included from early days not just a
reimplementation of man(7) but of its SunOS 4 variant, widely
considered by Berkeley acolytes to be the best realization of the
BSD system. (And just LOOK at how much money Bill Joy was making!)
Moreover, AT&T was conspicuously not taking the Free Software
Foundation to court, despite GNU cloning Unix APIs left and right.
At this point, again I surmise, viewpoints in the CSRG split. Some
said, "hey, free software is free software, we can get the source,
we can hack on it, we can share it with anyone we want--'sall good,
man.". As they did with GCC before it,[3] the CSRG happily absorbed
groff 1.01 into the partial OS release known as "Net/2",[4] a
deliberate stepping stone on the long road to freeing BSD of
AT&T-encumbered code.
But there were others in the CSRG. People whose dreams were being
broken in the small--with man(7) freed, how could a case for mdoc(7)
be made on the basis of cost/licensing?--and in the large: with this
copyleft thing, _how am I supposed to make at least 10 million
dollars and retire at forty?_ (Understand--it was 1990 or
thereabouts. Today's Silicon Valley thought leaders wouldn't waste
their time to wipe their rears with a paltry 10 million dollars.)
And that, I am convinced, is why the BSD community, which had once
been cool with stuff from GNU, became a citadel of anti-copyleft
sentiment. And there were plenty of firms around to keep you
chasing the carrot of a yacht-bound retirement before you got your
first prescription for bifocals.
[2] https://en.wikipedia.org/wiki/Second-system_effect
[3]
https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/usr.bin/gcc/Makefile
[4]
https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/usr.bin/groff/VERSION
[5] https://savannah.gnu.org/bugs/?68065
signature.asc
Description: PGP signature
