| Subject: | Missing whatis entries |
Hi there:
I'm having trouble finishing the packaging of Dancer due to some
documentation issues -- they're sort of unimportant and probably
wouldn't stop us from uploading the package if we really wanted, but it
would be better to have this in place.
For many of your modules, the so-called "whatis" entries are missing --
these are entries used by apropos and mandb. They are essentially a
short description arranged in your POD like so:
=head1 NAME
Module::Name - thingy to do stuff
It is common convention that the dash reads like "is a", so the whatis
entry must start with a noun; in the above example: "Module::Name is a
thingy to do stuff"
Incidentally, these whatis entries are also displayed in your
distribution page next to module names:
http://search.cpan.org/dist/Dancer/ - It's really useful for giving
people a quick idea of what each module does and how it fits into the
overall design of the package as a whole.
This description from lintian, one of Debian's Quality Assurance tools,
might also be informative:
W: libdancer-perl: manpage-has-bad-whatis-entry
usr/share/man/man3/Dancer::Plugin.3pm.gz
N:
N: Each manual page should start with a "NAME" section, which lists the
N: name and a brief description of the page separated by "\-". The "NAME"
N: section is parsed by lexgrog and used to generate a database that's
N: queried by commands like apropos and whatis. This tag indicates that
N: lexgrog was unable to parse the NAME section of this manual page.
N:
N: For manual pages that document multiple programs, functions, files, or
N: other things, the part before "\-" should list each separated by a
comma
N: and a space. Each thing listed must not contain spaces; a man page
for a
N: two-part command like "fs listacl" must use something like
"fs_listacl"
N: in the "NAME" section so that it can be parsed by lexgrog.
N:
N: Refer to the lexgrog(1) manual page, the groff_man(7) manual page, and
N: the groff_mdoc(7) manual page for details.
N:
N: Severity: normal, Certainty: certain
N:
W: libdancer-perl: manpage-has-bad-whatis-entry
usr/share/man/man3/Dancer::Serializer::JSON.3pm.gz
W: libdancer-perl: manpage-has-bad-whatis-entry
usr/share/man/man3/Dancer::Serializer::Mutable.3pm.gz
W: libdancer-perl: manpage-has-bad-whatis-entry
usr/share/man/man3/Dancer::Serializer::YAML.3pm.gz
I hope to hear from you soon, as I'd like to get this package into
Debian as quickly as possible, and this would be a great help for us.
Cheers,
Jonathan
On behalf of the Debian Perl team