Adding upstream version 2.117.0.upstream/2.117.0upstream

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

1 files changed, 992 insertions, 0 deletions

diff --git a/doc/lintian.rst b/doc/lintian.rst
new file mode 100644
index 0000000..7fe6d18
--- /dev/null
+++ b/doc/lintian.rst
@@ -0,0 +1,992 @@
+=====================
+Lintian User's Manual
+=====================
+.. sectnum::
+.. contents::
+   :depth: 3
+
+.. _chapter-1:
+
+Introduction
+============
+
+.. _section-1.1:
+
+About Lintian
+-------------
+
+Lintian is a Debian package checker. It can be used to check binary and
+source packages for compliance with the Debian policy and for other
+common packaging errors.
+
+Lintian uses an archive directory, called laboratory, in which it stores
+information about the packages it examines. It can keep this information
+between multiple invocations in order to avoid repeating expensive
+data-collection operations. It's also possible to check the complete
+Debian archive for bugs — in a timely manner.
+
+.. _section-1.2:
+
+The intention of Lintian
+------------------------
+
+Packaging has become complicated—not because dpkg is complicated
+(indeed, dpkg-deb is very simple to use) but because of the high
+requirements of our policy. If a developer releases a new package, she
+has to consider hundreds of guidelines to make the package \`policy
+compliant.'
+
+All parts of our policy have been introduced by the same procedure: Some
+developer has a good idea how to make packages more \`unique' with
+respect to a certain aspect—then the idea is discussed and a policy
+proposal is prepared. If we have a consensus about the policy change,
+it's introduced in our manuals.
+
+Therefore, our policy is *not* designed to make life harder for the
+maintainers! The intention is to make Debian the best Linux distribution
+out there. With this in mind, lots of policy changes are discussed on
+the mailing lists each week.
+
+But changing the policy is only a small part of the story: Just having
+some statement included in the manual does not make Debian any better.
+What's needed is for that policy to become \`real life,' i.e., it's
+*implemented* in our packages. And this is where Lintian comes in:
+Lintian checks packages and reports possible policy violations. (Of
+course, not everything can be checked mechanically — but a lot of
+things can and this is what Lintian is for.)
+
+Thus, Lintian has the following goals:
+
+-  *To give us some impression of the \`gap' between theory (written
+   policy) and praxis (current state of implementation).*
+
+   From the results of the first two Lintian checks I implemented, I see
+   that there is a big need to make this gap smaller. Introducing more
+   policy aspects is worthless unless they are implemented. We first
+   should fix packages to comply with current policy before searching
+   for new ways to make policy more detailed. (Of course, there are also
+   important policy changes that need to be introduced — but this is
+   not what's meant here.)
+
+-  *To make us re-think about certain aspects of our policy.*
+
+   For example, it could turn out that some ideas that once sounded
+   great in theory are hard to implement in all our packages — in
+   which case we should rework this aspect of policy.
+
+-  *To show us where to concentrate our efforts in order to make Debian
+   a higher quality distribution.*
+
+   Most release requirements will be implemented through policy. Lintian
+   reports provide an easy way to compare *all* our packages against
+   policy and keep track of the fixing process by watching bug reports.
+   Note, that all this can be done *automatically*.
+
+-  *To make us avoid making the same mistakes all over again.*
+
+   Being humans, it's natural for us to make errors. Since we all have
+   the ability to learn from our mistakes, this is actually no big
+   problem. Once an important bug is discovered, a Lintian check could
+   be written to check for exactly this bug. This will prevent the bug
+   from appearing in any future revisions of any of our packages.
+
+.. _section-1.3:
+
+Design issues
+-------------
+
+There are three fields of application for Lintian:
+
+-  one person could use Lintian to check the whole Debian archive and
+   reports bugs,
+
+-  each maintainer runs Lintian over her packages before uploading them,
+
+-  dinstall checks packages which are uploaded to master before they are
+   installed in the archive.
+
+The authors of Lintian decided to use a very modular design to achieve
+the following goals:
+
+-  flexibility: Lintian can be used to check single packages or the
+   whole archive and to report and keep track of bug reports, etc.
+
+-  completeness: Lintian will eventually include checks for (nearly)
+   everything that can be checked mechanically.
+
+-  uptodateness: Lintian will be updated whenever policy is changed.
+
+-  performance: Lintian should make it possible to check single packages
+   within seconds or check the full archive within 5 days.
+
+The design also has a number of constrains that limits the things
+Lintian can check for and what tools it can use:
+
+-  static analysis: The code in a package may be analyzed, but it should
+   *never* be executed. However, Lintian can (and does) use external
+   tools to analyze files in the package.
+
+-  deterministic replay-ability: Checks should not rely on the state of
+   system caches or even the system time. These things makes it harder
+   for others to reproduce (the absence of) tags.
+
+-  same source analysis: Lintian checks packages in small isolated
+   groups based on the source package. Requiring the presence of all the
+   dependencies to provide the full results make it harder to run
+   lintian (not to mention, it makes "deterministic replay-ability" a
+   lot harder as well).
+
+.. _section-1.4:
+
+Disclaimer
+----------
+
+Here is a list of important notes on how to use Lintian:
+
+1. Lintian is not finished yet and will probably never be. Please don't
+   use Lintian as a reference for Debian policy. Lintian might miss a
+   lot of policy violations while it might also report some violations
+   by mistake. If in doubt, please check out the policy manuals.
+
+2. The Debian policy gives the maintainers a lot of freedom. In most
+   cases, the guidelines included in the manuals allow exceptions. Thus,
+   if Lintian reports a policy violation on a package and you think this
+   is such an exception (or if you think Lintian has a bug) you can do
+   two things: If your package is a bit non-standard and weird in this
+   regard, you can install an override. If you think however that the
+   check is too easily or outright wrongly triggered, please file a bug
+   on the lintian package.
+
+3. Please DO NOT use Lintian to file bug reports (neither single ones
+   nor mass bug reports). This is done by the authors of Lintian already
+   and duplication of efforts and bug reports should be avoided! If you
+   think a certain bug is \`critical' and should be reported/fixed
+   immediately, please contact the maintainer of the corresponding
+   package and/or the Lintian maintainers.
+
+4. Any feedback about Lintian is welcome! Please send your comments to
+   the lintian maintainers lintian-maint@debian.org.
+
+.. _chapter-2:
+
+Getting started
+===============
+
+.. _section-2.1:
+
+Installing Lintian
+------------------
+
+Before you can start to check your packages with Lintian, you'll have to
+install the lintian Debian package.
+
+Alternatively you can checkout Lintian from the source repository and
+use that directly. By setting LINTIAN_BASE (or using the --root option)
+lintian can be run from the source directory as if it had been installed
+on your system.
+
+The only known caveat of using Lintian from the source directory is that
+Lintian requires a C.UTF-8 (or en_US.UTF-8) locale to correctly process
+some files. (Is that still true?)
+
+.. _section-2.2:
+
+Running lintian
+---------------
+
+After that, you can run Lintian on a changes file or any Debian binary,
+udeb or source packages like this:
+
+::
+
+   $ lintian etm_3.2.30-1.1_all.deb
+   E: etm: appstream-metadata-legacy-format [usr/share/appdata/etm.appdata.xml]
+   W: etm: appstream-metadata-in-legacy-location [usr/share/appdata/etm.appdata.xml]
+   I: etm: package-contains-documentation-outside-usr-share-doc [usr/share/etm/etmTk/help/UserManual.html]
+   $
+
+Please note that some checks are cross-package checks and can only be
+(accurately) performed if the binary packages and the source are
+processed together. If Lintian is passed a changes file, it will attempt
+to process all packages listed in the changes file.
+
+Lintian supports a number of command line options, which are documented
+in the manpage of lintian(1). Some of the options may appear in the
+lintianrc file without leading dashes.
+
+.. _section-2.3:
+
+Lintian Tags
+------------
+
+Lintian uses a special format for all its error and warning messages.
+With that it is very easy to write other programs which run Lintian and
+interpret the displayed messages.
+
+The first character of each line indicates the type of message.
+Currently, the following types are supported:
+
+*Errors (E)*
+   The displayed message indicates a policy violation or a packaging
+   error. For policy violations, Lintian will cite the appropriate
+   policy section when it is invoked with the ``-i`` option.
+
+*Warnings (W)*
+   The displayed message might be a policy violation or packaging error.
+   A warning is usually an indication that the check is known to
+   sometimes produce false positive alarms, because either the
+   corresponding rule in policy has many exceptions or the check uses
+   some sort of heuristic to find errors.
+
+*Info (I)*
+   The displayed message is meant to inform the maintainer about a
+   certain packaging aspect. Such messages do not usually indicate
+   errors, but might still be of interest to the curious. They are not
+   displayed unless the ``-I`` option is set.
+
+*Notes (N)*
+   The displayed message is a debugging message which informs you about
+   the current state of Lintian.
+
+*Experimental (X)*
+   The displayed message is one of the types listed above, but has been
+   flagged as \`experimental' by the Lintian maintainers. 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. They are not
+   displayed unless the ``-E`` option is set.
+
+*Overridden (O)*
+   The displayed message indicates a previous *Warning* or *Error*
+   message which has been *overridden* (see below). They are not
+   displayed unless the ``--show-overrides`` option is set.
+
+*Pedantic (P)*
+   The displayed message indicates a message of Lintian at its most
+   pickiest and include checks for particular Debian packaging styles,
+   checks that are very frequently wrong, and checks that many people
+   disagree with. They are not displayed unless the ``--pedantic``
+   option is set.
+
+The type indicator is followed by the name of the package and for
+non-binary packages the type of the package. Then comes the *problem*
+that was discovered, also known as a *tag* (for example,
+``old-fsf-address-in-copyright-file``).
+
+Depending on which tag has been reported, the line may contain
+additional arguments which tell you, for example, which files are
+involved.
+
+If you do not understand what a certain tag is about, you can specify
+the ``-i`` option when calling Lintian to get a detailed description of
+the reported tags:
+
+::
+
+   $ lintian --info --tags appstream-metadata-in-legacy-location etm_3.2.30-1.1_all.deb
+   N:
+   W: etm: appstream-metadata-in-legacy-location [usr/share/appdata/etm.appdata.xml]
+   N:
+   N:   AppStream metadata file was found in /usr/share/appdata/. The AppStream XML files should be placed in /usr/share/metainfo/.
+   N:
+   N:   Please refer to https://wiki.debian.org/AppStream/Guidelines for details.
+   N:
+   N:   Visibility: warning
+   N:   Show-Always: no
+   N:   Check: appstream-metadata
+   N:
+   $
+
+In some cases, the messages contain some additional text with a leading
+hash character (``#``). This text should be ignored by any other
+programs which interpret Lintian's output because it doesn't follow a
+unique format between different messages and it's only meant as
+additional information for the maintainer.
+
+.. _section-2.4:
+
+Overrides
+---------
+
+In some cases, the checked package does not have a bug or does not
+violate policy, but Lintian still reports an error or warning. This can
+have the following reasons: Lintian has a bug itself, a specific Lintian
+check is not smart enough to know about a special case allowed by
+policy, or the policy does allow exceptions to some rule in general.
+
+In the first case (where Lintian has a bug) you should send a bug report
+to the Debian bug tracking system and describe which package you
+checked, which messages have been displayed, and why you think Lintian
+has a bug. Best would be, if you would run Lintian again over your
+packages using the ``-d`` (or ``--debug``) option, which will cause
+Lintian to output much more information (debugging info), and include
+these messages in your bug report. This will simplify the debugging
+process for the authors of Lintian.
+
+In the other two cases (where the error is actually an exception to
+policy), you should probably add an override. If you're unsure though
+whether it's indeed a good case for an override, you should contact the
+Lintian maintainers too, including the Lintian error message and a short
+note, stating why you think this is an exception. This way, the Lintian
+maintainers can be sure the problem is not actually a bug in Lintian or
+an error in the author's reading of policy. Please do not override bugs
+in lintian, they should rather be fixed than overridden.
+
+Once it has been decided that an override is needed, you can easily add
+one by supplying an overrides file. If the override is for a binary or
+udeb package, you have to place it at
+``/usr/share/lintian/overrides/<package>`` inside the package. The tool
+``dh_lintian`` from the Debian package debhelper may be useful for this
+purpose.
+
+If the override is for a source package, you have to place it at
+``debian/source/lintian-overrides`` or
+``debian/source.lintian-overrides`` (the former path is preferred). With
+that, Lintian will know about this exception and not report the problem
+again when checking your package. (Actually, Lintian will report the
+problem again, but with type *overridden*, see above.)
+
+Note that Lintian extracts the override file from the (u)deb and stores
+it in the laboratory. The files currently installed on the system are
+not used in current Lintian versions.
+
+.. _section-2.4.1:
+
+Format of override files
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The format of the overrides file is simple, it consists of one override
+per line (and may contain empty lines and comments, starting with a
+``#``, on others): ``[[<package>][ <archlist>][ <type>]: ]<lintian-tag>[
+[*]<context>[*]]``. <package> is the package name;
+<archlist> is an architecture list (see Architecture specific overrides
+for more info); <type> is one of ``binary``, ``udeb`` and ``source``,
+and <context> is all additional information provided by Lintian
+except for the tag. What's inside brackets is optional and may be
+omitted if you want to match it all. Additionally, if the context of
+the tag contains paths to files in the package, they're enclosed with
+literal brackets (so called "pointed hints") so that tools which
+process lintian tags can link to the according file and potentially
+even line in the file.
+
+An example file for a binary package would look like:
+
+::
+
+   /usr/share/lintian/overrides/foo, where foo is the name of your package
+
+   # We use a non-standard dir permission to only allow the webserver to look
+   # into this directory:
+   foo binary: non-standard-dir-perm
+   foo binary: FSSTND-dir-in-usr [/usr/man/man1/foo.1.gz]
+
+An example file for a source package would look like:
+
+::
+
+   debian/source/lintian-overrides in your base source directory
+   foo source: debian-files-list-in-source
+   # Upstream distributes it like this, repacking would be overkill though, so
+   # tell lintian to not complain:
+   foo source: configure-generated-file-in-source [config.cache]
+
+Many tags can occur more than once (e.g. if the same error is found in
+more than one file). You can override a tag either completely by
+specifying its name (first line in the examples) or only one occurrence
+of it by specifying the additional info, too (second line in the
+examples). If you add an asterisk (``*``) in the additional info, this
+will match arbitrary strings similar to the shell wildcard. For example:
+
+::
+
+   # Multiple files need to be covered by the override
+   source-is-missing [apidoc/html/*.js]
+
+.. _section-2.4.2:
+
+Documenting overrides
+~~~~~~~~~~~~~~~~~~~~~
+
+To assist reviewers, Lintian will extract the comments from the
+overrides file and display the related comments next to the overridden
+tags.
+
+Comments directly above an override will be shown next to all tags it
+overrides. If an override for the same tags appears on the very next
+line, it will inherit the comment from the override above it.
+
+::
+
+   # This comment will be shown above all tags overridden by the following
+   # two overrides, (because they apply to the same tag and there is no
+   # empty line between them)
+   foo source: some-tag exact match
+   foo source: some-tag wildcard * match
+   # This override has its own comment, and it is not shared with the
+   # override below (because there is an empty line in between them).
+   foo source: some-tag another exact match
+
+   foo source: some-tag override without a comment
+
+Empty lines can be used to disassociate a comment from an override
+following it. This can also be used to make a general comment about the
+overrides that will not be displayed.
+
+::
+
+   # This is a general comment not connected to any override, since there
+   # is one (or more) empty lines after it.
+
+   foo source: another-tag without any comments
+
+.. _section-2.4.3:
+
+Architecture specific overrides
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In rare cases, Lintian tags may be architecture specific. It is possible
+to mark overrides architecture specific by using the optional
+architecture list.
+
+The architecture list has the same syntax as the architecture list in
+the "Build-Depends" field of a source package. This is described in
+detail in the `Debian Policy Manual
+§7.1 <https://www.debian.org/doc/debian-policy/#s-controlsyntax>`__.
+Examples:
+
+::
+
+   # This is an example override that only applies to the i386
+   # architecture.
+   foo [i386] binary: some-tag optional-extra
+
+   # An architecture wildcard would look like:
+   foo [any-i386] binary: another-tag optional-extra
+
+   # Negation also works
+   foo [!amd64 !i386] binary: some-random-tag optional-extra
+
+   # Negation even works for wildcards
+   foo [!any-i386] binary: some-tag-not-for-i386 optional-extra
+
+   # The package name and the package type is optional, so this
+   # also works
+   [linux-any]: tag-only-for-linux optional-extra.
+
+An unknown architecture will trigger a packaging hint. So will an
+architecture-specific override in an architecture-independent
+installable.
+
+.. _section-2.5:
+
+Vendor Profiles
+---------------
+
+Vendor profiles allows vendors and users to customize Lintian without
+having to modify the underlying code. If a profile is not explicitly
+given, Lintian will derive the best possible profile for the current
+vendor from dpkg-vendor.
+
+.. _section-2.5.1:
+
+Rules for profile names and location
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Profile names should only consist of the lower case characters ([a-z]),
+underscore (_), dash (-) and forward slashes (/). Particularly note that
+dot (.) are specifically *not* allowed in a profile name.
+
+The default profile for a vendor is called ``$VENDOR/main``. If Lintian
+sees a profile name without a slash, it is taken as a short form of the
+default profile for a vendor with that name.
+
+The filename for the profile is derived from the name by simply
+concatenating it with ``.profile``, Lintian will then look for a file
+with that name in the following directories:
+
+-  ``$XDG_DATA_HOME/lintian/profiles``
+
+-  ``$HOME/.lintian/profiles``
+
+-  ``/etc/lintian/profiles``
+
+-  ``$LINTIAN_BASE/profiles``
+
+Note that an implication of the handling of default vendor profiles
+implies that profiles must be in subdirectories of the directories above
+for Lintian to recognise them.
+
+The directories are checked in the listed order and the first file
+matching the profile will be used. This allows users to override a
+system profile by putting one with the same filename in
+``$XDG_DATA_HOME/lintian/profiles`` or ``$HOME/.lintian/profiles``.
+
+.. _section-2.5.2:
+
+Profile syntax and semantics
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Profiles are written in the same syntax as Debian control files as
+described in the `Debian Policy Manual
+§5.1 <https://www.debian.org/doc/debian-policy/#s-controlsyntax>`__.
+Profiles allow comments as described in the Policy Manual.
+
+.. _section-2.5.2.1:
+
+Main profile paragraph
+^^^^^^^^^^^^^^^^^^^^^^
+
+The fields in the first paragraph are:
+
+*Profile* (simple, mandatory)
+   Name of the profile.
+
+*Extends* (simple, optional)
+   Name of the (parent) profile, which this profile extends. Lintian
+   will recursively process the extended profile before continuing with
+   processing this profile. In the absence of this field, the profile is
+   not based on another profile.
+
+*Load-Checks* (folded, optional)
+   Comma-separated list of checks. Lintian will ensure all checks listed
+   are loaded (allowing tags from them to be enabled or disabled via
+   Enable-Tags or Disable-Tags).
+
+   If a given check was already loaded before this field is processed,
+   then it is silently ignored. Otherwise, the check is loaded and all
+   of its tags are disabled (as if it had been listed in
+   Disable-Tags-From-Check).
+
+   This field is most likely only useful if the profile needs to enable
+   a list of tags from a check in addition to any tags already enabled
+   from that check (if any).
+
+*Enable-Tags-From-Check* (folded, optional)
+   Comma-separated list of checks. All tags from each check listed will
+   be enabled in this profile. The check will be loaded if it wasn't
+   already.
+
+*Disable-Tags-From-Check* (folded, optional)
+   Comma-separated list of checks. All tags from each check listed will
+   be disabled in this profile. The check will be loaded if it wasn't
+   already.
+
+*Enable-Tags* (folded, optional)
+   Comma-separated list of tags that should be enabled. It may only list
+   tags from checks already loaded or listed in one of the following
+   fields "Load-Checks", "Enable-Tags-From-Check" or
+   "Disable-Tags-From-Check" in the current profile.
+
+*Disable-Tags* (folded, optional)
+   Comma-separated list of tags that should be disabled. It may only
+   list tags from checks already loaded or listed in one of the
+   following fields "Load-Checks", "Enable-Tags-From-Check" or
+   "Disable-Tags-From-Check" in the current profile.
+
+The profile is invalid and is rejected, if Enable-Tags and Disable-Tags
+lists the same tag twice - even if it is in the same field. This holds
+analogously for checks and the three fields Load-Checks,
+Enable-Tags-From-Check and Disable-Tags-From-Check.
+
+It is allowed to list a tag in Enable-Tags or Disable-Tags even if the
+check that provides this tag is listed in the Disable-Tags-From-Check or
+Enable-Tags-From-Check field. In case of conflict, Enable-Tags /
+Disable-Tags shall overrule Disable-Tags-From-Check /
+Enable-Tags-From-Check within the profile.
+
+Load-Checks, Enable-Tags-From-Check and Disable-Tags-From-Check can be
+used to load third-party or vendor specific checks.
+
+It is not an error to load, enable or disable a check or tag that is
+already loaded, enabled or disabled respectively (e.g. by a parent
+profile).
+
+A profile is invalid if it directly or indirectly extends itself or if
+it extends an invalid profile.
+
+By default the tags from the check "lintian" will be loaded as they
+assist people in writing and maintaining their overrides file (e.g. by
+emitting ``malformed-override``). However, they can be disabled by
+explicitly adding the check ``lintian`` in the Disable-Tags-From-Check
+field.
+
+.. _section-2.5.2.2:
+
+Tag alteration paragraphs
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The fields in the secondary paragraphs are:
+
+*Tags* (folded, mandatory)
+   Comma separated list of tags affected by this paragraph.
+
+*Overridable* (simple, optional)
+   Either "Yes" or "No", which decides whether these tags can be
+   overridden. Lintian will print an informal message if it sees an
+   override for a tag marked as non-overridable (except if --quiet is
+   passed).
+
+*Visibility* (simple, optional)
+   The value must be a valid tag visibility other than "classification".
+   The visibility of the affected tags is set to this value. This cannot
+   be used on any tag that is defined as a "classification" tag.
+
+   Note that *experimental* is not a visibility.
+
+The paragraph must contain at least one other field than the Tag field.
+
+.. _section-2.5.2.3:
+
+An example vendor profile
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Below is a small example vendor profile for a fictive vendor called
+"my-vendor".
+
+::
+
+   # The default profile for "my-vendor"
+   Profile: my-vendor/main
+   # It has all the checks and settings from the "debian" profile
+   Extends: debian/main
+   # Add checks specific to "my-vendor"
+   Enable-Tags-From-Check:
+     my-vendor/some-check,
+     my-vendor/another-check,
+   # Disable a tag
+   Disable-Tags: dir-or-file-in-opt
+
+   # Bump visibility of no-md5sums-control-file
+   # and file-missing-in-md5sums and make them
+   # non-overridable
+   Tags: no-md5sums-control-file,
+         file-missing-in-md5sums,
+   Visibility: error
+   Overridable: no
+
+.. _section-2.6:
+
+Vendor specific data files
+--------------------------
+
+Lintian uses a number of data files for various checks, ranging from
+common spelling mistakes to lists of architectures. While some of these
+data files are generally applicable for all vendors (or Debian
+derivatives), others are not.
+
+Lintian supports vendor specific data files. This allows vendors to deploy
+their own data files tailored for their kind of system. Lintian supports
+both extending an existing data file and completely overriding it.
+
+.. _section-2.6.1:
+
+Load paths and order
+~~~~~~~~~~~~~~~~~~~~
+
+Lintian will search the following directories in order for vendor
+specific data files:
+
+-  ``$XDG_DATA_HOME/lintian/vendors/PROFILENAME/data``
+
+-  ``$HOME/.lintian/vendors/PROFILENAME/data``
+
+-  ``/etc/lintian/vendors/PROFILENAME/data``
+
+-  ``$LINTIAN_BASE/vendors/PROFILENAME/data``
+
+If none of the directories exists or none of them provide the data file
+in question, Lintian will (recursively) retry with the parent of the
+vendor (if any). If the vendor and none of its parents provide the data
+file, Lintian will terminate with an error.
+
+.. _section-2.6.2:
+
+Basic syntax of data files
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Generally, data files are read line by line. Leading whitespace of every
+line is removed and (now) empty lines are ignored. Lines starting with a
+``#`` are comments and are also ignored by the parser. Lines are
+processed in the order they are read.
+
+If the first character of the line is a ``@``, the first word is parsed
+as a special processing instruction. The rest of the line is a parameter
+to that processing instruction. Please refer to `List of processing
+instructions <#section-2.6.2.1>`__.
+
+All other lines are read as actual data. If the data file is a table (or
+map), the lines will parsed as key-value pairs. If the data file is a
+list (or set), the full line will be considered a single value of the
+list.
+
+It is permissible to define the same key twice with a different value.
+In this case, the value associated with the key is generally redefined.
+There are very rare exceptions to this rule, where the data file is a
+table of tables (of values). In this case, a recurring key is used to
+generate the inner table.
+
+.. _section-2.6.2.1:
+
+List of processing instructions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following processing instructions are recognised:
+
+*@delete ENTRY*
+   Removes a single entry denoted by ENTRY that has already been parsed.
+
+   It is permissible to list a non-existent entry, in which case the
+   instruction has no effect. This instruction does *not* prevent the
+   entry from being (re-)defined later, it only affects the current
+   definition of the entry.
+
+   For key-pair based data files, ENTRY must match the key. For single
+   value data files, ENTRY must match the line to remove.
+
+*@include-parent*
+   Processes parent data file of the current data file.
+
+   The informal semantics of this instruction is that it reads the
+   "next" data file in the vendor "chain". The parsing of the parent is
+   comparable to a C-style include or sourcing a shell script.
+
+   More formally, let CP be the name of the vendor profile that defines
+   the data file containing the instruction. Let the parent of CP be
+   referred to as PCP.
+
+   Lintian will search for the data file provided by PCP using the rules
+   as specified in `Load paths and order <#section-2.6.1>`__. If no data
+   file is found, Lintian will terminate the parsing with an error.
+   Thus, this instruction can only be used by profiles that extends
+   other profiles.
+
+.. _chapter-3:
+
+Advanced usage
+==============
+
+.. _section-3.1:
+
+How Lintian works
+-----------------
+
+Lintian is divided into the following layers:
+
+*frontend*
+   the command line interface (currently, this layer consists of the
+   ``lintian`` program.
+
+*checks*
+   a set of modules that check different aspects of packages.
+
+*data collectors*
+   a set of scripts that prepares specific information about a package
+   needed by the check modules
+
+When you check a package with Lintian, the following steps are performed
+(not exactly in this order—but the details aren't important now):
+
+1. An entry is created for the package in the *laboratory* (or just
+   *lab*).
+
+2. Some data is collected about the package. (That is done by the
+   so-called *data collector* scripts.) For example, the ``file``
+   program is run on each file in the package and the output is stored
+   in the lab.
+
+3. The *checks* are run over the package and report any discovered
+   policy violations or other errors. These scripts don't access the
+   package contents directly, but use the collected data as input.
+
+4. Depending on the *lab mode* Lintian uses (see below), the whole lab
+   directory is removed again. If the lab is not removed, parts of the
+   data collected may be auto cleaned to reduce disk space.
+
+This separation of the *check* from the *data collector scripts* makes
+it possible to run Lintian several times over a package without having
+to recollect all the data each time. In addition, the checker scripts do
+not have to worry about packaging details since this is abstracted away
+by the collector scripts.
+
+.. _section-3.2:
+
+The laboratory
+--------------
+
+Lintian creates a temporary lab in ``/tmp`` which is removed again after
+Lintian has completed its checks, unless the ``--keep-lab`` is used.
+
+.. _section-3.3:
+
+Writing your own Lintian checks
+-------------------------------
+
+This section describes how to write and deploy your own Lintian checks.
+Lintian will load checks from the following directories (in order):
+
+-  ``$LINTIAN_BASE/checks``
+
+Existing checks can be shadowed by placing a check with the same name in
+a directory appearing earlier in the list. This also holds for the
+checks provided by Lintian itself.
+
+Checks in Lintian consist of a Perl module implementing the actual check
+(.pm). The files names of such checks are expected to be in CamelCase. For
+the check name used on the command line, case transitions are replaced with
+hyphens. Perl's two colons (::) are replaced with a slash.
+
+Vendors are recommended to use their vendor name before the first slash
+(e.g. "ubuntu/fields").
+
+.. _section-3.3.1:
+
+Check description file
+~~~~~~~~~~~~~~~~~~~~~~
+
+The check description file is written in the same syntax as Debian
+control files as described in the `Debian Policy Manual
+§5.1 <https://www.debian.org/doc/debian-policy/#s-controlsyntax>`__.
+Check description files allow comments as described in the Policy
+Manual.
+
+The check description file has two paragraph types. The first is the
+check description itself and must be the first paragraph. The rest of
+the descriptions describe tags, one tag per paragraph.
+
+.. _section-3.3.1.1:
+
+Check description paragraph
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The fields in the check description paragraph are:
+
+*Check-Script* (simple, mandatory)
+   Name of the check. This is used to determine the package name of the
+   Perl module implementing the check.
+
+*Type* (simple, mandatory)
+   Comma separated list of package types for which this check should be
+   run. Allowed values in the list are "binary" (.deb files), "changes"
+   (.changes files), "source" (.dsc files) and "udeb" (.udeb files).
+
+*Info* (multiline, optional)
+   A short description of what the check is for.
+
+*Author* (simple, optional)
+   Name and email of the person, who created (or implemented etc.) the
+   check.
+
+*Abbrev* (simple, optional)
+   Alternative or abbreviated name of the check. These can be used with
+   certain command line options as an alternative name for the check.
+
+.. _section-3.3.1.2:
+
+Tag description paragraph
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The fields in the tag description paragraph are:
+
+*Tag* (simple, mandatory)
+   Name of the tag. It must consist entirely of the lower or/and upper
+   case characters ([a-zA-Z]), digits ([0-9]), underscore (_), dash (-)
+   and period (.). The tag name should be at most 68 characters long.
+
+*Severity* (simple, mandatory)
+   Determines the default value for the alert level. The value must be
+   one of "error", "warning", "info", "pedantic", or "classification".
+   This correlates directly to the one-letter code (of non-experimental
+   tags).
+
+*Info* (multiline, mandatory)
+   The tag descriptions can be found on Lintian's website
+   ("https://lintian.debian.org"). The description is in the standard
+   Markdown format.
+
+   The symbols &, < and > must be escaped as &amp;, &lt; and &gt;
+   (respectively). Please also escape _ as &lowbar; and * as &ast;.
+
+   Indented lines are considered "pre-formatted" and will not be line
+   wrapped. These lines are still subject to the allowed HTML tags and
+   above mentioned escape sequences.
+
+*Ref* (simple, optional)
+   A comma separated list of references. It can be used to refer to
+   extra documentation. It is primarily used for manual references, HTTP
+   links or Debian bug references.
+
+   If a reference contains a space, it is taken as a manual reference
+   (e.g. "policy 4.14"). These references are recorded in the
+   "output/manual-references" data file.
+
+   Other references include manpages ("lintian(1)"), ftp or http(s)
+   links ("https://lintian.debian.org"), file references
+   ("/usr/share/doc/lintian/changelog.gz") or Debian bug numbers
+   prefixed with a hash ("#651816").
+
+   Unknown references are (silently) ignored.
+
+*Experimental* (simple, optional)
+   Whether or not the tag is considered "experimental". Recognised
+   values are "no" (default) and "yes". Experimental tags always use "X"
+   as their "one-letter" code.
+
+.. _section-3.3.2:
+
+Check Perl module file
+~~~~~~~~~~~~~~~~~~~~~~
+
+This section describes the requirements for the Perl module implementing
+a given check.
+
+The Perl package name of the check must be identical to the check name
+(as defined by the "Check-Script" field in the description file) with
+the following transformations:
+
+-  All periods and dashes are replaced with underscores.
+
+-  All forward slashes are replaced by two colons (::).
+
+-  The resulting value is prefixed with "Lintian::".
+
+As an example, the check name ``contrib/hallo-world`` will result in the
+Perl package name ``Lintian::contrib::hallo_world``.
+
+.. _section-3.3.2.1:
+
+API of the "run" sub
+^^^^^^^^^^^^^^^^^^^^
+
+The Perl module must implement the sub called ``run`` in that Perl
+package. This sub will be run once for each package to be checked with 5
+arguments. These are (in order):
+
+-  The package name.
+
+-  The package type being checked in this run. This string is one of
+   "binary" (.deb), "changes" (.changes), "source" (.dsc) or "udeb"
+   (.udeb).
+
+-  An instance of API Lintian::Collect. Its exact type depends on the
+   type being processed and is one of Lintian::Collect::Binary (.deb or
+   .udeb), Lintian::Collect::Changes (.changes) or
+   Lintian::Collect::Source (.dsc).
+
+-  An instance of Lintian::Processable that represents the package being
+   processed.
+
+-  An instance of Lintian::ProcessableGroup that represents the other
+   processables in the given group. An instance of the
+   Lintian::Collect::Group is available via its "info" method.
+
+Further arguments may be added in the future after the above mentioned
+ones. Implementations should therefore ignore extra arguments beyond the
+ones they know of.
+
+If the run sub returns "normally", the check was run successfully.
+Implementations should ensure the return value is undefined.
+
+If the run sub invokes a trappable error (e.g. "die"), no further checks
+are done on the package and Lintian will (eventually) exit with 1 to its
+caller. The check may still be run on other packages.