Re: Manual pages for GNU programs: template
david> When we are at it: Lars, forgot to add ENVIRONMENT, FILES, ACKNOWLEDGMENT
david> sections (if appropriate). man(7) suggests:
lars> I left them out on purpose. The Debian maintainer can add them
lars> if he wants to, but I thought it would be better to keep the
lars> manual page simple as possible so as to make sure it requires
lars> few updates.
IMHO, man-pages are technical references. As such, they should be
"complete". In this sense, ENVIRONMENT and FILES should be on the
page even if these section contain the information (!) "no
(environment|files)".
For daemon programs SIGNALS should be mandatory, too.
EXAMPLES should be highly recommended, but optional.
ACKNOWLEDGMENTS should go into /usr/doc/... or into some place where we
hide the CREDITS.
Some man-pages really annoy me: they let the text float around the
options so it is really hard to survey. I didn't found an entry in man(7)
which forbids this. :-)
Lars, could you provide a README or something like that ("style guide")
for you sample man-page to cover those aspects? (read: the things you did
well but didn't explain explicitly).
-Winfried
--
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-devel-REQUEST@lists.debian.org . Trouble? e-mail to Bruce@Pixar.com
Reply to: