Re: [groff] Bold v Italics: Dawn of Justice

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Thu, Nov 15, 2018 at 09:20:42PM -0500:

> It was evidently excessively optimistic of me to regard the silence
> toward my overhaul of groff_man(7) as assent.

Actually, i missed these new recommendations among the large volume
of polishing.  That's not your fault; it is hard for you to anticipate
which of your improvements might be controversial or might not seem
improvements to others, and discussing everything is impractical.

> Use bold
> for literal portions of syntax synopses,
> for command-line options in running text,
> and for literals that are major topics of the subject under discussion;
> for example,
> this page uses bold for macro and register names.

Agreed.

[order changed for grouping of responses in the following paragraph]

> Use italics
> for file and path names,
> for variable (user-determined) portions of syntax synopses,
> for the first occurrence only of a technical concept being introduced,
> and anywhere a parameter requiring replacement by the user is
> encountered.

Agreed.

> for environment variables,
> for enumeration or preprocessor constants in C,

I don't particularly like that, and i also don't particularly like
Werner's alternative suggestion of setting them in bold; i'd prefer
roman, even though that also has downsides.  But given that man(7)
doesn't really offer a good option for these, i don't feel strongly
either way.

> for names of works of software
> (including commands and functions,

Here, i strongly disagree.  I consider it important that these are
consistently set in bold.

> .\" The following is an interesting exception that seems to have arisen
> .\" organically and nearly universally.
> but excluding names of operating systems or their kernels),

That seems excessive, not so relevant detail.  If you avoid the
over-generalization "works of software" and only talk about names of
commands and functions in the first place, you can delete this
distracting exception including the comment.

So regarding what you wrote in the manual page, i only see serious
disagreement regarding the names of commands and functions,
and less important disagreement regarding environment variables
and enumeration and preprocessor constants.

Yours,
  Ingo