Re: [groff] .SY/.YS, was: Duff's Device

[G. Branden Robinson]

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
work already.

Looking at the current state of the diff, I see that I'm changing 40
source pages[1], and of those, only 13[2] 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
in pdfroff(1)).

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[3]--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
future."

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
0013a2e010a26f242925b33f8e66be83ebb23ef1.

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
count).

Regards,
Branden

[1] contrib/groffer/roff2.1.man is a template for several generated
    pages.

[2] contrib/mm/groff_mm.7.man
    contrib/mm/groff_mmse.7.man
    contrib/mm/mmroff.1.man
    src/devices/grodvi/grodvi.1.man
    src/devices/grotty/grotty.1.man
    src/devices/xditview/gxditview.1.man
    src/preproc/grn/grn.1.man
    src/preproc/pic/pic.1.man
    src/utils/addftinfo/addftinfo.1.man
    src/utils/lkbib/lkbib.1.man
    src/utils/lookbib/lookbib.1.man
    src/utils/pfbtops/pfbtops.1.man
    src/utils/xtotroff/xtotroff.1.man

[3] 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.

signature.asc
Description: PGP signature