From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mailout-webserver.scc.kit.edu (mailout-webmail.scc.kit.edu [129.13.185.232]) by krisdoz.my.domain (8.14.5/8.14.5) with ESMTP id s7DLN1Op031080 for ; Wed, 13 Aug 2014 17:23:02 -0400 (EDT) Received: from hekate.usta.de (asta-nat.asta.uni-karlsruhe.de [172.22.63.82]) by scc-mailout-02.scc.kit.edu with esmtp (Exim 4.72 #1) id 1XHg0Z-0003R3-SP; Wed, 13 Aug 2014 23:22:59 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1XHg0Z-0005zN-RA; Wed, 13 Aug 2014 23:22:59 +0200 Received: from iris.usta.de ([172.24.96.5] helo=usta.de) by donnerwolke.usta.de with esmtp (Exim 4.72) (envelope-from ) id 1XHg0Z-0002Sw-PV; Wed, 13 Aug 2014 23:22:59 +0200 Received: from schwarze by usta.de with local (Exim 4.77) (envelope-from ) id 1XHfzp-0005JU-3Q; Wed, 13 Aug 2014 23:22:13 +0200 Date: Wed, 13 Aug 2014 23:22:12 +0200 From: Ingo Schwarze To: jmc@openbsd.org Cc: tech@mdocml.bsd.lv Subject: mdoc(7): improve description of .Em and .Sy Message-ID: <20140813212212.GG26534@iris.usta.de> X-Mailinglist: mdocml-tech Reply-To: tech@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.5.21 (2010-09-15) 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 , sometimes , .Sy sometimes and sometimes , 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