groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Ingo Schwarze
Subject: Re: [groff] 01/04: nroff(1): Fix style and content issues.
Date: Wed, 14 Nov 2018 23:42:59 +0100
User-agent: Mutt/1.8.0 (2017-02-23)

Hi Branden,

G. Branden Robinson wrote on Wed, Nov 14, 2018 at 03:26:14PM -0500:
> At 2018-11-14T08:12:35+0100, Ingo Schwarze wrote:
>> 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.

Assigning conflicting meanings to the same markup in the same
manual page sounds like a really bad idea.

>> 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 X manual pages are low quality in many respects, so using them
as an example is quite meaningsless.  Besides, they are inconsistent
in this very respect:  Xephyr(1) Xmark(1) Xnest(1) Xorg(1)
bdftruncate(1) cwm(1) cxpm(1) fc-cache(1) gccmakedep(1) glxinfo(1)
luit(1) makedepend(1) setxkbmap(1) ssh-askpass(1) startx(1) xcompmgr(1)
xgamma(1) xidle(1) xinit(1) xlock(1) xtsscale(1) xvinfo(1) are some
examples of pages that do correctly mark up commands in bold.

>       * the ~307 pages in Seventh Edition Unix distribution; and

You have a point here; v7 did not know that convention yet, they
indeed used conflicting markup in the SYNOPSIS and DESCRIPTION.

>       * the over 1100 pages in 4.3BSD.

Yes, because up to about Reno, BSD manuals were more or less an
extension of the AT&T manuals.

However, the consistent scheme i described was established between
4.3 and 4.4 and has been used ever since - i.e. for the last 28
years, see e.g.

  https://man.openbsd.org/?query=Nd~.&apropos=1&sec=1&manpath=4.4BSD-Lite2

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

No, i have all of them readily installed, but thanks.

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

Hmm - i have to admit printed books are less consistent than is seemed
to remember.  There are some examples, e.g. Stevens, TCP/IP Illustrated
uses bold face, Stroustrup, C++ uses a bold italic font - but you are
right, books differ, so they provide less guidance than i thought.

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

I agree that some of the recommendations in man-pages(7) are not good;
but when recommendations from the BSD and Linux man pages worlds agree,
we should probably not diverge.

> Doing so puts too much
> bold on the screen (or printed page) for visual comfort.

Beauty sometimes is a valid argument when choosing markup - but it
doesn't beat consistency and clarity.

> (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

Actually, command names occur only occasionally in running text, typically
significantly less than once per paragraph, on average.  So even if
you would prioritize beauty over consistency, that argument is weak.

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

That's a straw man - you can understand a well-written manual page
without any markup whatsoever.  Consistent markup is merely one
tool to make it easier.  And yes, the Bell Labs manuals were very
consistent, up to the point of consistently sticking to this
inconsistency between SYNOPSIS and DESCRIPTION.

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

Yes, and also from 4.4BSD onwards ever since (speaking of physical
markup, that is, of course they do carry semantic markup).

> 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,

Whatever - i dislike font changes for cross references for the stated
reasons, but it's not so important because even with markup, the
section number in parentheses makes it quite clear what it is.

> (4) the X11 corpus follows the practice.

Again, please don't use X as an example.  Besides, SEE ALSO appears
to be vastly inconsitsent there.  My impression is that a bit more
than half of the pages use roman(roman), a bit less than half
bold(roman), but italic(roman) seems rather rare.

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

My above remark was specifically directed at cross references -
because in contrast to command names, cross refences do tend to occur
in clusters, and *then* it looks heavy.  That was an argument for
roman, not italic. 

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

For syntax elements, when used well, they almost do; certainly in
modern BSD manuals (that is, those aged 25 years or less).

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

Hmpf.  We two seem to have some talent to disagree on relatively
simple, elementary questions.

Yours,
  Ingo



reply via email to

[Prev in Thread] Current Thread [Next in Thread]