Closed emollier closed 1 year ago
I see. All our samtools man page follow a similar format. Will these cause similar problems with lintian on samtools?
That's a good question.
I went through samtools subcommand manual pages, and they do not raise issues with the mandb. Although lexgrog does choke on them, e.g.:
$ lexgrog samtools-mpileup.1
samtools-mpileup.1: parse failed
apropos and whatis do manage to locate the manuals:
$ apropos samtools-mpileup
samtools-mpileup (1) - produces "pileup" textual format from an alignment
Since the whatis entries are usable, they do not raise any lintian notification. So you can safely not worry about them. :)
So in spite of what lexgrog manual states:
On the left-hand side, there may be several names, separated by commas. Names containing whitespace will be ignored to avoid pathological behaviour on certain ill-formed NAME sections.
my initial assumption about white spaces was partially wrong with mandb. The mandb seems more relaxed and tolerates two words, as it's a common pattern for documenting subcommands I suppose. What seems to happen however, is simply that the left hand item in the whatis entry "s3 plugin" mismatches the manual page file name "htslib-s3-plugin.7". So, after doing further experiments, htslib-s3-plugin.7 is kind of a special case for two reasons:
Also, my initial thought about using "s3-plugin" instead of "htslib-s3-plugin" was wrong, as the mismatch between the file name. So in the end "htslib-s3-plugin" is the only remaining way to go.
In hope this clarifies things...
Thank you for the change and thank you for the explanation.
When preparing the htslib 1.17 upload in Debian, lintian caught a bad-whatis-entry issue. Looking closer, whatis(1) and apropos(1) commands fail to locate htslib-s3-plugin(7) manual and the parsing of the page fails with:
It seems to stem from the two words "s3 plugin" in the name of the manual, instead of having a single word as needed. This change names the manual page "htslib-s3-plugin" instead, making the mandb, the lexgrog parser, and lintian happy:
The name could also simply be "s3-plugin", but having htslib in the name felt more apropos. :)