Re: [groff] 01/04: nroff(1): Fix style and content issues.

[G. Branden Robinson]

At 2018-11-14T08:12:35+0100, Ingo Schwarze wrote:
> Hi Branden,
> 
> G. Branden Robinson wrote on Tue, Nov 13, 2018 at 09:59:20PM -0500:
> 
> > commit b447d738fb65168ef8ccda2a89555425ebe6aa4a
> > Author: G. Branden Robinson <address@hidden>
> > Date:   Tue Nov 13 11:36:13 2018 -0500
> [...]
> >               + Set "@address@hidden", "groff", "grotty", and "locale"(1) in
> >                 italics, not bold or roman.
> [...]
> > -.B @address@hidden
> > +.I @address@hidden
> 
> I think these particular B -> I changes are wrong and ought to be
> reverted.
> 
> The fundamental rule for syntax elements (somewhat simplified) is
> that bold is for syntax elements that have to be typed verbatim
> (like command line options, keywords, type specifiers, function
> names, ...) and italics/underlined is for placeholders for syntax
> elements that the user has to replace by something else (like
> function argument placeholders, command line argument placeholders,
> ...).

In a synopsis, yes.

> In any case, command names are among the most typical cases
> of syntax elements absolutely requiring bold face.

This is widely overstated.

> That is not only very firmly established in manual pages

Incorrect.  I direct your attention to:
        * the more than 800 man pages in the X Window System
        * the ~307 pages in Seventh Edition Unix distribution; and
        * the over 1100 pages in 4.3BSD.

The above corpora are in fact remarkably consistent about rendering the
topic of the page in italics, more so in fact than they are about
rendering placeholders in italics in the Synopsis section.

If access to any of these is inconvenient for you, I'm happy to share
them.

> but a widespread convention in printed books about programming as
> well.

That's a big field but I checked my copies of several classics from
heavyweights and here's what I found:

        * K&R, _The C Programming Language_, 1st Ed., 1978, uses
          Courier, not bold, for function and command names.
        * Kernighan & Plauger, _Software Tools, 1976, uses Helvetica,
          not bold, for function and command names.
        * Kernighan & Pike, _The UNIX[sic] Programming Environment_,
          1984, uses Courier, not bold, for function and command names.
          It is the first of these books to use italics for much outside
          of the C Reference Manual appendices of K&R 1 and 2.
        * K&R, _The C Programming Language_, 2nd Ed., 1988, same as 1st.
        * W. Richard Stevens, _Advanced Programming in the UNIX®
          Environment_, 1st Ed., 1993, uses Courier, not bold, for
          function and command names and literals in general.

What respected source in the printed domain did you have in mind?  I
admit that Brian Kernighan casts a long shadow over my selections.

> Even Michael Kerrisk agrees with that:
> https://man.openbsd.org/?query=Nd~.&apropos=1&sec=1&manpath=Linux-4.13

Yes, and it's a point upon which I disagree.  Doing so puts too much
bold on the screen (or printed page) for visual comfort.  (You may
appreciate this as a point against GNU long option practices.)  Within a
synopsis, option tags, and perhaps some examples, it is valuable
nevertheless.

But in running prose, it's too much loudness and not necessary for
clarity.  If you disagree, you must explain how people managed to learn
anything from the man pages of 7th Edition Unix or 4.3BSD.

> Much less important: manual page cross references do not require
> any font changes at all.  All parts of them can be set in the default
> roman font because the section number in parentheses already makes
> the word stand out.

Your memory did not fail you here--in 7th Ed. and 4.3BSD, man page cross
references, at least in See Also sections, were typically not marked up
at all.

Nevertheless it is my preference to italicize the names of man page
topics because (1) they generally refer to works of software (if not
commercial products) in some sense, (2) I prefer to use _some_ kind
of markup on them because it gets the spell checker out of the writer's
way (they can either ignore the squiggles or highlights, or use that as
a reminder to add the term to their local dictionary), (3) it flags
the terms for potential "lifting" to semantic markup, that ever-receding
future goal, (4) the X11 corpus follows the practice.

> Some use boldface for such cross references
> anyway, which looks unnecessarily heavy to me, but which i don't
> care that strongly about.  As opposed to abusing italics, at least
> that is not misleading.

I agree that boldface can be unnecessarily heavy, which is why I think
it wise to reduce gratuitous use of it.

Italics are not semantic markup.  They do not mean "replaceable text"
everywhere you see them.

Having consulted all the above, I'm in fact _more_ persuaded that I'm on
the right path.

-- 
Regards,
Branden

signature.asc
Description: PGP signature