From: Ingo Schwarze <firstname.lastname@example.org> To: "Dag-Erling Smørgrav" <email@example.com> Cc: firstname.lastname@example.org Subject: Re: Dashes and strange markup Date: Mon, 6 Mar 2017 16:57:14 +0100 [thread overview] Message-ID: <20170306155714.GB58385@athene.usta.de> (raw) In-Reply-To: <email@example.com> 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 firstname.lastname@example.org
next prev parent reply other threads:[~2017-03-06 15:57 UTC|newest] Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top 2017-03-06 11:17 Dag-Erling Smørgrav 2017-03-06 14:55 ` Anthony J. Bentley 2017-03-06 16:52 ` Dag-Erling Smørgrav 2017-03-06 15:57 ` Ingo Schwarze [this message] 2017-03-06 16:39 ` Dag-Erling Smørgrav 2017-03-06 17:34 ` Ingo Schwarze
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20170306155714.GB58385@athene.usta.de \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --subject='Re: Dashes and strange markup' \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
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).