[man] Fix man page lintian issues

[arif-ali]

This was reported as part of deb packaging in Debian.

---

Please place an 'X' inside each '[]' to confirm you adhere to our Contributor Guidelines

• Is the commit message split over multiple lines and hard-wrapped at 72 characters?
• Is the subject and message clear and concise?
• Does the subject start with [plugin_name] if submitting a plugin patch or a [section_name] if part of the core sosreport code?
• Does the commit contain a Signed-off-by: First Lastname [email protected]?
• Are any related Issues or existing PRs properly referenced via a Closes (Issue) or Resolved (PR) line?
• Are all passwords or private data gathered by this PR obfuscated?

[packit-as-a-service]

Congratulations! One of the builds has completed. 🍾

You can install the built RPMs by following these steps:

• sudo yum install -y dnf-plugins-core on RHEL 8
• sudo dnf install -y dnf-plugins-core on Fedora
• dnf copr enable packit/sosreport-sos-3703
• And now you can install the packages.

Please note that the RPMs should be used only in a testing environment.

[arif-ali]

This came up with the following issue, and hence the change

I: sosreport: acute-accent-in-manual-page [usr/share/man/man1/sos-
report.1.gz:313]
N: 
N:   This manual page uses the \' groff sequence. Usually, the intent is to
N:   generate an apostrophe, but that sequence actually renders as an acute
N:   accent.
N:   
N:   For an apostrophe or a single closing quote, use plain '. For single
N:   opening quote, i.e. a straight downward line ' like the one used in
shell
N:   commands, use '\(aq'.
N:   
N:   In case this tag was emitted for the second half of a '\\' sequence,
this
N:   is indeed no acute accent, but still wrong: A literal backslash should
be
N:   written \e in the groff format, i.e. a '\\' sequence needs to be changed
N:   to '\e' which also won't trigger this tag.
N: 
N:   Please refer to Bug#554897, Bug#507673, and Bug#966803 for details.
N: 
N:   Visibility: info
N:   Show-Always: no
N:   Check: documentation/manual
N:   Renamed from: acute-accent-in-manpage
N: 
N:
I: sosreport: acute-accent-in-manual-page
[usr/share/man/man1/sosreport.1.gz:313]

Below is what was seen in the man page

using ´--plugin-timeout=60 -k logs.timeout=600´ will

[pmoravec]

Nice fix with the \aq

[TurboTurtle]

I don't follow why the underscores are needed? The commands are sos (space) $component, and the underscore to me implies that they would be separate commands e.g. sos_clean, sos_collect, etc...

[arif-ali]

I don't follow why the underscores are needed? The commands are sos (space) $component, and the underscore to me implies that they would be separate commands e.g. sos_clean, sos_collect, etc...

Below were the 2 warning outputs from lintian, and hence updated it, based on this (See Debian bugs #1076253 and #1076347 for full details)

bad-whatis-entry

W: sosreport: bad-whatis-entry [usr/share/man/man1/sos-clean.1.gz]
N: 
N:   A manual page should start with a NAME section, which lists the program
N:   name and a brief description. The NAME section is used to generate a
N:   database that can be queried by commands like apropos and whatis. You are
N:   seeing this tag because lexgrog was unable to parse the NAME section.
N:   
N:   Manual pages for multiple programs, functions, or files should list each
N:   separated by a comma and a space, followed by \- and a common description.
N:   
N:   Listed items may not contain any spaces. A manual page for a two-level
N:   command such as fs listacl must look like fs_listacl so the list is read
N:   correctly.
N: 
N:   Please refer to the lexgrog(1) manual page, the groff_man(7) manual page,
N:   and the groff_mdoc(7) manual page for details.
N: 
N:   Visibility: warning
N:   Show-Always: no
N:   Check: documentation/manual
N:   Renamed from: manpage-has-bad-whatis-entry
N: 
N:
W: sosreport: bad-whatis-entry [usr/share/man/man1/sos-collect.1.gz]
N:
W: sosreport: bad-whatis-entry [usr/share/man/man1/sos-collector.1.gz]
N:
W: sosreport: bad-whatis-entry [usr/share/man/man1/sos-help.1.gz]
N:
W: sosreport: bad-whatis-entry [usr/share/man/man1/sos-mask.1.gz]
N:
W: sosreport: bad-whatis-entry [usr/share/man/man1/sos-report.1.gz]
N:
W: sosreport: bad-whatis-entry [usr/share/man/man1/sosreport.1.gz]

wrong-manual-section

W: sosreport: wrong-manual-section 1 != CLEAN [usr/share/man/man1/sos-
clean.1.gz:1]
N: 
N:   A manual page usually should contain a .TH header, specifying the section.
N:   The section in this manual page doesn't match with the section in the
N:   filename.
N: 
N:   Please refer to the groff_man(7) manual page and the man(1) manual page
N:   for details.
N: 
N:   Visibility: warning
N:   Show-Always: no
N:   Check: documentation/manual
N:   Renamed from: manpage-section-mismatch

W: sosreport: wrong-manual-section 1 != CLEAN [usr/share/man/man1/sos-
mask.1.gz:1]
N:
W: sosreport: wrong-manual-section 1 != COLLECT [usr/share/man/man1/sos-
collect.1.gz:1]
N:
W: sosreport: wrong-manual-section 1 != COLLECT [usr/share/man/man1/sos-
collector.1.gz:1]
N:
W: sosreport: wrong-manual-section 1 != HELP [usr/share/man/man1/sos-
help.1.gz:1]
N:
W: sosreport: wrong-manual-section 1 != REPORT [usr/share/man/man1/sos-
report.1.gz:1]
N:
W: sosreport: wrong-manual-section 1 != REPORT
[usr/share/man/man1/sosreport.1.gz:1]

[arif-ali]

You'll also see the lint messages in the other PR (I still need to fine-tune that PR to fix a few things), and here's the log for that https://api.cirrus-ci.com/v1/task/4983139397795840/logs/main.log (Draft PR #3709)

[TurboTurtle]

Dang, I really dislike the reasoning behind the required use of underscores to an extreme degree, but it is what it is I guess.