summaryrefslogtreecommitdiffstats
path: root/doc/lintian.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-14 13:42:30 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-14 13:42:30 +0000
commit75808db17caf8b960b351e3408e74142f4c85aac (patch)
tree7989e9c09a4240248bf4658a22208a0a52d991c4 /doc/lintian.rst
parentInitial commit. (diff)
downloadlintian-75808db17caf8b960b351e3408e74142f4c85aac.tar.xz
lintian-75808db17caf8b960b351e3408e74142f4c85aac.zip
Adding upstream version 2.117.0.upstream/2.117.0upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/lintian.rst')
-rw-r--r--doc/lintian.rst992
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.