mandoc(1)'s man pages, groffed, and Project KIC (was: Milestone reached: hyperlinked mdoc(7) documents in PDF)

[G. Branden Robinson]

[dropping Alex from To: header]

Hi Lennart,

At 2024-03-18T21:13:32+0000, Lennart Jablonka wrote:
> I wouldn’t at all be surprised by what I’d call errors in the mandoc
> man pages, as I guess they aren’t tested a whole lot with more general
> troffs and the project calls mdoc not a macro package or the like, but
> its own language.

Ordinarily I'd characterize that sort of claim as overstated, but mdoc
does bend the *roff language hard.

> > Do you find the attached "groffed" mandoc collection an improvement?

[rearranged]

> And the page numbers reset at the start of each section.  Which they
> shouldn’t do—the book is one unit; it should get its own page numbers.
> And in other books, you don’t usually see page numbers per chapter.

This was a bug in me, not in groff.  I forgot to specify `-rC1` when
generating the PDF.  Include it, and one gets 160 pages (using U.S.
letter paper) numbered consecutively.

> (“Section” being an older term for “man pages,” if memory serves
> right.)

Not as far as I know.  I use the term "document" when it's important to
distinguish between a coherent chunk of man(7) or mdoc(7) with one `TH`
or `Dd` call, respectively, and the face of a (perhaps digitally)
printed "leaf".

> Though Courier is as ugly as ever.

I'm glad you brought this up.  I vigorously agree.  I think inline (as
opposed to "displayed" changes of font family are generally a terrible
idea.  And yes, I know some luminaries do it in their books--Brian
Kernighan for example.  But he also takes authorial care with the
clarity and quality of the result.  (I've been enjoying the recent 2nd
edition of _The AWK Programming Language_ lately.)

mdoc(7) pages typeset by groff have numerous deficiencies, motivated I
think by some misguided notion that if something was "literal", or maybe
not "literal" but something that a user was going to _make_ literal when
they typed it in (through parametric replacement), it should be
formatted in Courier.

I simply cannot subscribe to that principle.  I reject it violently.

One of the problems it causes is that as a stream of text is performing
the Times and Courier switcheroo by the word, it becomes difficult to
tell when a space between words is present.  Courier is monospaced and
its space width is really fat.  Times is not and its space width is
pretty narrow.  In command synopses, it is often hard to tell whether
there is a space before or after a square bracket, for example, because
the brackets, not being "literal", are therefore by this arc-welded
principle of coupling, in Times.  You can observe these problems
starting at the top of page 1 of the mandoc-groffed PDF.  They are
immediately conspicuous.  Look how close together a _closing_ square
bracket is to a subsequent _opening_ one.  Is a space implied there?
You think so?  Look at that fat space after "-M" and before "path".  Are
you still sure?  Probably, if you already understand Unix command
conventions and don't really need to be reading this man page in the
first place.  This is the Neuschwanstein Castle of the clubhouse
experts; "the experienced user will know what is [right]."

No, this is _terrible_ ergonomics.  And, I submit, bad typography.

All people have to do to test my claims is to look at the collected
mandoc man page PDFs I've shared.

> Another place is, on the same page, “( expr  )” as the first tag of
> the tagged list at the end.

That's the exact problem I'm talking about above.  Only one space
follows "expr" (select it in your PDF tool and see) but it's in Courier,
not Times, as the parentheses are.

But yes!  It absolutely does LOOK like two spaces.  People don't read
documentation by selecting it by the character cell in a PDF viewer.
They read it with their eyes and this slavish devotion to Courier for
"literals", even when as here, the argument _isn't even literal_, is
erecting a barrier to comprehension and to simple pleasant reading.

Bad, bad, bad.  I don't know who's behind these choices but I fear I've
made an enemy for life.  (Get in line, eh?)

> And on page 1 (See?  But I do indeed mean the first page of
> apropos(1).), in the second paragraph of the DESCRIPTION, you can see
> too much space after “Nm.”  That happens in a few places.  

Here's the, uh, pellucid macrology behind the exhibit in question.

.Pq the Li \&Nm No and Li \&Nd No macro keys .

Because `Nm` is `Li`teral here (and protected from interpretation by
mdoc(7)'s internal macro system by the dummy character), it gets set in
Courier.  And because `Li` happily eats arguments until hitting a
special one--an mdoc(7) macro name, an item of punctuation, and possibly
some other exceptions a real mdoc maven would add to this list,
haughtily correcting my scandalous ignorance--it can't know to switch
the font face back yet.  The space _has_ to be in Courier.

The thing is, nearly all of this problem is an unnecessary own-goal,
created not with sophisticated macro programming firepower--which every
implementation of mdoc(7) assuredly does possess--but with string
definitions that go bonkers with family-inclusive string definitions.

All, or nearly all, of this is in tmac/mdoc/doc-ditroff.  Observe:

.\" the 'doc-xx-font' strings must not be empty!
.
.ds doc-page-topic-font \f[I]
.ds doc-page-section-font \f[R]
.ds doc-Ad-font \f[I]
.ds doc-Ar-font \f[CI]
.ds doc-Cm-font \f[CR]
.ds doc-Em-font \f[I]
.ds doc-Er-font \f[CR]
.ds doc-Ev-font \f[I]
.ds doc-Fa-font \f[CI]
.ds doc-Fd-font \f[CB]
.ds doc-Fl-font \f[CR]
.ds doc-Fn-font \f[CB]
.ds doc-Ft-font \f[CI]
.ds doc-Ic-font \f[CB]
.ds doc-Li-font \f[CR]
.ds doc-Lk-font \f[R]\"
.ds doc-Me-font \f[B]

...and so on and so forth.

I've been tempted more than once to just nuke these "C"s.  I generally
haven't done it, and any such meddling is sure to bring strident
complaint from some quarters.  наб ripped me a new excretory orifice
when I "demoted" the output of `Nm` from bold to normal weight in the
"Name" section of the page.[1]

So I am glad to hear from someone else who perceives similar problems
with the existing use of Courier.

A few things I'd note:

1.  The groff(7) man page has a problem with Courier too.  It's not as
    bad because it's confined to applications where space width
    ambiguities don't crop up, but it's just plain unnecessary.  And
    I've been saying for years I'd get rid of the page-local macros this
    page uses.  Simplifying them first so that they don't set alight the
    beacons of Courier would be a small but worthwhile step in that
    direction.  And I am cautious of protecting my flank from further
    assault by наб or others claiming that I'm being a hypocrite by
    continuing to "permit" inline Courier in groff man(7) documents.[2]

2.  Again, I have _no_ objection to Courier in _displays_.  And mdoc(7)
    has those.  I'd like to see how far we can get with a strategy of
    assigning these doc-XX-font strings only _style_ changes, and leave
    it to block-structured macros like `Bd -literal`, `Ed` to change the
    font family.  There's a problem to be solved with `Bl`/`El`.  I'll
    need to learn my way around these heavily ornamented macros to grasp
    the shape of it.  Fortunately, examples of usage are not scarce.

3.  None of this should affect anyone reading on terminals in any way.

4.  This is groff--of _course_ you can customize your mdoc.local file to
    put all that Courier right back.[3]  Love it?  Knock yourself out.

That's my proposal for Project KIC: Kill Inline Courier.

Regards,
Branden

[1] https://savannah.gnu.org/bugs/index.php?65101

[2] If someone wants it out sooner, they can submit a high-quality
    patch.

    Part of the jeremiad in the ticket above reminds me of the meme at
    the top of this article.

    https://www.gottesdienst.org/gottesblog/2022/5/15/christian-rock

    But I would disagree (with the jeremiad).

[3] The original 4.4BSD mdoc was customizable in almost the exact same
    way; it simply used different names for the strings, as it had to.
    The technique was cute; you took the macro name and case-swapped it.

    So instead of:

    .ds doc-Ar-font \f[CI]

    you had:

    .ds aR \f[CI]

    ...leaving aside the groff font name and selection escape syntax.

    Yes, weird, but highly regular and totally predictable.  A good
    design choice given the constraints.

signature.asc
Description: PGP signature