[groff] Bold v Italics: Dawn of Justice

[G. Branden Robinson]

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

Since bold vs. italics is the Lilliputian contretemps of the day, let me
present my guidance to readers from the page and see if we can reach a
consensus.  Fortunately, in source form, the questions are already
itemized, for ease of quoting and objection-taking.

[how I present the difficult issue to the reader]
Because font styles are presentational rather than semantic,
conflicting traditions have arisen regarding which font styles should be
used to mark file or path names,
environment variables,
in-line literals,
and even man page cross-references.

[...]

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.
.
In
.BR .EX / .EE
examples of interactive I/O (such as a shell session),
set only the user-typed input in bold.

[...]

Use italics
for file and path names,
for environment variables,
for enumeration or preprocessor constants in C,
for variable (user-determined) portions of syntax synopses,
for the first occurrence only of a technical concept being introduced,
for names of works of software
(including commands and functions,
.\" The following is an interesting exception that seems to have arisen
.\" organically and nearly universally.
but excluding names of operating systems or their kernels),
and anywhere a parameter requiring replacement by the user is
encountered.
.
An exception involves variable text in a context that is already marked
up in italics,
such as file or path names with variable components;
in such cases,
follow the convention of mathematical typography:
set the file or path name in italics as usual
(see
.B .IR
below),
but use roman for the variable part,
and italics again in running roman text when referring to the variable
material.

[...]

All right--blast away.  :)

Regards,
Branden

signature.asc
Description: PGP signature