htslib-s3-plugin.7: fix whatis entry

[emollier]

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:

$ lexgrog htslib-s3-plugin.7
htslib-s3-plugin.7: parse failed

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:

$ lexgrog htslib-s3-plugin.7
htslib-s3-plugin.7: "htslib-s3-plugin - htslib AWS S3 plugin"

The name could also simply be "s3-plugin", but having htslib in the name felt more apropos. :)

[whitwham]

I see. All our samtools man page follow a similar format. Will these cause similar problems with lintian on samtools?

[emollier]

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:

• there are three words instead of two, and mandb doesn't seem to expand its tolerance to more than two words even if I try to match the left hand item to the manual page file name like "htslib s3 plugin", "htslib-s3 plugin", or "htslib s3-plugin;
• the two words leftover mismatched the manual page filename; perhaps s3-plugin.7 would have worked if it weren't at risk of polluting the namespace of s3 developpers outside samtools context.

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...

[whitwham]

Thank you for the change and thank you for the explanation.