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 s7DEqeqd027435 for ; Wed, 13 Aug 2014 10:52:41 -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 1XHZum-0005YC-0f; Wed, 13 Aug 2014 16:52:36 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1XHZul-0007RH-Vz; Wed, 13 Aug 2014 16:52:35 +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 1XHZul-0001Vg-Uo; Wed, 13 Aug 2014 16:52:35 +0200 Received: from schwarze by usta.de with local (Exim 4.77) (envelope-from ) id 1XHZu1-000617-5i; Wed, 13 Aug 2014 16:51:49 +0200 Date: Wed, 13 Aug 2014 16:51:48 +0200 From: Ingo Schwarze To: "Anthony J. Bentley" Cc: tech@mdocml.bsd.lv, Guy Harris Subject: Re: Is there any reason not to use for items emphasized with .Em? Message-ID: <20140813145148.GA26534@iris.usta.de> References: <01237D5A-9F46-4047-83BF-A98CAB0C16E1@alum.mit.edu> <20140813011505.GA24152@iris.usta.de> <3063.1407895598@cathet.us> X-Mailinglist: mdocml-tech Reply-To: tech@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <3063.1407895598@cathet.us> User-Agent: Mutt/1.5.21 (2010-09-15) Hi, i think i have made up my mind. First, what Anthony said here confirms my impression that 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 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): -> 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 isn't that bad either. Typical importance markup: -> corresponds to .Sy Note : .Sy Warning : Typical examples of highlighting keywords: -> 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 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 Warning! all over the place wouldn't be any better, really. So i think we should go for the following mappings: - .Em -> - .Sy -> - .Li Ql .Dl .Bd -literal -> 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 > 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