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