Skip Menu |

This queue is for tickets about the KinoSearch CPAN distribution.

Report information
The Basics
Id: 57230
Status: resolved
Priority: 0/
Queue: KinoSearch
People
Owner: Nobody in particular
Requestors: JAWNSY [...] cpan.org
Cc:
AdminCc:
Bug Information
Severity: Normal
Broken in: (no value)
Fixed in: (no value)

History Show all quoted text
  Wed May 05 12:30:17 2010 JAWNSY [...] cpan.org - Ticket created
Subject: Missing whatis entries
Hi there: Thanks for your contribution to the CPAN. This issue affects both the main KinoSearch branch (current version 0.165) as well as its fork (KinoSearch1 version 1.00). While packaging your module for Debian, I had some issues due to documentation -- 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/KinoSearch/ - 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: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::CompoundFileReader.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: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::CompoundFileWriter.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::DelDocs.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::FieldInfos.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::FieldsReader.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::FieldsWriter.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::IndexFileNames.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::IndexReader.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::MultiReader.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::MultiTermDocs.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::NormsReader.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::PostingsWriter.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::SegInfos.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::SegReader.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::SegTermDocs.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::SegTermEnum.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::SegWriter.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::TermBuffer.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::TermDocs.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::TermEnum.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::TermInfo.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::TermInfosReader.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::TermInfosWriter.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Index::TermVector.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Search::BooleanClause.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Search::BooleanScorer.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Search::HitCollector.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Search::HitQueue.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Search::PhraseScorer.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Search::Scorer.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Search::Searchable.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Search::Similarity.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Search::TermScorer.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Search::Weight.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Store::FSLock.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Store::InStream.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Store::Lock.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Store::OutStream.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Store::RAMLock.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Util::BitVector.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Util::ByteBuf.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Util::CClass.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Util::Carp.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Util::IntMap.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Util::MathUtils.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Util::MemManager.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Util::PriorityQueue.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Util::SortExternal.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Util::StringHelper.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Util::ToStringUtils.3pm.gz W: libkinosearch-perl: manpage-has-bad-whatis-entry usr/share/man/man3/KinoSearch::Util::VerifyArgs.3pm.gz The lintian software also picked up a spelling error: I: libkinosearch-perl: spelling-error-in-manpage usr/share/man/man3/KinoSearch::Searcher.3pm.gz noticable noticeable 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
  Wed May 05 21:52:38 2010 marvin [...] rectangular.com - Correspondence added
CC: undisclosed-recipients: ;
Subject: Re: [rt.cpan.org #57230] Missing whatis entries
Date: Wed, 5 May 2010 18:52:26 -0700
To: Jonathan Yu via RT <bug-KinoSearch [...] rt.cpan.org>
From: Marvin Humphrey <marvin [...] rectangular.com>
On Wed, May 05, 2010 at 12:30:18PM -0400, Jonathan Yu via RT wrote: Show quoted text
> For many of your modules, the so-called "whatis" entries are missing -- > these are entries used by apropos and mandb.
All of the modules that are listed in your report are private. It would be bad if man pages get generated for them. All POD within the modules in question is bracketed by =begin/=end to indicate that the content is only for "devdocs". =begin devdocs =head1 NAME KinoSearch1::Search::HitQueue - track highest scoring docs =head1 DESCRIPTION ... =end devdocs =cut Show quoted text
> They are essentially a > short description arranged in your POD like so: > > =head1 NAME > > Module::Name - thingy to do stuff
Your tool is detecting that POD exists, but is correctly ignoring all content since everything is in between =begin and =end. That's why it doesn't see the "=head1 NAME" block. The desired outcome is to have your tool ignore these private modules. With search.cpan.org and PAUSE, that's achieved by listing the packages under "no_index" within the META.yml file. Will your tool obey that directive? Currently KinoSearch1 1.00 and KinoSearch 0.165 do not have no_index entries within META.yml. (Only the last few releases of the dev branch, 0.30_xx, have no_index entries.) I would be happy to make new releases for those two packages to address that. As an alternate solution, I can just munge the POD for these private modules so that your tool won't detect it, e.g. by inserting an extra "=". ==begin devdocs ==head1 NAME KinoSearch1::Search::HitQueue - track highest scoring docs That's kind of dirty, but this POD isn't used anywhere so it's not a big deal if we have to resort to that. (I've never actually done something like generate HTML for all POD including "devdocs", and in the dev branch, all of this content has moved out of the .pm files). Marvin Humphrey
  Wed May 05 21:52:40 2010 The RT System itself - Status changed from 'new' to 'open'
  Wed May 05 22:16:00 2010 JAWNSY [...] cpan.org - Correspondence added
Hi Marvin, Show quoted text
> All of the modules that are listed in your report are private. It > would be > bad if man pages get generated for them. > > All POD within the modules in question is bracketed by =begin/=end to > indicate that the content is only for "devdocs".
Fair enough, I didn't notice this. I can simply remove the generated manpages so there is no problem in this case. A final nitpick about the spelling error I mentioned in the initial e-mail, as Lintian picked that up: I: libkinosearch-perl: spelling-error-in-manpage usr/share/man/man3/KinoSearch::Searcher.3pm.gz noticable noticeable (What that means is the POD for KinoSearch::Searcher has a typo, 'noticable' is where 'noticeable' should be) Thanks for your help & I apologize for not noticing the private nature of those modules beforehand (so sorry about the noise, and thanks for your enlightening response!) Cheers, Jonathan
  Wed May 05 22:22:35 2010 JAWNSY [...] cpan.org - Correspondence added
I should clarify that I can just patch the spelling issue for now, I just thought it'd be good for you to know so you can fix it for subsequent releases (obviously this is a silly thing to cut a new release for) Thanks again for your help here. I've almost finished the packaging work for KinoSearch1 for Debian, and look forward to working with you in the future to minimize the impact KinoSearch3 might have for our applications. (None of this would have been possible if you didn't drop by the MojoMojo channel the other day, so thanks very much for that, and thanks for working on KinoSearch) On Wed May 05 22:16:00 2010, JAWNSY wrote: Show quoted text
> Hi Marvin, >
> > All of the modules that are listed in your report are private. It > > would be > > bad if man pages get generated for them. > > > > All POD within the modules in question is bracketed by =begin/=end to > > indicate that the content is only for "devdocs".
> > Fair enough, I didn't notice this. I can simply remove the generated > manpages so there is no problem in this case. > > A final nitpick about the spelling error I mentioned in the initial > e-mail, as Lintian picked that up: > I: libkinosearch-perl: spelling-error-in-manpage > usr/share/man/man3/KinoSearch::Searcher.3pm.gz noticable noticeable > > (What that means is the POD for KinoSearch::Searcher has a typo, > 'noticable' is where 'noticeable' should be) > > Thanks for your help & I apologize for not noticing the private nature > of those modules beforehand (so sorry about the noise, and thanks for > your enlightening response!) > > Cheers, > > Jonathan
  Thu May 06 11:28:45 2010 marvin [...] rectangular.com - Correspondence added
CC: undisclosed-recipients: ;
Subject: Re: [rt.cpan.org #57230] Missing whatis entries
Date: Thu, 6 May 2010 08:28:30 -0700
To: Jonathan Yu via RT <bug-KinoSearch [...] rt.cpan.org>
From: Marvin Humphrey <marvin [...] rectangular.com>
On Wed, May 05, 2010 at 10:22:36PM -0400, Jonathan Yu via RT wrote: Show quoted text
> I should clarify that I can just patch the spelling issue for now, I > just thought it'd be good for you to know so you can fix it for > subsequent releases (obviously this is a silly thing to cut a new > release for)
I appreciate the attention to detail -- if that weren't the case, we'd have had more misspellings. :) Fix committed to both branches. Show quoted text
> I can simply remove the generated manpages so there is no problem in this > case.
OK, glad that will work. Cheers, Marvin Humphrey
  Tue May 11 20:28:34 2010 JAWNSY [...] cpan.org - Correspondence added
This issue has been avoided by removing the generated manpages, so I'm marking this bug as resolved. Thanks for your help and clarification :)
  Tue May 11 20:28:39 2010 JAWNSY [...] cpan.org - Status changed from 'open' to 'resolved'