Re: Lintian and manpage for X app
In my opinion, yes. All debian packages with executables should have
as many man pages as there are executables. That's policy. In my opinion,
all file formats introduced by a package should have a man page in
section 5 which completely describes the format.
Write the man page with a description and pointers to other sources of
documentation which you should probably get and include in the package,
if the license for that documentation allows distribution.
If there is some other way of getting help, make sure they know that
and know how to get to it.
If there is no documentation and no other help, this is a bug. (this
is not the case, is it?)
If there is already lots of ways to get help, list them in the man
page, and you have less to write. if there aren't so many, list those
that exist and fill in the holes in the information as you see them,
and listen to users of your app as well, because the answers to
the questions they ask might be material to go into the documentation.
In your situation, there is or may be other sources of info, and if there
are, then your man page only need describe, refer, and list files, bugs
and authors. But if there is no other source of info, then you have
to provide it.
General opinions meant for the policy list:
The man pages in a package are essential because debian is a flavor of
unix. When looking at a unix command -- which is what we all package --
the man page is often the only thing that exists, and this kind of
man page has to be comprehensive, trying to catch every nuance. In my
case and in the case of other developers and users, man <executableName>
is the very first thing I type after installing whichever package. I find
it frustrating when there is no man page, because then I have to go to
the (known to be useless in most cases) /usr/doc heirarchy. This is use-
less because there is normally not much but a copyright file. I found
the copyright file to be useful I think exactly once. I have hoped tho,
in the useless cases, that my final try of looking at the copyright file
would yield more sources of docs or maybe the author's page covering the
package. It was a last-chance try for something useful, so I tried it...
-Jim
---
Jim Lynch Finger for pgp key
as Laney College CIS admin: jim@laney.edu http://www.laney.edu/~jim/
as Debian developer: jwl@debian.org http://www.debian.org/~jwl/
Reply to: