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