#643735 lintian: Check that the TH header in manual pages matches FILENAME

Package:
lintian
Source:
lintian
Submitter:
Jari Aalto
Date:
2021-07-04 05:33:05 UTC
Severity:
wishlist
Tags:
#643735#5
Date:
2011-09-29 05:11:40 UTC
From:
To:
An example. Binary name /usr/bin/xsnap-ocr and manpage in
.../man1/xsnap-ocr.1 reads:

!   64  .IX Title "xsnap_ocr 1"
!   65  .TH xsnap_ocr 1 "2011-09-29" "xsnap-ocr" "User Commands"
    66  .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
    67  .\" way too many mistakes in technical documents.
    68  .if n .ad l
    69  .nh
    70  .SH "NAME"
!   71  xsnap_ocr \- OCR reader helper called by xsnap
    72  .SH "SYNOPSIS"

SUGGESTION

It would be nice if there were a P: or X: check to verify that
basename of manual page's filename (without suffix) matches the marked
(!) lines.

The above should have read:

!   64  .IX Title "xsnap-ocr 1"
!   65  .TH xsnap-ocr 1 "2011-09-29" "xsnap-ocr" "User Commands"
    ...
!   71  xsnap-ocr \- OCR reader helper called by xsnap
#643735#10
Date:
2011-10-12 11:27:42 UTC
From:
To:
What about manpages re-used for multiple commands? gzip, gunzip and zcat
uses the same manpage, how would you expect this to be handled?

~Niels
#643735#15
Date:
2011-10-12 11:44:56 UTC
From:
To:
On 2011-10-12 13:27, Niels Thykier wrote:
| On 2011-09-29 07:11, Jari Aalto wrote:
| > Package: lintian
| > Version: 2.5.3
| > Severity: wishlist
| >
| > An example. Binary name /usr/bin/xsnap-ocr and manpage in
| > .../man1/xsnap-ocr.1 reads:
| >
| > !   64  .IX Title "xsnap_ocr 1"
| > !   65  .TH xsnap_ocr 1 "2011-09-29" "xsnap-ocr" "User Commands"
| >     66  .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
| >     67  .\" way too many mistakes in technical documents.
| >     68  .if n .ad l
| >     69  .nh
| >     70  .SH "NAME"
| > !   71  xsnap_ocr \- OCR reader helper called by xsnap
| >     72  .SH "SYNOPSIS"
| >
| > SUGGESTION
| >
| > It would be nice if there were a P: or X: check to verify that
| > basename of manual page's filename (without suffix) matches the marked
| > (!) lines.
| >
| > The above should have read:
| >
| > !   64  .IX Title "xsnap-ocr 1"
| > !   65  .TH xsnap-ocr 1 "2011-09-29" "xsnap-ocr" "User Commands"
| >     ...
| > !   71  xsnap-ocr \- OCR reader helper called by xsnap
| >
| > -- System Information:
| > [...]
|
| What about manpages re-used for multiple commands? gzip, gunzip and zcat
| uses the same manpage, how would you expect this to be handled?

If it were classified "X:" and explanation reads "certainty: not
sure", I don't think there is not much problem.

Jari
#643735#22
Date:
2011-10-12 12:56:05 UTC
From:
To:
I am not convinced there is a point in implementing this tag if we do
not take common cases into consideration.  I do not want X tags to stay
experimental forever and I do not consider this proposal (so far) good
enough to survive as a pedantic/wild-guess.

If we can agree on how we can fairly reliably handle this case without
too many false-positives, I will consider it.  But otherwise I think our
time is better spent on some of the other 170ish bugs.

~Niels
#643735#27
Date:
2011-10-13 05:19:28 UTC
From:
To:
On 2011-10-12 14:56, Niels Thykier wrote:
| On 2011-10-12 13:44, jari wrote:
| > [...]
| >
| > If it were classified "X:" and explanation reads "certainty: not
| > sure", I don't think there is not much problem.
| >
| > Jari
| >
|
| I am not convinced there is a point in implementing this tag if we do
| not take common cases into consideration.  I do not want X tags to stay
| experimental forever and I do not consider this proposal (so far) good
| enough to survive as a pedantic/wild-guess.
|
| If we can agree on how we can fairly reliably handle this case without
| too many false-positives, I will consider it.  But otherwise I think our
| time is better spent on some of the other 170ish bugs.

This can be handled. Take a look at how gzip(1):


    .TH GZIP 1 local
    .SH NAME
    gzip, gunzip, zcat \- compress or expand files
    .SH SYNOPSIS

I guess something like:

    1. Parse binary names from (.SH) up till (-)
    2. Verify that .IX [if exists] and .TH headers match any of the
       found names.
    3. Likewise, verify that the beginning of the filename matches any
       of the found names.

Jari