Check-Script: manpages Author: Christian Schwarz Abbrev: man Type: binary Unpack-Level: 2 Needs-Info: 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 "../man[237]/undocumented.[237].gz" for manual pages in /usr/share/man or "../../../share/man/man[237]/undocumented.[237].gz" for manual pages in /usr/X11R6/man. 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 debmake or dh_make, or the /usr/share/doc/man-db/examples directory. If the package provides --help output, you might want to use the help2man utility to generate a simple manual page. Ref: policy 12.1 Tag: binary-without-manpage Severity: normal Certainty: possible Info: Each binary in /usr/bin, /usr/sbin, /bin, /sbin or /usr/games 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 /usr/share/man/ or /usr/share/man/locale. 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 "section[program].gz". Ref: policy 12.1 Tag: manpage-not-compressed Severity: important Certainty: certain Info: Manual pages have to be installed compressed (using "gzip -9"). Ref: policy 12.1 Tag: x11-games-should-be-in-usr-games Severity: important Certainty: certain Info: Since X11 games should be installed in /usr/games (and not in /usr/X11R6/bin) and the game's manual pages should be installed in /usr/share/man/man6, the directory /usr/X11R6/man/man6 should be empty. Ref: policy 11.11 Tag: manpage-not-compressed-with-gzip Severity: important Certainty: certain Info: Manual pages should be compressed with gzip -9. Ref: policy 12.1 Tag: manpage-not-compressed-with-max-compression Severity: important Certainty: certain Info: Manual pages should be compressed with gzip -9. 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 "\-". These sections are parsed by "mandb" and stored in a database for the use of "apropos" and "whatis", so they must be in a certain format. This manual page apparently uses the wrong format and cannot be parsed by "mandb". 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 manual. . "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 man's --warnings option to enable groff warnings that catch common mistakes, such as putting . or ' 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 (\&) immediately before them. . At worst, warning messages can be disabled with the .warn directive, see "Debugging" in the groff manual. . To test this for yourself you can use the following command: LANG=C man --warnings -l manpage-file >/dev/null 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: manpage-for-x11-binary-in-wrong-directory Severity: important Certainty: certain Info: Manual pages for binaries which are located in /usr/X11R6/bin should be installed below /usr/X11R6/man. . Note that normally only packages that are part of X itself and those that are using some arcane Imakefiles should actually install binaries into /usr/X11R6/bin. Ref: fhs usrsharemanmanualpages Tag: manpage-for-non-x11-binary-in-wrong-directory Severity: important Certainty: certain Info: Manual pages for binaries that are not located in /usr/X11R6/bin should not be installed below /usr/X11R6/man, but below /usr/share/man. . Note that moving a binary into /usr/X11R6/bin is almost never the proper solution for this problem; move the manual page instead. Ref: fhs usrsharemanmanualpages 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. . .so man3/boo.1.gz 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 .TH 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: hyphen-used-as-minus-sign Severity: wishlist Certainty: certain Info: Manual page seems to contain a hyphen where a minus sign was intended. "-" chars are interpreted as hyphens (U+2010) by groff, not as minus signs (U+002D). Since options to programs use minus signs (U+002D), this means for example in UTF-8 locales that you cannot cut&paste options, nor search for them easily. . "-" must be escaped ("\-") to be interpreted as minus. If you really intend a hyphen, write it as "\(hy" to emphasise that fact. See groff(7) and especially groff_char(7) for details, and also the thread starting with http://lists.debian.org/debian-devel/2003/debian-devel-200303/msg01481.html . If you use some tool that converts your documentation to groff format, it might be possible that this tool converts dashes of any kind to groff hyphens, while the safe way of converting dashes is usually to convert them to "\-". . Because this error can occur very often we show only the first 10 occurrences for each man page and give the number of suppressed occurrences. If you want to see all warnings, run lintian with the -d/--debug option. 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 /usr/bin, /usr/sbin, /bin, /sbin or /usr/games 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 Maemian if this is another case where a country name is appropriate.