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

[G. Branden Robinson]

At 2018-11-15T18:16:59+0100, Ingo Schwarze 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.

This might be the _only_ uncontroversial point.  My toy semantic
extension tmac file already has .EMPH and .STRONG.  :)

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

We already do it with .EX/.EE, but that's hidden within the macro
implementation so, in my view, it's fair play.  Varying *roff front-ends
and output devices can (and should) be coped with there, not foisted off
on the poor man page writer.

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

Indeed.  I'm quoting all of the above to reinforce just how fragile the
seemingly simple "literal -> bold; replaceable -> italic" paradigm
actually is.  My numerous style commits have not been whimsical; one
reason I write at length, testing Ralph's patience, is to expose my
rationales and motivations.

You and I will likely still disagree about what we'd like to see
markup-wise in the terminal window, but I think it would be altogether a
better world if we made fun of each other's $HOME/.troffrc files while
the groff man pages, at least, were pleasantly semantic and above the
fray.  :)

-- 
Regards,
Branden

signature.asc
Description: PGP signature