From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-02.scc.kit.edu (scc-mailout-kit-02.scc.kit.edu [129.13.231.82]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id fc148c6e for ; Mon, 6 Mar 2017 10:57:22 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1ckv0h-00010l-24; Mon, 06 Mar 2017 16:57:21 +0100 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1ckv0c-0005ud-TS; Mon, 06 Mar 2017 16:57:14 +0100 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1ckv0c-0001FW-O6; Mon, 06 Mar 2017 16:57:14 +0100 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 779cf478; Mon, 6 Mar 2017 16:57:14 +0100 (CET) Date: Mon, 6 Mar 2017 16:57:14 +0100 From: Ingo Schwarze To: Dag-Erling =?utf-8?B?U23DuHJncmF2?= Cc: discuss@mdocml.bsd.lv Subject: Re: Dashes and strange markup Message-ID: <20170306155714.GB58385@athene.usta.de> References: <86wpc2ac39.fsf@desk.des.no> X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <86wpc2ac39.fsf@desk.des.no> User-Agent: Mutt/1.6.2 (2016-07-01) Hi, Dag-Erling Smoergrav wrote on Mon, Mar 06, 2017 at 12:17:30PM +0100: >> des@hive ~% uname -r >> 11.0-RELEASE-p2 >> des@hive ~% PAGER=cat whatis beastie >> beastie.4th(8) - FreeBSD ASCII art boot module known simply as beastie >> to the right of the boot loader menu. [...] > I cut it short, but it prints out the entire DESCRIPTION section instead > of just the document description. That's correct behaviour. If you specify a one line desciption, it is supposed to appear in whatis(1). > So apparently Nd was (ab)used "Abused" is indeed the correct word. I have never seen such horrible abuse of .Nd before. > for an en- or em-dash, and I can sort of understand it because it is > documented to "print a dash followed by its arguments", Well, the old mdoc.samples(7) was very imprecise in many places. The newer groff_mdoc(7) is now much better, and it clearly says that the usage is question is incorrect: The NAME section consists of at least three items. The first is the .Nm name macro naming the subject of the man page. The second is the name description macro, .Nd, which separates the subject name from the third item, which is the description. The description should be the most terse and lucid possible, as the space available is small. That clearly says that what follows .Nd is the description. It says that is is intended for use in the NAME section; admittedly, it does not explicitly say that it should not be used outside the NAME section, but given the content of the above paragraph, that more or less goes without saying. The mdoc(7) manual is more explicit: Nd A one line description of the manual's content. This is the mandatory last macro of the NAME section and not appropriate for other sections. Examples: .Nd mdoc language reference .Nd format and display UNIX manuals The Nd macro technically accepts child macros and terminates with a subsequent Sh invocation. Do not assume this behaviour: some whatis(1) database generators are not smart enough to parse more than the line arguments and will display macros verbatim. > and mandoc's makewhatis is less forgiving than groff. Well, abusing .Nd outside NAME is so bizarre that being forgiving about it would be a bad idea. The much more common abuse that needs to be handled is multi-line .Nd blocks containing macros roughly as follows: .Sh NAME .Nm ugliness .Nd this is a .Em very stupid idea, but somewhat widespread .Sh DESCRIPTION People would bitterly complain about $ whatis ugliness ugliness(1) - this is a Anthony correctly answered the rest, so my impression is that no code or documentation changes are required. Yours, Ingo -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv