tech@mandoc.bsd.lv
 help / color / mirror / Atom feed
* mdoc(7): improve description of .Em and .Sy
@ 2014-08-13 21:22 Ingo Schwarze
  2014-08-13 22:54 ` Guy Harris
       [not found] ` <20140814065720.GB7407@harkle.home.gateway>
  0 siblings, 2 replies; 5+ messages in thread
From: Ingo Schwarze @ 2014-08-13 21:22 UTC (permalink / raw)
  To: jmc; +Cc: tech

Hi,

when working on mandoc -Thtml, we noticed that the descriptions
of .Em and .Sy in the mandoc(1) manual are of dubious quality.

There are four problems with what we have:

 1) For both .Em and .Sy, mdoc(7) says they should not be used
    to mark up technical terms.  This neither matches historical
    nor current practice nor is it possible to follow that advice.
    Situations regularly arise where markup for technical terms
    is needed but none of the semantic macros fit.

 2) In these situations, mdoc(7) provides no advice whatsoever
    which macro to use.

 3) The examples given for .Em blatantly contradict the explanation
    given right above.  While the explanation talks about emphasis,
    the examples are typical for importance; see for example
    https://developer.mozilla.org/en-US/docs/Web/HTML/Element/em
    https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strong
    for the distinction.  Also, the examples do not agree with
    current practice, neither in typography in general nor in our
    manuals, most of which correctly use .Sy for words like "Note:"
    and "Warning!"

 4) .Sy lacks any examples whatsoever.

To fix this, i dug up all existing versions of historical mdoc(7)
manuals to understand what these macros were originally intended
to be.

4.3BSD-Reno (1990) has in mdoc.samples(7):

  Symbolic
  The symbolic request is really a boldface request.  The need for
  this macro has not been established, it is included 'just in case'.
  Usage: .Sy symbol ...
  Example output: something bold

  Emphasis Request
  A portion of text may be stressed or emphasized with the .Em request.
  The font used is commonly italic.
  Usage: .Em argument ...

4.3BSD Net/2 (1991) mdoc.sample(7) up to current groff_mdoc(7) have:

  Symbolic
  The symbolic emphasis macro is generally a boldface macro in either
  the symbolic sense or the traditional English usage.
  Usage: .Sy symbol ...
  Example usage: .Sy Important Notice
  Example output: Important Notice

  Emphasis Macro
  Text may be stressed or emphasized with the `.Em' macro.  The usual
  font for emphasis is italic.
  Usage: .Em argument ...
  Example usage: .Em does not
  Example usage: .Em exceed 1024 .
  Example usage: .Em vide infra ) ) ,

4.4BSD (1993) mdoc(7) has in the macro overview:

  Sy: Symbolic (traditional English).
  Em: Emphasis (traditional English).

Our own MACRO OVERVIEW in mdoc(7) has:

  Physical markup:
  Em: italic font or underline (emphasis)
  Sy: boldface font (symbolic)

The central question is whether these macros should be considered
as semantic or as physical markup.  While the historic documents
may slightly, if inconsistently, favour the semantic standpoint,
in our MACRO OVERVIEW i called them "physical", and i'd like to
stick with that, for the following reason:  Even if we call them
semantic, we have to define such a broad range of semantic
meanings that translation into any other modern semantic markup
language, in particular HTML, becomes impossible.  In particular,
sometimes .Em would have to become <em>, sometimes <i>, .Sy
sometimes <strong> and sometimes <b>, but there is no way to
automatically decide which is the right one when finding one of
these macros in a manual page, so we would have to fall back to
physical markup anyway.  Calling the physical also reflects actual
usage better and isn't completely inconsistent with historical
documentation.

So, i'm proposing the patch appended below.  Note that i'm also
providing some (new) advice which one to use for what.  I'm well
aware that our manuals are not consistent about that, but i think
this is the right direction to move:

  bold:
  .Nm  for utility and page names
  .Fl  for utility options
  .Cm  for fixed strings passed as arguments
  .In  for include files
  .Fo  and .Fn for function names
  .Ms  for mathematical symbols
  .Sy  for other syntax elements to be given verbatim
  .Sy  for highlighting importance

  italic:
  .Pa  for file names
  .Vt  for variable types
  .Va  for variable names
  .Ft  for function return types
  .Fa  for function arguments
  .Ar  for other syntax element placeholders,
       in particular arguments to .Nm, .Fl, .Cm, and .Ic
  .Em  for other technical terms and placeholders, except syntax elements
  .Em  for stress emphasis

That list seems exhaustive to me, and rather close to existing practice.

OK?
  Ingo


Index: mdoc.7
===================================================================
RCS file: /cvs/src/share/man/man7/mdoc.7,v
retrieving revision 1.116
diff -u -p -r1.116 mdoc.7
--- mdoc.7	8 Aug 2014 16:32:17 -0000	1.116
+++ mdoc.7	13 Aug 2014 20:09:51 -0000
@@ -1482,16 +1482,29 @@ See also
 and
 .Sx \&It .
 .Ss \&Em
-Denotes text that should be
-.Em emphasised .
-Note that this is a presentation term and should not be used for
-stylistically decorating technical terms.
-Depending on the output device, this is usually represented
-using an italic font or underlined characters.
+Request an italic font.
+If the output device does not provide that, underline.
 .Pp
-Examples:
-.Dl \&.Em Warnings!
-.Dl \&.Em Remarks :
+This is most often used for stress emphasis (not to be confused with
+importance, see
+.Sx \&Sy ) .
+In the rare cases where none of the semantic markup macros fit,
+it can also be used for technical terms and placeholders, except
+that for syntax elements,
+.Sx \&Sy
+and
+.Sx \&Ar
+are preferred, respectively.
+.Pp
+Examples:
+.Bd -literal -compact -offset indent
+Selected lines are those
+\&.Em not
+matching any of the specified patterns.
+Some of the functions use a
+\&.Em hold space
+to save the pattern space for subsequent retrieval.
+.Ed
 .Pp
 See also
 .Sx \&Bf ,
@@ -2652,10 +2665,24 @@ See also
 and
 .Sx \&Ss .
 .Ss \&Sy
-Format enclosed arguments in symbolic
-.Pq Dq boldface .
-Note that this is a presentation term and should not be used for
-stylistically decorating technical terms.
+Request a boldface font.
+.Pp
+This is most often used to indicate importance or seriousness (not to be
+confused with stress emphasis, see
+.Sx \&Em ) .
+When none of the semantic macros fit, it is also adequate for syntax
+elements that have to be given or that appear verbatim.
+.Pp
+Examples:
+.Bd -literal -compact -offset indent
+\&.Sy Warning :
+If
+\&.Sy s
+appears in the owner permissions, set-user-ID mode is set.
+This utility replaces the former
+\&.Sy dumpdir
+program.
+.Ed
 .Pp
 See also
 .Sx \&Bf ,
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2014-08-14 22:06 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-08-13 21:22 mdoc(7): improve description of .Em and .Sy Ingo Schwarze
2014-08-13 22:54 ` Guy Harris
2014-08-14 16:07   ` Ingo Schwarze
     [not found] ` <20140814065720.GB7407@harkle.home.gateway>
2014-08-14 15:13   ` Ingo Schwarze
     [not found]     ` <20140814201627.GD7407@harkle.home.gateway>
2014-08-14 22:05       ` Ingo Schwarze

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).