lintian 2.5.6 / usr / share / lintian / checks / manpages.desc

Check-Script: manpages
Author: Christian Schwarz <schwarz@debian.org>
Abbrev: man
Type: binary
Needs-Info: unpacked, file-info, index
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> or
 "<tt>../../../share/man/man[237]/undocumented.[237].gz</tt>" for manual
 pages in <tt>/usr/X11R6/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 -9</tt>").
Ref: policy 12.1

Tag: x11-games-should-be-in-usr-games
Severity: important
Certainty: certain
Info: Since X11 games should be installed in <tt>/usr/games</tt> (and
 not in <tt>/usr/X11R6/bin</tt>) and the game's manual pages should be
 installed in <tt>/usr/share/man/man6</tt>, the directory
 <tt>/usr/X11R6/man/man6</tt> should be empty.
Ref: policy 11.11

Tag: manpage-not-compressed-with-gzip
Severity: important
Certainty: certain
Info: Manual pages should be compressed with <tt>gzip -9</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 -9</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 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 <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.
 .
 To test this for yourself you can use the following command:
  LC_ALL=en_US.UTF-8 MANWIDTH=80 man --warnings -E UTF-8 -l &lt;file&gt; &gt;/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 <tt>/usr/X11R6/bin</tt>
 should be installed below <tt>/usr/X11R6/man</tt>.
 .
 Note that normally only packages that are part of X itself and those that
 are using some arcane Imakefiles should actually install binaries into
 <tt>/usr/X11R6/bin</tt>.
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 <tt>/usr/X11R6/bin</tt>
 should not be installed below <tt>/usr/X11R6/man</tt>, but below
 <tt>/usr/share/man</tt>.
 .
 Note that moving a binary into <tt>/usr/X11R6/bin</tt> 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.
 .
 <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: hyphen-used-as-minus-sign
Severity: wishlist
Certainty: possible
Info: This manual page seems to contain a hyphen where a minus sign was
 intended.  By default, "-" 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 and paste options, nor search for them easily.  The Debian groff
 package currently forces "-" to be interpreted as a minus sign due to the
 number of manual pages with this problem, but this is a Debian-specific
 modification and hopefully eventually can be removed.
 .
 "-" must be escaped ("\-") to be interpreted as minus.  If you really
 intend a hyphen (normally you don't), 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,
 this tag may indicate a bug in the tool.  Some tools convert dashes of
 any kind to hyphens.  The safe way of converting dashes is to convert
 them to "\-".
 .
 Because this error can occur <em>very</em> often, Lintian shows 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.
Ref: /usr/share/doc/groff-base/README.Debian, groff_char(7)

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.