+++ /dev/null
-Check-Script: manpages
-Author: Christian Schwarz <schwarz@debian.org>
-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
-Type: error
-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
-Type: warning
-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>debmake</tt> or <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
-Type: warning
-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
-Type: error
-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
-Type: error
-Info: The manual page has an extension other than
- `<i>section</i>[<i>program</i>].gz'.
-Ref: policy 13.1
-
-Tag: manpage-not-compressed
-Type: error
-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
-Type: error
-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
-Type: error
-Info: Manual pages should be compressed with <tt>gzip -9</tt>.
-Ref: policy 12.1
-
-Tag: manpage-not-compressed-with-max-compression
-Type: error
-Info: Manual pages should be compressed with <tt>gzip -9</tt>.
-Ref: policy 12.1
-
-Tag: manpage-has-bad-whatis-entry
-Type: warning
-Info: Each manual page should start with a `NAME' section, which lists the
- name and a brief description of the page seperated 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'.
- .
- For information on how `NAME' sections should be written see lexgrog(1).
- See also groff_man(7) and groff_mdoc(7) for general information on writing
- manual pages.
-
-Tag: manpage-has-useless-whatis-entry
-Type: warning
-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
-Type: error
-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
-Type: warning
-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.
-
-Tag: manpage-for-x11-binary-in-wrong-directory
-Type: error
-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>.
-
-Tag: manpage-for-non-x11-binary-in-wrong-directory
-Type: error
-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.
-
-Tag: no-manpage-in-correct-directory
-Type: warning
-Info: Manpages for executables in /sbin and /usr/sbin should be placed in
- section 8; manpages for executables in /bin and /usr/bin in section 1;
- manpages for executables in /usr/games in section 6. For the noted
- executable some probable manpages were found but none in the right section.
- .
- This could either mean there is no manpage for the executable or that its
- manpage is placed in the wrong section.
-
-Tag: bad-so-link-within-manual-page
-Type: error
-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
-Type: error
-Info: The referenced manual page is empty.
-
-Tag: manpage-section-mismatch
-Type: warning
-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. Please consult groff_man(7) for more information about
- <tt>.TH</tt> syntax (amongst others).
-
-Tag: hyphen-used-as-minus-sign
-Type: info
-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 <em>very</em> 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
-Type: info
-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
-Type: warning
-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
-Type: warning
-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.
projects / maemian / blobdiff