Adding upstream version 2.117.0.upstream/2.117.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 785 insertions, 0 deletions

diff --git a/man/lintian.pod b/man/lintian.pod
new file mode 100644
index 0000000..5204aee
--- /dev/null
+++ b/man/lintian.pod
@@ -0,0 +1,785 @@
+# Copyright (C) 2010 Niels Thykier
+# Copyright (C) 2017, 2019 Chris Lamb <lamby@debian.org>
+#  - based on the work Richard Braakman and Christian
+#    Schwarz (copyrighted 1998).
+#
+# This manual page is free software.  It is distributed under the
+# terms of the GNU General Public License as published by the Free
+# Software Foundation; either version 2 of the License, or (at your
+# option) any later version.
+#
+# This manual page is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this manual page; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
+# USA
+#
+
+=head1 NAME
+
+lintian - Static analysis tool for Debian packages
+
+=head1 SYNOPSIS
+
+B<lintian> [I<action>] [I<options>] [I<packages>] ...
+
+=head1 DESCRIPTION
+
+Lintian dissects Debian packages and reports bugs and policy
+violations.  It contains automated checks for many aspects of Debian
+policy as well as some checks for common errors.
+
+There are two ways to specify binary, udeb or source packages for
+Lintian to process: by file name (the .deb file for a binary package
+or the .dsc file for a source package), or by naming a I<.changes>
+file.
+
+If you specify a I<.changes> file, Lintian will process all packages
+listed in that file.  This is convenient when checking a new package
+before uploading it.
+
+If you specify packages to be checked or use the option
+B<--packages-from-file>, the packages requested will be processed.
+Otherwise, if I<debian/changelog> exists, it is parsed to determine
+the name of the .changes file to look for in the parent directory.
+See L</CHECKING LAST BUILD> for more information.
+
+
+=head1 OPTIONS
+
+Actions of the lintian command: (Only one action can be specified per invocation)
+
+=over 4
+
+=item B<-c>, B<--check>
+
+Run all checks over the specified packages.  This is the default action.
+
+=item B<-C> chk1,chk2,..., B<--check-part> chk1,chk2,...
+
+Run only the specified checks.  You can either specify the name of the
+check script or the abbreviation.  For details, see the L</CHECKS> section
+below.
+
+=item B<-F>, B<--ftp-master-rejects>
+
+Run only the checks that issue tags that result in automatic rejects
+from the Debian upload queue.  The list of such tags is refreshed with
+each Lintian release, so may be slightly out of date if it has changed
+recently.
+
+This is implemented via a profile and thus this option cannot be used
+together with B<--profile>.
+
+=item B<-T> tag1,tag2,..., B<--tags> tag1,tag2,...
+
+Run only the checks that issue the requested tags.  The tests for
+other tags within the check scripts will be run but the tags will not
+be issued.
+
+With this options all tags listed will be displayed regardless of the
+display settings.
+
+=item B<--tags-from-file> filename
+
+Same functionality as B<--tags>, but read the list of tags from a
+file.  Blank lines and lines beginning with # are ignored.  All other
+lines are taken to be tag names or comma-separated lists of tag names
+to (potentially) issue.
+
+With this options all tags listed will be displayed regardless of the
+display settings.
+
+=item B<-X> chk1,chk2,..., B<--dont-check-part> chk1,chk2,...
+
+Run all but the specified checks.  You can either specify the name
+of the check script or the abbreviation.  For details, see the
+L</CHECKS> section below.
+
+=back
+
+General options:
+
+=over 4
+
+=item B<-h>, B<--help>
+
+Display usage information and exit.
+
+=item B<-q>, B<--quiet>
+
+Suppress all informational messages including override comments
+(normally shown with B<--show-overrides>).
+
+This option is silently ignored if B<--debug> is given.  Otherwise, if
+both B<--verbose> and B<--quiet> is used, the last of these two options
+take effect.
+
+This option overrides the B<verbose> and the B<quiet> variable in the
+configuration file.  In the configuration file, this option is enabled
+by using B<quiet> variable.  The B<verbose> and B<quiet> variables may
+not both appear in the config file.
+
+=item B<-v>, B<--verbose>
+
+Display verbose messages.
+
+If B<--debug> is used this option is always enabled.  Otherwise, if
+both B<--verbose> and B<--quiet> is used (and B<--debug> is not used),
+the last of these two options take effect.
+
+This option overrides the B<quiet> variable in the configuration file.
+In the configuration file, this option is enabled by using B<verbose>
+variable.  The B<verbose> and B<quiet> variables may not both appear
+in the config file.
+
+=item B<-V>, B<--version>
+
+Display lintian version number and exit.
+
+=item B<--print-version>
+
+Print unadorned version number and exit.
+
+=back
+
+Behavior options for B<lintian>.
+
+=over 4
+
+=item B<--color> (auto|never|always|html)
+
+Whether to colorize tags in lintian output based on their visibility.
+The default is "auto" will use color only if the output is going to a
+terminal. "never" will never use color, "always" will always use
+color, and "html" will use HTML E<lt>spanE<gt> tags with a color style
+attribute (instead of ANSI color escape sequences).
+
+This option overrides the B<color> variable in the configuration file.
+
+=item B<--hyperlinks> (on|off)
+
+Shows text-based hyperlinks to tag descriptions on lintian.debian.org on
+terminals that support it. The default is on for terminals that support
+it, unless the user selected '--color never'. This currently only works
+in GNOME Terminal.
+
+This option overrides the B<color> variable in the configuration file.
+
+=item B<--default-display-level>
+
+Reset the current display level to the default.  Basically, this
+option behaves exactly like passing the following options to lintian:
+
+=over 4
+
+B<-L> ">=warning"
+
+=back
+
+The primary use for this is to ensure that lintian's display level has
+been reset to the built-in default values.  Notably, this can be used
+to override display settings earlier on the command-line or in the
+lintian configuration file.
+
+Further changes to the display level can be done I<after> this option.
+Example: B<--default-display-level --display-info> gives you the
+default display level plus informational ("I:") tags.
+
+=item B<--display-source> X
+
+Only display tags from the source X (e.g. the Policy Manual or the
+Developer Reference).  This option can be used multiple times to
+add additional sources.  Example sources are "policy" or "devref"
+being the Policy Manual and the Developer Reference (respectively).
+
+The entire list of sources can be found in
+I<$LINTIAN_BASE/data/output/manual-references>
+
+=item B<-E>, B<--display-experimental>, B<--no-display-experimental>
+
+Control whether to display experimental ("X:") tags.  They are
+normally suppressed.
+
+If a tag is marked experimental, this means that the code that
+generates this message is not as well tested as the rest of Lintian,
+and might still give surprising results.  Feel free to ignore
+Experimental messages that do not seem to make sense, though of course
+bug reports are always welcome (particularly if they include fixes).
+
+These options overrides the B<display-experimental> variable in the
+configuration file.
+
+=item B<--fail-on> {error | warning | info | pedantic | experimental | override | none}
+
+Causes B<lintian> to exit with a program status of 2 for the given
+conditions. This option can be a comma-separated list, or it may be
+specified multiple times.
+
+The default is B<error>. Also, 'warning' does not imply 'error'.
+Please specify both if you want both.
+
+=item B<-i>, B<--info>
+
+Print explanatory information about each problem discovered in
+addition to the lintian error tags. To print a long tag description
+without running lintian, see L<lintian-explain-tags(1)> or check
+the website at https://lintian.debian.org.
+
+To negate it, please use B<--no-info>.
+
+This option overrides B<info> (or B<no-info>) variable in the configuration
+file.
+
+=item B<-I>, B<--display-info>
+
+Display informational ("I:") tags as well.  They are normally
+suppressed.  (This is equivalent to B<-L> ">=info").
+
+This option overrides the B<display-info> variable in the
+configuration file.
+
+Note: B<display-level> and B<display-info> may not both appear in the
+configuration file.
+
+=item B<-L> [+|-|=][>=|>|=|<|<=][S|C|S/C], B<--display-level> [+|-|=][>=|>|=|<|<=][S|C|S/C]
+
+Fine-grained selection of tags to be displayed. It is possible to add,
+remove or set the levels to display, specifying a visibility (error,
+warning, info, pedantic, or classification. The default settings are
+equivalent to B<-L> ">=warning".
+
+The value consists of 3 parts, where two of them are optional.  The
+parts are:
+
+=over 4
+
+=item modifier operator
+
+How to affect the current display level.  Can be one of add to ("+"),
+remove from ("-") or set to ("=") the display level(s) denoted by the
+following selection.
+
+The default value is "=" (i.e. set the display level).
+
+=item set operator
+
+The visibility to be selected.  The operator can be one of ">=", ">",
+"=", "<" or "<=".  As an example, this can be used to select all info
+(and more serious) tags via ">=info".
+
+The default value is "=", which means "exactly" the given visibility.
+
+=back
+
+This option overrides the B<display-level> variable in the
+configuration file.  The value of the B<display-level> in
+configuration file should be space separated entries in the same
+format as passed via command-line.
+
+Note: B<display-level> may not be used with B<display-info> or B<pedantic>
+in the configuration file.
+
+=item B<-o>, B<--no-override>
+
+Ignore all overrides provided by the package.  This option will overrule
+B<--show-overrides>.
+
+This option overrides the B<override> variable in the configuration
+file.
+
+=item B<--pedantic>
+
+Display pedantic ("P:") tags as well.  They are normally suppressed.
+(This is equivalent to B<-L> "+=pedantic").
+
+Pedantic tags are Lintian at its most pickiest and include checks for
+particular Debian packaging styles and checks that many people
+disagree with.  Expect false positives and Lintian tags that you don't
+consider useful if you use this option.  Adding overrides for pedantic
+tags is probably not worth the effort.
+
+This option overrides the B<pedantic> variable in the configuration
+file.
+
+Note: B<pedantic> and B<display-level> may not both appear in the
+configuration file.
+
+=item B<--profile> vendor[/prof]
+
+Use the profile from vendor (or the profile with that name).  If the
+profile name does not contain a slash, the default profile for than
+vendor is chosen.
+
+As an example, if you are on Ubuntu and want to use Lintian's Debian
+checks, you can use:
+
+  --profile debian
+
+Likewise, on a Debian machine you can use this to request the Ubuntu
+checks.
+
+If the token I<{VENDOR}> appears in the profile name, B<lintian> will
+substitute the token with a vendor name to find the profile.
+B<lintian> uses L<Dpkg::Vendor> to determine the best vendor to use
+(the closer to the current vendor, the better).  This is mostly useful
+for people implementing their own checks on top of Lintian.
+
+If not specified, the default value is I<{VENDOR}/main>.
+
+Please Refer to the Lintian User Manual for the full documentation of
+profiles.
+
+=item B<--show-overrides>
+
+Controls whether tags that have been overridden should be shown.
+
+B<--show-overrides> will show overridden tags and mark them as
+overridden (using an "O" code).
+
+If the overridden tags are shown, the related override comments will
+also be displayed (unless --quiet is used).  Please refer to the Lintian
+User Manual for the documentation on how lintian relates comments to a
+given override.
+
+To negate it, i.e. suppress the showing of overridden tags, please use
+B<--no-show-overrides>.
+
+This option overrides the B<show-overrides> (or B<no-show-overrides>) variable
+in the configuration file.
+
+=item B<--suppress-tags> tag1,tag2,...
+
+Suppress the listed tags.  They will not be reported if they occur and
+will not affect the exit status of Lintian.  This option can be given
+multiple times and can be mixed with B<--suppress-tags-from-file>.
+
+This option can be used together with B<--dont-check-part> ("Not those
+checks nor these tags") and B<--check-part> ("Only those checks, but
+not these tags (from those checks)") to further reduce the selection of
+tags.
+
+When used with B<--tags>, this option is mostly ignored.
+
+=item B<--suppress-tags-from-file> file
+
+Suppress all tags listed in the given file.  Blank lines and lines
+beginning with # are ignored.  All other lines are taken to be tag
+names or comma-separated lists of tag names to suppress.  The
+suppressed tags will not be reported if they occur and will not affect
+the exit status of Lintian.
+
+Tags parsed from the file will be handled as if they had been given to
+the B<--suppress-tags> option (e.g. ignored if B<--tags> is used).
+
+=item B<--tag-display-limit>[=NUM]
+
+By default, lintian limits itself to emitting at most 4 instances of each
+tag per processable when STDOUT is a TTY.  This option specifies that limit.
+
+When STDOUT is not a TTY, lintian has no limit.
+
+To disable the limit, please use a value of zero.
+
+This option overrides the B<tag-display-limit> variable in the
+configuration file.
+
+=back
+
+Configuration options:
+
+=over 4
+
+=item B<--cfg> configfile
+
+Read the configuration from configfile rather than the default
+locations.  This option overrides the B<LINTIAN_CFG> environment
+variable.
+
+=item B<--no-cfg>
+
+Do not read any configuration file.  This option overrides the
+B<--cfg> above.
+
+=item B<--ignore-lintian-env>
+
+Ignore all environment variables starting with I<LINTIAN_>.
+
+This option is mostly useful for applications running B<lintian> for
+checking packages and do not want the invoking user to affect the
+result (by setting LINTIAN_PROFILE etc.).
+
+Note it does I<not> cause B<lintian> to ignore the entire environment
+like I<TMPDIR> or I<DEB_VENDOR>.  The latter can affect the default
+profile (or "{VENDOR}" token for B<--profile>).
+
+Should usually be combined with B<--no-user-dirs> (or unsetting $HOME
+and all I<XDG_> variables).
+
+=item B<--include-dir> dir
+
+Use dir as an additional "LINTIAN_BASE".  The directory is expected
+have a similar layout to the LINTIAN_BASE (if it exists), but does not
+need to be a full self-contained root.
+
+B<lintian> will check this directory for (additional) profiles, data
+files, support libraries and checks.  The latter two imply that
+Lintian may attempt to I<load and execute code> from this directory.
+
+This option may appear more than once; each time adding an additional
+directory.  Directories are searched in the order they appear on the
+command line.
+
+The additional directories will be checked I<after> the user
+directories (though see B<--no-user-dirs>) and I<before> the core
+LINTIAN_BASE.
+
+B<Note>: This option should be the very first if given.
+
+=item B<-j> X, B<--jobs>=X
+
+Set the limit for how many jobs Lintian will run in parallel. This
+option overrides the B<jobs> variable in the configuration file.
+
+By default Lintian will use I<nproc> to determine a reasonable default
+(or 2, if the nproc fails).
+
+=item B<--user-dirs>, B<--no-user-dirs>
+
+By default, B<lintian> will check I<$HOME> and I</etc> for files
+supplied by the user or the local sysadmin (e.g. config files and
+profiles).  This default can be disabled (and re-enabled) by using
+B<--no-user-dirs> (and B<--user-dirs>, respectively).
+
+These options will I<not> affect the inclusion of LINTIAN_BASE, which
+is always included.
+
+These option can appear multiple times, in which case the last of them
+to appear determines the result.
+
+Note that if the intention is only to disable the user's I<$HOME>,
+then unsetting I<$HOME> and I<XDG_*_HOME> may suffice.  Alternatively,
+I</etc> can be "re-added" by using I<--include-dir> (caveat:
+I</etc/lintianrc> will be ignored by this).
+
+If the intention is to avoid (unintentional) side-effects from the
+calling user, then this option could be combined with
+B<--ignore-lintian-env>.
+
+If for some reason B<--no-user-dirs> cannot be used, then consider
+unsetting I<$HOME> and all the I<$XDG_*> variables (not just the
+I<$XDG_*_HOME> ones).
+
+B<Note>: This option should be the very first if given.
+
+=back
+
+Developer/Special usage options:
+
+=over 4
+
+=item B<--allow-root>
+
+Override lintian's warning when it is run with superuser privileges.
+
+=item B<--packages-from-file> X
+
+The line is read as the path to a file to process (all whitespace is
+included!).
+
+If X is "-", Lintian will read the packages from STDIN.
+
+=item B<--perf-debug>
+
+Enable performance related debug logging to STDERR.
+
+The data logged and the format used is subject to change with every
+release.
+
+Note that some of the information may also be available (possibly in
+a different format) with the B<--debug> option.
+
+=back
+
+=head1 FILES
+
+Lintian looks for its configuration file in the following locations,
+in this order:
+
+=over 4
+
+=item * The argument given to B<--cfg>
+
+=item * I<$LINTIAN_CFG>
+
+=item * I<$XDG_CONFIG_HOME/lintian/lintianrc>
+
+=item * I<XDG_DIR/lintian/lintianrc>
+
+Where XDG_DIR is a directory listed in I<$XDG_CONFIG_DIRS> (or
+I</etc/xdg> if I<$XDG_CONFIG_DIRS> is unset).
+
+=item * I<$HOME/.lintianrc>
+
+Please consider using the XDG based variant above (usually, in
+I<~/.config>).
+
+=item * I</etc/lintianrc>
+
+=back
+
+Lintian uses the following directories:
+
+=over 4
+
+=item I</tmp>
+
+Lintian defaults to creating a temporary lab directory in I</tmp>.  To
+change the directory used, set the TMPDIR environment variable to a
+suitable directory.  TMPDIR can be set in the configuration file.
+
+=item I</usr/share/lintian/checks>
+
+Scripts that check aspects of a package.
+
+=item I</usr/share/lintian/collection>
+
+Scripts that collect information about a package and store it for use
+by the check scripts.
+
+=item I</usr/share/lintian/data>
+
+Supporting data used by Lintian checks and for output formatting.
+
+=item I</usr/share/lintian/lib>
+
+Utility scripts used by the other lintian scripts.
+
+=back
+
+For binary packages, Lintian looks for overrides in a file named
+I<usr/share/lintian/overrides/E<lt>packageE<gt>> inside the binary
+package, where I<E<lt>packageE<gt>> is the name of the binary
+package.  For source packages, Lintian looks for overrides in
+I<debian/source/lintian-overrides> and then in
+I<debian/source.lintian-overrides> if the first file is not found.
+The first path is preferred.  See the Lintian User's Manual for the
+syntax of overrides.
+
+=head1 CONFIGURATION FILE
+
+The configuration file can be used to specify default values for some
+options.  The general format is:
+
+ option = value
+
+All whitespace adjacent to the "=" sign as well as leading and
+trailing whitespace is ignored.  However whitespace within the
+value is respected, as demonstrated by this example:
+
+ # Parsed as "opt1" with value "val1"
+    opt1    =   val1
+ # Parsed as "opt2" with value "val2.1  val2.2     val2.3"
+ opt2 = val2.1  val2.2     val2.3
+
+Unless otherwise specified, no option may appear more than once.
+Lintian will ignore empty lines or lines starting with the
+B<#>-character.
+
+Generally options will be the long form of the command-line option
+without the leading dashes.  There some exceptions (such as
+--profile), where Lintian uses the same name as the environment
+variable.
+
+Lintian only allows a subset of the options specified in the
+configuration file; please refer to the individual options in
+L</OPTIONS>.
+
+In the configuration file, all options listed must have a value, even
+if they do not accept a value on command line (e.g. --pedantic).  The
+values "yes", "y", "1", or "true" will enable such an option and "no",
+"n", "0" or "false" will disable it.  Prior to the 2.5.2 release,
+these values were case sensitive.
+
+For other options, they generally take the same values as they do on
+the command line.  Though some options allow a slightly different
+format (e.g. --display-level).  These exceptions are explained for the
+relevant options in L</OPTIONS>.
+
+Beyond command line options, it is also allowed to specify the
+environment variable "TMPDIR" in the configuration file.
+
+A sample configuration file could look like:
+
+ # Sample configuration file for lintian
+ #
+ # Set the default profile (--profile)
+ LINTIAN_PROFILE = debian
+
+ # Set the default TMPDIR for lintian to /var/tmp/lintian
+ # - useful if /tmp is tmpfs with "limited" size.
+ TMPDIR = /var/tmp/lintian/
+
+ # Show info (I:) tags by default (--display-info)
+ #  NB: this cannot be used with display-level
+ display-info=yes
+
+ # Ignore all overrides (--no-override)
+ #  NB: called "override" in the config file
+ #      and has inverted value!
+ override = no
+
+ # Automatically determine if color should be used
+ color = auto
+
+=head1 EXIT STATUS
+
+=over 4
+
+=item B<0>
+
+Normal operation.
+
+=item B<1>
+
+Lintian run-time error. An error message is sent to stderr.
+
+=item B<2>
+
+Detected a condition specified via the B<--fail-on> option. This can
+be used to trigger a non-zero exit value in case of policy violations.
+
+=back
+
+=head1 CHECKING LAST BUILD
+
+When run in an unpacked package dir (with no package selection
+arguments), Lintian will use I<debian/changelog> to determine the
+source and version of the package.  Lintian will then attempt to find
+a matching I<.changes> file for this source and version combination.
+
+Lintian will (in order) search the following directories:
+
+=over 4
+
+=item ..
+
+Used by dpkg-buildpackage(1).
+
+=item ../build-area
+
+Used by svn-buildpackage(1).
+
+=item /var/cache/pbuilder/result
+
+Used by pbuilder(1) and cowbuilder(1).
+
+=back
+
+In each directory, Lintian will attempt to find a I<.changes> file
+using the following values as architecture (in order):
+
+=over 4
+
+=item I<$DEB_BUILD_ARCH> (or I<dpkg --print-architecture>)
+
+The environment variable DEB_BUILD_ARCH (if not set, "dpkg
+--print-architecture" will be used instead)
+
+=item I<$DEB_HOST_ARCH>
+
+The environment variable DEB_HOST_ARCH.
+
+=item I<dpkg --print-foreign-architectures>
+
+If dpkg(1) appears to support multi-arch, then any architecture listed
+by "dpkg --print-foreign-architectures" will be used (in the order
+returned by dpkg).
+
+=item I<multi>
+
+Pseudo architecture used by mergechanges(1).
+
+=item I<all>
+
+Used when building architecture indep packages only (e.g.
+dpkg-buildpackage -A).
+
+=item I<source>
+
+Used for "source only" builds (e.g. dpkg-buildpackage -S).
+
+=back
+
+If a I<.changes> file matches any combination above exists, Lintian
+will process the first match as if you had passed it per command line.
+If no I<.changes> file can be found, Lintian will print a list of attempted
+locations on STDERR and exit 0.
+
+=head1 EXAMPLES
+
+=over 4
+
+=item B<$ lintian foo.changes>
+
+Check the changes file itself and any (binary, udeb or source) package
+listed in it.
+
+=item B<$ lintian foo.deb>
+
+Check binary package foo given by foo.deb.
+
+=item B<$ lintian foo.dsc>
+
+Check source package foo given by foo.dsc.
+
+=item B<$ lintian foo.dsc -L +info>
+
+Check source package foo given by foo.dsc, including info tags.
+
+=item B<$ lintian -i foo.changes>
+
+Check the changes file and, if listed, the source and binary package
+of the upload. The output will contain detailed information about the
+reported tags.
+
+=item B<$ lintian>
+
+Assuming I<debian/changelog> exists, look for a changes file for the
+source in the parent dir.  Otherwise, print usage information and
+exit.
+
+=back
+
+=head1 BUGS
+
+Lintian does not have any locking mechanisms yet.  (Running several
+Lintian processes on the same laboratory simultaneously is likely to fail
+or corrupt the laboratory.)
+
+If you discover any other bugs in lintian, please contact the authors.
+
+=head1 SEE ALSO
+
+L<lintian-explain-tags(1)>, Lintian User Manual
+(/usr/share/doc/lintian/lintian.html)
+
+Packaging tools: L<debhelper(7)>, L<dh_make(1)>,
+L<dpkg-buildpackage(1)>.
+
+=head1 AUTHORS
+
+Niels Thykier <niels@thykier.net>
+
+Richard Braakman <dark@xs4all.nl>
+
+Christian Schwarz <schwarz@monet.m.isar.de>
+
+Please use the email address <lintian-maint@debian.org> for
+Lintian related comments.
+
+=cut