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

[Ingo Schwarze]

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