[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: |
Thu, 15 Nov 2018 18:16:59 +0100 |
User-agent: |
Mutt/1.8.0 (2017-02-23) |
Hi Branden,
G. Branden Robinson wrote on Thu, Nov 15, 2018 at 11:36:42AM -0500:
> A. Always set command names in bold.
> B. Always set man page topics in bold.
I'd answer "both" (except that, less importantly, in cross references
with trailing section numbers in parentheses, roman is preferable).
> At 2018-11-15T06:31:21+0100, Werner LEMBERG wrote:
>> As Ingo says: only placeholders get italic, the rest gets bold
>> tagging.
For syntax elements, that is. Of course, italics for stress emphasis
of normal English words also exists.
> That's a much broader mandate than what you quoted above. It would mean
> I also need to revert my recent changes of environment variables to
> italics,
Environment variable names are typically all caps, so they already
stand out and do not necessarily need any markup at all. When
available, it may be a good idea to set them in a monospace font;
at least that's what i do in mandoc.css. Same for preprocessor-#define'd
constants and for errno(2) constants. But that's not really an
option for man(7) documents because the man(7) language does not
provide any way to portably request a monospace font. Some people
try to use various low-portability idioms like \fC, \f(CW, \f(CR,
often causing formatter-dependent and even output-device-dependent
trouble, so i wouldn't recommend trying that in man(7) documents.
In case this seems to contradict what i said earlier: the rationale
is that names of environment variables ought to be formatted in a
uniform way. However, some function almost like keywords (HOME,
LC_CTYPE, ...) while many others can be freely chosen by the user.
So neither bold nor italics would fit all cases - together with the
argument above, that motivates the answer of "roman".
All that said, what to do with environment variable names is much less
clear than with command names. I don't particularly like making
them italic, but i can live with it - in man(7) documents only,
of course, there is no problem with them in mdoc(7).
> and abort my intentions to migrate file specifications to
> italics.
Actually, no, i fully agree with setting file names in italics.
Again, having uniform formatting for filenames is more important
than the bold/italic rule. In many cases, filenames can be freely
chosen by the user, so italics are appropriate. The consequence
that fixed filenames like /etc/fstab also end up in italics is
unavoidable.
Yours,
Ingo