Re: How to write a good manpage ?
Am Donnerstag, den 17.08.2006, 15:46 +0300 schrieb Damyan Ivanov:
> Marco Bertorello написа:
> > I always used help2man to generate a manpage for those packages that
> > hasn't one.
> >
> > But now, I'm working on a package that has a non useful help output:
> >
> > $ gcstar --help
> > Usage: /usr/bin/gcstar [[-u|--update [-a|--all] [-c|--collection]
> > [-w|--website] [-i|--import] [-e|--export] [-l|--lang]] | [FILE]]
> >
> > How can I write a manpage good for debian?
>
> /usr/share/doc/man-db/examples/manpage.example
> /usr/share/debhelper/dh_make/debian/manpage.xml.ex
In the case of using this example, please note the following tips when
working with the latest docbook-xsl packages in Sid:
- the mail address belongs into the author tag and you should add the
contrib tag, if the term "Author." does not fit, what you did
- the self-written AUTHOR section should be removed - the section
conflicts with
-> the automatically created AUTHOR section with the info from the
authorgroup|author|editor|othercredit elements
-> the automatically created license and copyright section with the info
from the copyright|legalnotice elements
- the varlistentry/term elements should be used as follows
<term><option>-h</option></term>
<term><option>--help</option></term>
and the output should be controlled via the variablelist.term.separator
and variablelist.term.break.after parameters
> /usr/share/debhelper/dh_make/debian/manpage.sgml.ex
> /usr/share/debhelper/dh_make/debian/manpage.1.ex
>
> (last three from dh-make package)
>
> Except for the synopsis above, you should describe each option's
> meaning and what the program does. Write in the manpage whatever you'd
> expect to read if you face the program for the first time :)
http://www.tldp.org/HOWTO/Man-Page/q3.html
The howto is a good reference, what is at least expected to be found in
the manpage.
Regards, Daniel
Reply to: