vcs.maemo.org Git - maemian/blob - nokia-lintian/checks/manpages.desc

   1 Check-Script: manpages
   2 Author: Christian Schwarz <schwarz@debian.org>
   3 Abbrev: man
   4 Type: binary
   5 Unpack-Level: 2
   6 Needs-Info: file-info
   7 Info: This script checks if a binary package conforms to manual page policy.
   8
   9 Tag: bad-link-to-undocumented-manpage
  10 Type: error
  11 Info: The symbolic link should reference
  12  `<tt>../man[237]/undocumented.[237].gz</tt>' for manual pages in
  13  <tt>/usr/share/man</tt> or
  14  `<tt>../../../share/man/man[237]/undocumented.[237].gz</tt>' for manual
  15  pages in <tt>/usr/X11R6/man</tt>.
  16
  17 Tag: link-to-undocumented-manpage
  18 Type: warning
  19 Info: Symbolic links to the undocumented(7) manual page may be provided
  20  if no manual page is available, but that is deprecated.
  21  .
  22  The lack of a manual page is still a bug, and if at all possible you
  23  should write one yourself.
  24  .
  25  For help with writing manual pages, refer to the Man-Page-HOWTO at
  26  http://www.schweikhardt.net/man_page_howto.html, the examples created
  27  by <tt>debmake</tt> or <tt>dh_make</tt>, or the
  28  <tt>/usr/share/doc/man-db/examples</tt> directory.
  29  If the package provides <tt>--help</tt> output, you might want to use
  30  the <tt>help2man</tt> utility to generate a simple manual page.
  31 Ref: policy 12.1
  32
  33 Tag: binary-without-manpage
  34 Type: warning
  35 Info: Each binary in <tt>/usr/bin</tt>, <tt>/usr/sbin</tt>, <tt>/bin</tt>,
  36  <tt>/sbin</tt> or <tt>/usr/games</tt> should have a manual page
  37  .
  38  Note that though the man program has the capability to check for
  39  several program names in the NAMES section, each of these programs
  40  should have its own manual page (a symbolic link to the appropriate
  41  manual page is sufficient) because other manual page viewers such as
  42  xman or tkman don't support this.
  43  .
  44  If the name of the man page differs from the binary by case, man may
  45  be able to find it anyway; however, it is still best practice to make the
  46  case of the man page match the case of the binary.
  47  .
  48  If the man pages are provided by another package on which this package
  49  depends, lintian may not be able to determine that man pages are
  50  available.  In this case, after confirming that all binaries do have
  51  man pages after this package and its dependencies are installed, please
  52  add a lintian override.
  53 Ref: policy 12.1
  54
  55 Tag: manpage-in-wrong-directory
  56 Type: error
  57 Info: The manual page should be installed in the correct directory below
  58  <tt>/usr/share/man/</tt> or <tt>/usr/share/man/<i>locale</i></tt>.
  59  Only sections 1 through 9 should be used.
  60  .
  61  The section number in the filename should correspond with the section
  62  number in the directory name.
  63 Ref: policy 12.1
  64
  65 Tag: manpage-has-wrong-extension
  66 Type: error
  67 Info: The manual page has an extension other than
  68  `<i>section</i>[<i>program</i>].gz'.
  69 Ref: policy 13.1
  70
  71 Tag: manpage-not-compressed
  72 Type: error
  73 Info: Manual pages have to be installed compressed (using `<tt>gzip -9</tt>').
  74 Ref: policy 12.1
  75
  76 Tag: x11-games-should-be-in-usr-games
  77 Type: error
  78 Info: Since X11 games should be installed in <tt>/usr/games</tt> (and
  79  not in <tt>/usr/X11R6/bin</tt>) and the game's manual pages should be
  80  installed in <tt>/usr/share/man/man6</tt>, the directory
  81  <tt>/usr/X11R6/man/man6</tt> should be empty.
  82 Ref: policy 11.11
  83
  84 Tag: manpage-not-compressed-with-gzip
  85 Type: error
  86 Info: Manual pages should be compressed with <tt>gzip -9</tt>.
  87 Ref: policy 12.1
  88
  89 Tag: manpage-not-compressed-with-max-compression
  90 Type: error
  91 Info: Manual pages should be compressed with <tt>gzip -9</tt>.
  92 Ref: policy 12.1
  93
  94 Tag: manpage-has-bad-whatis-entry
  95 Type: warning
  96 Info: Each manual page should start with a `NAME' section, which lists the
  97  name and a brief description of the page seperated by '\-'. These sections
  98  are parsed by `mandb' and stored in a database for the use of `apropos' and
  99  `whatis', so they must be in a certain format. This manual page apparently
 100  uses the wrong format and cannot be parsed by `mandb'.
 101  .
 102  For information on how `NAME' sections should be written see lexgrog(1).
 103  See also groff_man(7) and groff_mdoc(7) for general information on writing
 104  manual pages.
 105
 106 Tag: manpage-has-useless-whatis-entry
 107 Type: warning
 108 Info: The whatis entry for this manual page (the brief description found
 109  in the NAME section) is of the form:
 110  .
 111   program - manual page for program
 112  .
 113  This conveys no information about what the program is for and is
 114  repetitive.  The short description should contain brief information about
 115  what the program is for to aid in searching with apropos and similar
 116  programs.
 117  .
 118  If this manpage was generated by help2man, use the -n option to provide a
 119  more meaningful description.
 120
 121 Tag: manpage-is-dh_make-template
 122 Type: error
 123 Info: This manual page appears to be an unmodified or insufficiently
 124  modified copy of the dh_make manual page template.  It has a whatis entry
 125  (the brief description found in the NAME section) of the form:
 126  .
 127   package - program to do something
 128  .
 129  Please double-check the manual page and replace the template language
 130  with specific information about this program.
 131
 132 Tag: manpage-has-errors-from-man
 133 Type: warning
 134 Info: This man page provokes warnings or errors from man.
 135  .
 136  "cannot adjust" or "can't break" are trouble with paragraph filling,
 137  usually related to long lines.  Adjustment can be helped by left
 138  justifying, breaks can be helped with hyphenation, see "Manipulating
 139  Filling and Adjusting" and "Manipulating Hyphenation" in the manual.
 140  .
 141  "can't find numbered character" usually means latin1 etc in the input, and
 142  this warning indicates characters will be missing from the output.  You can
 143  change to escapes like \[:a] described on the groff_char man page.
 144  .
 145  Other warnings are often formatting typos, like missing quotes around a
 146  string argument to .IP.  These are likely to result in lost or malformed
 147  output.  See the groff_man (or groff_mdoc if using mdoc) man page for
 148  information on macros.
 149  .
 150  This test uses <tt>man</tt>'s <tt>--warnings</tt> option to enable groff
 151  warnings that catch common mistakes, such as putting <tt>.</tt> or
 152  <tt>'</tt> characters at the start of a line when they are intended as
 153  literal text rather than groff commands.  This can be fixed either by
 154  reformatting the paragraph so that these characters are not at the start of
 155  a line, or by adding a zero-width space (<tt>\&</tt>) immediately before
 156  them.
 157  .
 158  At worst, warning messages can be disabled with the .warn directive, see
 159  "Debugging" in the groff manual.
 160
 161 Tag: manpage-for-x11-binary-in-wrong-directory
 162 Type: error
 163 Info: Manual pages for binaries which are located in <tt>/usr/X11R6/bin</tt>
 164  should be installed below <tt>/usr/X11R6/man</tt>.
 165  .
 166  Note that normally only packages that are part of X itself and those that
 167  are using some arcane Imakefiles should actually install binaries into
 168  <tt>/usr/X11R6/bin</tt>.
 169
 170 Tag: manpage-for-non-x11-binary-in-wrong-directory
 171 Type: error
 172 Info: Manual pages for binaries that are not located in <tt>/usr/X11R6/bin</tt>
 173  should not be installed below <tt>/usr/X11R6/man</tt>, but below
 174  <tt>/usr/share/man</tt>.
 175  .
 176  Note that moving a binary into <tt>/usr/X11R6/bin</tt> is almost never the
 177  proper solution for this problem; move the manual page instead.
 178
 179 Tag: no-manpage-in-correct-directory
 180 Type: warning
 181 Info: Manpages for executables in /sbin and /usr/sbin should be placed in
 182  section 8; manpages for executables in /bin and /usr/bin in section 1;
 183  manpages for executables in /usr/games in section 6. For the noted
 184  executable some probable manpages were found but none in the right section.
 185  .
 186  This could either mean there is no manpage for the executable or that its
 187  manpage is placed in the wrong section.
 188
 189 Tag: bad-so-link-within-manual-page
 190 Type: error
 191 Info: Manual files that use the .so links to include other pages should
 192  only point to a path relative to the top-level manual hierarchy, e.g.
 193  .
 194  <tt>.so man3/boo.1.gz</tt>
 195
 196 Tag: empty-manual-page
 197 Type: error
 198 Info: The referenced manual page is empty.
 199
 200 Tag: manpage-section-mismatch
 201 Type: warning
 202 Info: A man page usually should contain a <tt>.TH</tt> header, specifying the
 203  section.  The section in this manpage doesn't match with the section in the
 204  filename.  Please consult groff_man(7) for more information about
 205  <tt>.TH</tt> syntax (amongst others).
 206
 207 Tag: hyphen-used-as-minus-sign
 208 Type: info
 209 Info: Manual page seems to contain a hyphen where a minus sign was intended.
 210  '-' chars are interpreted as hyphens (U+2010) by groff, not as minus signs
 211  (U+002D). Since options to programs use minus signs (U+002D), this means for
 212  example in UTF-8 locales that you cannot cut&amp;paste options, nor search for
 213  them easily.
 214  .
 215  '-' must be escaped ('\-') to be interpreted as minus. If you really intend a
 216  hyphen, write it as '\(hy' to emphasise that fact. See groff(7) and
 217  especially groff_char(7) for details, and also the thread starting with
 218  http://lists.debian.org/debian-devel/2003/debian-devel-200303/msg01481.html
 219  .
 220  If you use some tool that converts your documentation to groff format, it
 221  might be possible that this tool converts dashes of any kind to groff
 222  hyphens, while the safe way of converting dashes is usually to convert them
 223  to '\-'.
 224  .
 225  Because this error can occur <em>very</em> often we show only the
 226  first 10 occurrences for each man page and give the number of
 227  suppressed occurrences. If you want to see all warnings, run
 228  lintian with the -d/--debug option.
 229
 230 Tag: FSSTND-dir-in-manual-page
 231 Type: info
 232 Info: The manual page references a directory that is specified
 233  in the FSSTND but not in the FHS which is used by Debian.
 234  This can be an indicator of a mismatch of the location of
 235  files as installed for Debian and as described by the man page.
 236  .
 237  If you have to change file locations to abide by Debian Policy
 238  please also patch the man page to mention these new locations.
 239
 240 Tag: binary-without-english-manpage
 241 Type: warning
 242 Info: Each binary in <tt>/usr/bin</tt>, <tt>/usr/sbin</tt>, <tt>/bin</tt>,
 243  <tt>/sbin</tt> or <tt>/usr/games</tt> should have a manual page. You don't
 244  provide an english, only a translated manpage. Since english is fallback,
 245  shipping only a non-english man page leaves most users without a man page
 246  at all.
 247
 248 Tag: manpage-locale-dir-country-specific
 249 Type: warning
 250 Ref: policy 12.1
 251 Info: This package installs a manual page in a locale directory that
 252  includes the country name.  A country name should not be included in the
 253  directory name unless it indicates a significant difference in the
 254  language.  The known cases where country names are appropriate are pt_BR
 255  and zh_*.  Please file a bug against Lintian if this is another case
 256  where a country name is appropriate.