[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [groff] .SY/.YS, was: Duff's Device
G. Branden Robinson
Re: [groff] .SY/.YS, was: Duff's Device
Wed, 27 Jun 2018 12:50:57 -0400
At 2018-06-27T16:13:09+0200, Ingo Schwarze wrote:
> Hi Branden,
> G. Branden Robinson wrote on Wed, Jun 27, 2018 at 09:16:18AM -0400:
> > I'm in the midst of preparing a commit to make sure all the groff
> > man pages have Synopsis sections that (1) use .SY and .YS (and .OP
> > where feasible),
> Must you really do that?
No one's got a gun to my head, but I plan to, and I've done most of the
Looking at the current state of the diff, I see that I'm changing 40
source pages, and of those, only 13 require conversion from raw
font-based markup to the more semantic .SY/.YS.
I admit that .OP is a problem. It promises too much, given the multiple
conventions for option syntax in popular use. It's good for options
that take no arguments, okay for options that take a mandatory argument
separated by whitespace, and painful for every other case (we have some
But .SY/.YS does useful things; it turns off hyphenation, an advantage
you don't notice because in your ecosystem hyphenation is always off
anyway, and it indents the arguments to the command if they line-wrap,
which allows a pleasant and ergonomic visual effect and keeps man page
writers from trying to reinvent that wheel with \w tricks, or more
likely, very crude attempts at manual indentation which will not align
correctly on both terminal and typesetter output devices.
> I'm still hoping that at some point, we may be able to get the
> groff manual pages at least half-portable, even though that may
> still be a long way. Use of .SY/.YS is a major step backwards.
My objectives do not include killing off the man macro package for
non-legacy purposes, at least not in favor of mdoc. Yours do.
Everything we do to make the man macro package less capable and
attractive to use than it already is--and it already has many design
problems and has proven too hard for many garden-variety developers to
use competently--is going to become an argument by you to just write
in mdoc instead. This is not conjecture; I've seen you do on it this
list, and up to a certain point I even support you doing it.
Heck, if Peter Schaffter were to propose rewriting all the man pages in
mom instead, I might even volunteer as a lieutenant. :P
(You can ask me why, but that would be a separate discussion.)
I think we share a goal of getting good documentation in front of
people's eyes. I think if mdoc were going to take over the world, it
would have happened already. Michael Kerrisk has had an open invitation
in the man-pages project to be seduced away from man(7) for 14 years.
I'm not kidding. In his man(7) page, he has the following passage:
"By sticking to the safe subset described above, it should be easier to
automate transitioning to a different reference page format in the
According to git blame, these lines have not been touched since 3
November of 2004.
I don't see an mdoc revolution coming. Instead, we're limping along
with man(7). But if we're going to limp, I want us to limp as
comfortably as possible.
Consequently, my goals are to make the groff man page corpus (1)
consistent and (2) a good example for man page authors to copy. That's
why I've been trying to chop out custom macros, low-level requests, and
esoteric escape sequences--especially when these have been cargo-culted
in or been rendered no-ops by subsequent development. See e.g., commit
The shorter path to consistency is to adopt .SY/.YS across the groff man
page corpus. That has me changing 13 pages instead of 36 (by rough
 contrib/groffer/roff2.1.man is a template for several generated
 For many years, as I recall, Linux ps had the worst man page I have
ever seen in my life. Worst not due to incompetence, but malice.
I know this because the author/maintainer ranted on Debian mailing
lists about it at the time. He hated man(7), maybe hated *roff too,
and deliberately wrote the page in a fit of Torvaldsian
contrarianism, inverting every man page convention he could think
of. Mainly it was his users who suffered, hapless fools that they
were to dare the command "man ps". RMS might have missed an
opportunity to recruit this gentleman to Texinfo advocacy, but the
ps guy probably hated that, too. Anyway, at some point in the early
2000s, a less irascible maintainer took over and the modern Linux ps
man page is a vast improvement.
Description: PGP signature
- [groff] Duff's Device lurking in refer.cpp, G. Branden Robinson, 2018/06/26
- Re: [groff] Duff's Device lurking in refer.cpp, Steffen Nurpmeso, 2018/06/26
- Re: [groff] Duff's Device lurking in refer.cpp, Ralph Corderoy, 2018/06/27
- Re: [groff] Duff's Device lurking in refer.cpp, G. Branden Robinson, 2018/06/27
- [groff] .SY/.YS, was: Duff's Device, Ingo Schwarze, 2018/06/27
- Re: [groff] .SY/.YS, was: Duff's Device,
G. Branden Robinson <=
- Re: [groff] .SY/.YS, was: Duff's Device, Nate Bargmann, 2018/06/27
- Re: [groff] .SY/.YS, was: Duff's Device, G. Branden Robinson, 2018/06/28