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 08:12:35 +0100
User-agent: Mutt/1.8.0 (2017-02-23)

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 any case, command names are among the most typical cases
of syntax elements absolutely requiring bold face.

That is not only very firmly established in manual pages but a
widespread convention in printed books about programming as well.

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

Yours,
  Ingo


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



reply via email to

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