Re: Is there any reason not to use <EM> for items emphasized with .Em?

[Ingo Schwarze <schwarze@usta.de>]

Hi,

i think i have made up my mind.  First, what Anthony said here confirms
my impression that <span> is clearly not the right element for .Em, which
was Guy's main point, i think.

Regarding which HTML element to pick, the important aspect to keep in
mind is that .Em, .Sy, and .Li are not semantic, but physical markup.
In other words, they can be used for text that needs markup in some
way when none of the semantic markup macros fit.

In particular,

 - .Em can be used for all text that would usually end up in italic font,
   for example stress emphasis or alternate voice or mood.
 - .Sy can be used for all text that would usually end up in bold face,
   for example importance or highlighting.
 - .Li can be used for all text that would usually end up in fixed width font,
   for example code samples.

Real examples from base system manuals include:

Typical stress emphasis:  -> corresponds to <em>
History substitutions begin with the character
.Ql \&!
and may begin
.Em anywhere
in the input stream (with the proviso that they do
.Em not
nest).

Looks more like alternate quality (technical term):  ->  <i>
The shell begins parsing its input by breaking it into
.Em words .

Obviously, it is not feasible to automatically distinguish both
cases.  But looking at real manuals, my rough guess is that for .Em
we have about

 - 70% of stress emphasis
 - 20% of abuse that should be replaced by other macros
 - 10% of alternate voice, mood, or quality

I didn't count, so the numbers may be somewhat wrong, but the exact
numbers don't really matter.  What matters is that stress emphasis
is the vast majority, and even in the cases of alternate quality,
there is usually some emphasis, too, so <em> isn't that bad either.


Typical importance markup:  ->  corresponds to <strong>
.Sy Note :
.Sy Warning :

Typical examples of highlighting keywords:  ->  <b>
Note that the
.Fl t
flag replaces the function of the old
.Sy dumpdir
program.
.It Sy S
If in the owner permissions, the file is not executable and
set-user-ID mode is set.

Here, my impression is that we have about

 - 80% of importance markup
 -  5% of abuse
 - 15% of keyword highlighting

The reason we don't have more keyword highlighting is that
more specific macros like .Nm .In .Fo .Fn exist.

Here, even though importance markup is clearly in the majority,
keyword highlighting does exist for good reasons, and <strong>
is rather unfortunate for keyword highlighting, so this is a
tougher call than for .Em.  But there seems to be no way out.
Having tons of <b>Warning!</b> all over the place wouldn't be
any better, really.


So i think we should go for the following mappings:

 - .Em                      ->  <em>
 - .Sy                      ->  <strong>
 - .Li Ql .Dl .Bd -literal  ->  <code>

Yes, this is sometimes off, but it's the best fit, i think.

Some specific answers:

Anthony J. Bentley wrote on Tue, Aug 12, 2014 at 08:06:38PM -0600:

> mdoc(7):
> Examples:
>       .Em Warnings!
>       .Em Remarks:

These examples are clearly wrong and should be fixed in the manual.

> (As an aside, there are many uses of Sy in OpenBSD manpages like "Note:"
> and "Important:". Based on mdoc(7) that seems to be misuse of
> presentational macros.)

No, i think that usage is just right.

> Honestly? I think this is just hair-splitting and we should use <em>
> for Em. But if we do that, mdoc(7) probably should be revised for clarity.

Fully agreed.

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv