| Subject: | Missing whatis entries |
Hi there:
First off, thanks very much for your contribution to CPAN. Your module
looks really neat and I was hoping to use it to generate some of my own
graphs when I had some more free time for hacking.
I'm currently packaging your module for Debian because I think it will
be quite useful for a lot of people. One issue I'm having right now is
all the so-called "whatis" entries that are missing from your package.
Whatis entries are used by apropos and mandb, and are 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/Chart-Clicker/ - 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. As of writing (version
2.60), only Chart::Clicker itself and Chart::Clicker::Positioned have
whatis entries.
This description from lintian, one of Debian's Quality Assurance tools,
might also be informative:
W: libchart-clicker-perl: manpage-has-bad-whatis-entry
usr/share/man/man3/Chart::Clicker::Axis.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
I hope to hear from you soon, as I'd like to get this package into
Debian as quickly as possible. I've already packaged all of
Chart::Clicker's dependencies, so the module itself is the last piece in
the puzzle.
Cheers,
Jonathan