Re: policy summary (new packages without man pages)
On Tue, 18 Jan 2000, Matthew Vernon wrote:
> It's tricky to write a decent manpage if you know no nroff.
You don't have to learn all the nroff macros to write a simple man
page! Have a look at the manpage-HOWTO
(http://www.schweikhardt.net/man_page_howto.html) or man(7) and you
will see, that you need a very limited set of macros to write man
pages. IMHO this can be learned in only one hour (or less) and it is
not harder than learning how to write a control file or how to write a
docbase file or something like this. And don't forget, that you don't
have to learn it again for every man page, you can reuse your
knowledge for every new man page ;-)
> Besides foo --help is often all you need to get at least basic
> functionality from a package.
So use help2man and add a short description what this binary does.
Should a user start an unknown program foo with the option --help only
to find out, that --help isn't supported, but foo always removes/files
some files in his home?
Before I start an unknown program, I want to know, what it is expected
to do. For this I need a man page, where I can find out, what the
program does (at least a link to some documentation, which tells me).
> Or, in the case of beta software, the author says "Developers should
> be able to manage with the commented header file. I'll write more
> documentation at a later stage", I'm inclined to agree with
> upstream, and provide the header file in the appropriate place, with
> a comment in Readme.Debian.
And why can't you write this into a man page? BTW: the upstream
maintainer will be happy, if you help him writing the documentation,
so he can concentrate on improving the program.
Ciao
Roland
--
* roland@spinnaker.de * http://www.spinnaker.de/ *
Reply to: