discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
* "Default usage" statement in manpages.
@ 2011-11-29 11:13 Kristaps Dzonsons
  0 siblings, 0 replies; only message in thread
From: Kristaps Dzonsons @ 2011-11-29 11:13 UTC (permalink / raw)
  To: discuss

Hi,

In a recent commit, mandocdb(8)'s "default usage" statement was moved 
above its argument listing:

DESCRIPTION
      The mandocdb utility extracts keywords from UNIX manuals and
      indexes them in a Keyword Database and Index Database for fast
      retrieval.

      By default, mandocdb creates databases in each dir using the
      files mansection/[arch/]title.section and
      catsection/[arch/]title.0 in that directory; existing databases
      are truncated.  If dir is not provided, mandocdb uses the
      default paths stipulated by man(1).

      The arguments are as follows:

I'm curious what people think about this.  In mdocml .1 and .8 manpages, 
the DESCRIPTION is usually laid out with an expansion of `Nd' ("The foo 
utility does this and that..."), then arguments ("Its argument are as 
follows..."), then the defaults ("By default, foo does...").

I think this new format makes a lot more sense to me: readers know 
up-front about the behaviour.

If you agree, we should modify mdoc(7) to note this convention and 
update our own manuals.  It's a small amount of work, and in my opinion, 
makes our manpages more friendly to users.

Thoughts?

Kristaps
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] only message in thread

only message in thread, other threads:[~2011-11-29 11:13 UTC | newest]

Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2011-11-29 11:13 "Default usage" statement in manpages Kristaps Dzonsons

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).