discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: "Dag-Erling Smørgrav" <des@des.no>
Cc: discuss@mdocml.bsd.lv
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: <86wpc2ac39.fsf@desk.des.no>

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

  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 \
    --to=schwarze@usta.de \
    --cc=des@des.no \
    --cc=discuss@mdocml.bsd.lv \
    --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).