Linux puskom-ProLiant-DL385-Gen10 5.4.0-150-generic #167~18.04.1-Ubuntu SMP Wed May 24 00:51:42 UTC 2023 x86_64
/
usr
/
share
/
lintian
/
checks
/
//usr/share/lintian/checks/manpages.desc
Check-Script: manpages Author: Christian Schwarz <schwarz@debian.org> Abbrev: man Type: binary Needs-Info: unpacked, file-info Info: This script checks if a binary package conforms to manual page policy. Tag: bad-link-to-undocumented-manpage Severity: important Certainty: certain Info: The symbolic link should reference "<tt>../man[237]/undocumented.[237].gz</tt>" for manual pages in <tt>/usr/share/man</tt>. Tag: link-to-undocumented-manpage Severity: normal Certainty: certain Info: Symbolic links to the undocumented(7) manual page may be provided if no manual page is available, but that is deprecated. . The lack of a manual page is still a bug, and if at all possible you should write one yourself. . For help with writing manual pages, refer to the Man-Page-HOWTO at http://www.schweikhardt.net/man_page_howto.html, the examples created by <tt>dh_make</tt>, or the <tt>/usr/share/doc/man-db/examples</tt> directory. If the package provides <tt>--help</tt> output, you might want to use the <tt>help2man</tt> utility to generate a simple manual page. Ref: policy 12.1 Tag: binary-without-manpage Severity: normal Certainty: possible Info: Each binary in <tt>/usr/bin</tt>, <tt>/usr/sbin</tt>, <tt>/bin</tt>, <tt>/sbin</tt> or <tt>/usr/games</tt> should have a manual page . Note that though the man program has the capability to check for several program names in the NAMES section, each of these programs should have its own manual page (a symbolic link to the appropriate manual page is sufficient) because other manual page viewers such as xman or tkman don't support this. . If the name of the man page differs from the binary by case, man may be able to find it anyway; however, it is still best practice to make the case of the man page match the case of the binary. . If the man pages are provided by another package on which this package depends, Lintian may not be able to determine that man pages are available. In this case, after confirming that all binaries do have man pages after this package and its dependencies are installed, please add a Lintian override. Ref: policy 12.1 Tag: manpage-in-wrong-directory Severity: important Certainty: certain Info: The manual page should be installed in the correct directory below <tt>/usr/share/man/</tt> or <tt>/usr/share/man/<i>locale</i></tt>. Only sections 1 through 9 should be used. . The section number in the filename should correspond with the section number in the directory name. Ref: policy 12.1 Tag: manpage-has-wrong-extension Severity: important Certainty: certain Info: The manual page has an extension other than "<i>section</i>[<i>program</i>].gz". Ref: policy 12.1 Tag: manpage-not-compressed Severity: important Certainty: certain Info: Manual pages have to be installed compressed (using "<tt>gzip -9n</tt>"). Ref: policy 12.1 Tag: manpage-not-compressed-with-gzip Severity: important Certainty: certain Info: Manual pages should be compressed with <tt>gzip -9n</tt>. Ref: policy 12.1 Tag: manpage-not-compressed-with-max-compression Severity: important Certainty: certain Info: Manual pages should be compressed with <tt>gzip -9n</tt>. Ref: policy 12.1 Tag: manpage-has-bad-whatis-entry Severity: normal Certainty: certain Info: Each manual page should start with a "NAME" section, which lists the name and a brief description of the page separated by "\-". The "NAME" section is parsed by lexgrog and used to generate a database that's queried by commands like apropos and whatis. This tag indicates that lexgrog was unable to parse the NAME section of this manual page. . For manual pages that document multiple programs, functions, files, or other things, the part before "\-" should list each separated by a comma and a space. Each thing listed must not contain spaces; a man page for a two-part command like "fs listacl" must use something like "fs_listacl" in the "NAME" section so that it can be parsed by lexgrog. Ref: lexgrog(1), groff_man(7), groff_mdoc(7) Tag: manpage-has-useless-whatis-entry Severity: normal Certainty: certain Info: The whatis entry for this manual page (the brief description found in the NAME section) is of the form: . program - manual page for program . This conveys no information about what the program is for and is repetitive. The short description should contain brief information about what the program is for to aid in searching with apropos and similar programs. . If this manpage was generated by help2man, use the -n option to provide a more meaningful description. Tag: manpage-is-dh_make-template Severity: important Certainty: certain Info: This manual page appears to be an unmodified or insufficiently modified copy of the dh_make manual page template. It has a whatis entry (the brief description found in the NAME section) of the form: . package - program to do something . Please double-check the manual page and replace the template language with specific information about this program. Tag: manpage-has-errors-from-man Severity: normal Certainty: certain Info: This man page provokes warnings or errors from man. . "cannot adjust" or "can't break" are trouble with paragraph filling, usually related to long lines. Adjustment can be helped by left justifying, breaks can be helped with hyphenation, see "Manipulating Filling and Adjusting" and "Manipulating Hyphenation" in the groff manual (see info groff). . "can't find numbered character" usually means latin1 etc in the input, and this warning indicates characters will be missing from the output. You can change to escapes like \[:a] described on the groff_char man page. . Other warnings are often formatting typos, like missing quotes around a string argument to .IP. These are likely to result in lost or malformed output. See the groff_man (or groff_mdoc if using mdoc) man page for information on macros. . This test uses <tt>man</tt>'s <tt>--warnings</tt> option to enable groff warnings that catch common mistakes, such as putting <tt>.</tt> or <tt>'</tt> characters at the start of a line when they are intended as literal text rather than groff commands. This can be fixed either by reformatting the paragraph so that these characters are not at the start of a line, or by adding a zero-width space (<tt>\&</tt>) immediately before them. . At worst, warning messages can be disabled with the .warn directive, see "Debugging" in the groff manual. . Lintian also stricter in regards to declaring manpage preprocessors. . To test this for yourself you can use the following command: LC_ALL=en_US.UTF-8 MANROFFSEQ='' MANWIDTH=80 \ man --warnings -E UTF-8 -l -Tutf8 -Z <file> >/dev/null Ref: groff_man(7), groff_mdoc(7) Tag: manpage-has-errors-from-pod2man Severity: normal Certainty: certain Info: This man page contains a section "POD ERRORS" generated by pod2man. This sections lists errors in the POD syntax found by pod2man during the generation of the man page. Tag: bad-so-link-within-manual-page Severity: important Certainty: certain Info: Manual files that use the .so links to include other pages should only point to a path relative to the top-level manual hierarchy, e.g. . <tt>.so man3/boo.1.gz</tt> Tag: empty-manual-page Severity: important Certainty: certain Info: The referenced manual page is empty. Tag: manpage-section-mismatch Severity: normal Certainty: certain Info: A man page usually should contain a <tt>.TH</tt> header, specifying the section. The section in this manpage doesn't match with the section in the filename. Ref: groff_man(7), man(1) Tag: FSSTND-dir-in-manual-page Severity: wishlist Certainty: certain Info: The manual page references a directory that is specified in the FSSTND but not in the FHS which is used by Debian. This can be an indicator of a mismatch of the location of files as installed for Debian and as described by the man page. . If you have to change file locations to abide by Debian Policy please also patch the man page to mention these new locations. Tag: binary-without-english-manpage Severity: normal Certainty: certain Info: Each binary in <tt>/usr/bin</tt>, <tt>/usr/sbin</tt>, <tt>/bin</tt>, <tt>/sbin</tt> or <tt>/usr/games</tt> should have a manual page. You don't provide an English, only a translated manpage. Since English is fallback, shipping only a non-English man page leaves most users without a man page at all. Tag: manpage-locale-dir-country-specific Severity: normal Certainty: certain Ref: policy 12.1 Info: This package installs a manual page in a locale directory that includes the country name. A country name should not be included in the directory name unless it indicates a significant difference in the language. The known cases where country names are appropriate are pt_BR and zh_*. Please file a bug against Lintian if this is another case where a country name is appropriate. Tag: spelling-error-in-manpage Severity: minor Certainty: possible Info: Lintian found a spelling error in the manpage. Lintian has a list of common misspellings that it looks for. It does not have a dictionary like a spelling checker does. . If the string containing the spelling error is translated with the help of gettext (with the help of po4a, for example) or a similar tool, please fix the error in the translations as well as the English text to avoid making the translations fuzzy. With gettext, for example, this means you should also fix the spelling mistake in the corresponding msgids in the *.po files. Tag: manpage-named-after-build-path Severity: important Certainty: certain Info: The manual page appears to be named after its build path and not after its content. . Please check your debian/rules or upstream Makefile. Tag: manpage-has-overly-generic-name Severity: important Certainty: certain Info: The manual page appears to have an overly generic name that is likely to clash with other packages. . Please check your debian/rules or upstream Makefile.