-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hey I understood from [1] that there has been an interest in rewriting the lintian man pages in POD, so I spent a couple of hours doing just that. I figured that the CHECKS and COLLECTION sections of the lintian manpage could mostly be auto-generated from checks/*.desc and collection/*.desc (respectively), which would save us time keeping them in sync. "generate-lintian-pod" was written for just that. Dump generate-lintian-pod in private/ and run it like: $ private/generate-lintian-pod man/lintian.pod.in > man/lintian.pod Of course this will require that all checks and collection desc files actually have an "info" field, which they do not at the current time. Alternatively if it is not possible to completely reuse info in all cases, I made it possible to use a "Manpage" field that will be used instead. Do you think this would work, or would it be better just to keep this information static in the pod file and manually update it? ~Niels [1] http://wiki.debian.org/Teams/Lintian -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.10 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iQIcBAEBCAAGBQJNGOTTAAoJEAVLu599gGRC6OUP/0NtnUFEbMsupYu9jcwV93lS UPtzfwX+hw8hHs8yCVwIHbihJhKkWpVsWqbZKRUaTeQvMUMySqdUtIICPK6pKe/w CUmEVN5m10vv09owtssYMRptmFPGYLJNZloTxdmjVdXj5ik0o++nt6rQ6wq+DEr3 DLunLaOzPuW2m8GrpCyJ2SSk1o+uoZb1ltPlggWR5NMUADbPrgEZTzKPawGxgNrD jFRNJwPpLLVhGG1a5wtKc/XK7svlhKHw8pPKsrudP2iWQCcmjDHtACpzwj0t3a94 4naWBS/jekZWRTNee9xq+xjsOoKyx4Hpm8TUWajnY37HjmRtOO1/bR0x9SJZTb/c xgAiO4HYMia0OqUugF1DE32F0ndm6gS5ip6I0fLvVDt1o0Ae+qs/zExRr+A9M9cz DQy8WP8e2scbZKLL+79n70JY2aPi6gbv87GfnF3aHz5xciF2bz046b7Tr96N8ttQ qCOcfPowT6/j4n1KmTOWbPEP1uANVnx/U+LADVUvgIQG1aVve9z87XXmbCDyNcDt ifSETCtuOVVLTLFw63OZt/uCs1vWMOp7//8Rx46VUGUI+U/Uxuh/guS/I0ordzDl DHL69FYO2NF88sQuik+d9mV+lewqBaEVA22NTmNka1NqYd6b4GZgLUoED6hAIyvw zfR1f2Mk+U9VhaIfqBWz =FqVk -----END PGP SIGNATURE-----
# Copyright 2010 Niels Thyker # - 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-info - give detailed information about Lintian's error tags =head1 SYNOPSIS B<lintian-info> [I<log-file>...] B<lintian-info> B<--tags> I<tag> ... =head1 DESCRIPTION The B<lintian-info> command parses the output of the B<lintian> command and gives verbose information about the listed Lintian error tags, parses a Lintian override file and gives verbose information about the tags included, or (if given the B<-t> or B<--tags> option) explains a given tag or tags. If no log-file is specified on the command line, this command expects its input on stdin. Thus, the output of B<lintian> can either be piped through B<lintian-info> or a log file produced by B<lintian> can be processed with this command. (Note, though, that the B<lintian> command has a command line option B<-i> to display the same results as B<lintian-info>, so you will not normally need to pipe the output of B<lintian> into this command.) =head1 OPTIONS =over 4 =item B<-a>, B<--annotate> Read from standard input or any files specified on the command line and search the input for lines formatted like Lintian override entries. For each one that was found, display verbose information about that tag. =item B<-h>, B<--help> Display usage information and exit. =item B<-t>, B<--tags> Rather than treating them as log file names, treat any command-line options as tag names and display the descriptions of each tag. =back =head1 EXIT STATUS If B<-t> or B<--tags> was given and one or more of the tags specified were unknown, this command returns the exit code 1. Otherwise, it always returns with exit code 0. =head1 SEE ALSO L<lintian(1)> =head1 AUTHORS Niels Thykier <niels@thykier.net> Richard Braakman <dark@xs4all.nl> Christian Schwarz <schwarz@monet.m.isar.de> =cut
# Copyright 2010 Niels Thyker
# - 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.
It uses an archive directory, called I<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.
There are three 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), by package name, or by naming
a I<.changes> file. If you list packages by package name, you'll have to
define the B<LINTIAN_DIST> variable in the configuration file (see
below). Lintian will then search for any binary or source packages in
this directory for packages with the given name. (You can use the
B<-b> (B<--binary>), B<--udeb> and B<-s> (B<--source>) options if you
only want to process binary, udeb or source packages.)
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.
=head1 OPTIONS
Actions of the lintian command: (Only one action can be specified per invocation)
=over 4
=item B<-S>, B<--setup-lab>
Set up or update the laboratory.
=item B<-R>, B<--remove-lab>
Remove the laboratory directory.
=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<-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.
=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.
=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 option does not, as yet, ignore overrides for fatal
tags for which overrides aren't allowed.
=item B<-X> chk1,chk2,..., B<--dont-check-part> chk1,chk2,...
Run all but the 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<-u>, B<--unpack>
Unpack the specified packages up to the current unpack level. The
default and only unpack level is 1 for this option. See the L</UNPACK
LEVELS> section below.
=item B<-r>, B<--remove>
Clean up the lintian directory of the specified packages up to the
current unpack level. The default unpack level is 0 for this option.
=back
General options:
=over 4
=item B<-h>, B<--help>
Display usage information and exit.
=item B<-V>, B<--version>
Display lintian version number and exit.
=item B<--print-version>
Print unadorned version number and exit.
=item B<-v>, B<--verbose>
Display verbose messages.
=item B<-d>, B<--debug>
Display debugging messages. (Implies B<-v>).
=item B<-q>, B<--quiet>
Suppress all informational messages. Currently, the only message this
suppresses is the message at the end of the run giving the total count
of overrides.
=back
Behaviour options for B<lintian>.
=over 4
=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-info(1)>..
=item B<-I>, B<--display-info>
Display informational ("I:") tags as well. They are normally
suppressed. (This is equivalent to B<-L> ">=wishlist").
=item B<-E>, B<--display-experimental>
Display experimental ("X:") tags as well. 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 welcomed (particularly if they include fixes).
=item B<--pedantic>
Display pedantic ("P:") tags as well. They are normally suppressed.
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.
=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 severity (S:
serious, important, normal, minor, wishlist), a certainty (C: certain,
possible, wild-guess), or both (S/C). The default settings are
equivalent to B<-L> ">=important" B<-L> "+>=normal/possible" B<-L>
+minor/certain).
=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.
=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.
=item B<-l> n, B<--unpack-level> n
Set unpack level to I<n>. See the L</UNPACK LEVELS> section, below.
=item B<-o>, B<--no-override>
Don't use the overrides file.
=item B<--show-overrides>
Output tags that have been overridden.
=item B<--color> (never|always|auto|html)
Whether to colorize tags in lintian output based on their severity.
The default is "never", which never uses color. "always" will always
use color, "auto" will use color only if the output is going to a
terminal, and "html" will use HTML E<lt>spanE<gt> tags with a color style
attribute (instead of ANSI color escape sequences).
=item B<-U> info1,info2,..., B<--unpack-info> info1,info2,...
Collect information info1, info2, etc. even if these are not required
by the checks.
=item B<-m>, B<--md5sums>, B<--checksums>
Check checksums when processing a .changes file. Normally, Lintian
only checks the checksums for .dsc files when processing a .changes
file.
=item B<--allow-root>
Override lintian's warning when it is run with superuser privileges.
=item B<--fail-on-warnings>
By default, B<lintian> exits with 0 status if only warnings were
found. If this flag is given, exit with a status of 1 if either
warnings or errors are found.
=item B<--keep-lab>
By default, temporary labs will be removed after lintian is finished.
Specifying this options will leave the lab behind, which might be
useful for debugging purposes. You can find out where the temporary
lab is located by running lintian with the B<--verbose> option.
Implies B<--unpack-level=2> unless another unpack level is specified
directly.
=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<--lab> labdir
Use labdir as the permanent laboratory. This is where Lintian keeps
information about the packages it checks. This option overrides the
B<LINTIAN_LAB> environment variable and the configuration file entry
of the same name.
=item B<--archivedir> archivedir
Location of Debian archive to scan for packages. (See the L</FILES>
section for complete information on how the path is constructed.) Use
this if you want Lintian to check the whole Debian archive instead of
just single packages. This option overrides the B<LINTIAN_ARCHIVEDIR>
environment variable and the configuration file entry of the same
name.
=item B<--dist> distdir
Scan for packages in the I<distdir> directory. (See the L</FILES>
section for complete information on how the path is constructed.) Use
this if you want Lintian to check the whole Debian archive instead of
just single packages. This option overrides the B<LINTIAN_DIST>
environment variable and the configuration file entry of the same
name.
=item B<--area> area
When scanning for packages in the distdir, select only packages from
the comma-separated list of archive I<areas> (e.g. main, contrib).
This option overrides the B<LINTIAN_AREA> environment variable and the
configuration file entry of the same name.
=item B<--section> area
This is an old name for the B<--area> option and accepted as a synonym
for that option.
=item B<--arch> arch
When scanning for packages in the distdir, select only packages for
architecture I<arch>. This option overrides the B<LINTIAN_ARCH>
environment variable and the configuration file entry of the same
name.
=item B<--root> rootdir
Look for B<lintian>'s support files (such as check scripts and
collection scripts) in rootdir. This overrides the B<LINTIAN_ROOT>
environment variable. The default location is I</usr/share/lintian>.
=back
Package selection options:
=over 4
=item B<-a>, B<--all>
Check all packages in the distribution. (This requires that the
LINTIAN_DIST variable is defined in the configuration file.)
=item B<-b>, B<--binary>
The following packages listed on the command line are binary packages.
=item B<-s>, B<--source>
The following packages listed on the command line are source packages.
=item B<--udeb>
The following packages listed on the command line are udeb packages.
=item B<-p> X, B<--packages-file> X
Process all packages which are listed in file X. Each package has to
be listed in a single line using the following format:
B<type> B<package> B<version> B<file>
where B<type> is either `b', `u', or `s' (binary, udeb, or source
package), B<package> is the package name, B<version> is the package's
version, and B<file> is the package file name (absolute path
specification).
=back
=head1 UNPACK LEVELS
=over 4
=item B<0 (none)>
The package does not exist in the I<laboratory> at all.
=item B<1 (basic)>
A directory for this package exists in the I<laboratory> and basic
information is extracted. This does not take much space.
For binary and udeb packages, the I<control> and I<fields> directories
and the index file are unpacked, and symbolic links are made to the
B<.deb> file and to the lintian directory for the source package.
For source packages, the binary and fields directories are unpacked,
and symbolic links are made to the source package files.
=item B<2 (contents)>
This unpack level is deprecated and no longer functional. The
I<unpacked> collection script replaced it.
=back
Lintian will unpack packages as far as is necessary to do its checks,
but it will leave the package in whatever unpack level was specified
when it is done.
The default unpack level can be overwritten by setting the
B<LINTIAN_UNPACK_LEVEL> variable in the configuration file.
=head1 CHECKS
@CHECKS@
=head1 COLLECTION
@COLLECTION@
=head1 FILES
Lintian looks for its configuration file in the following locations:
The directory given with the --cfg option
=over 4
=item I<$LINTIAN_CFG>
=item I<$LINTIAN_ROOT/lintianrc>
=item I<$HOME/.lintianrc>
=item I</etc/lintianrc>
=back
Lintian uses the following directories:
=over 4
=item I</tmp>
If no lab location is specified via the LINTIAN_LAB environment
variable, configuration, or the B<--lab> command-line option, 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.
=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.
=item I</usr/share/lintian/unpack>
Scripts that manage the I<laboratory>.
=back
The I</usr/share/lintian> directory can be overridden with the
B<LINTIAN_ROOT> environment variable or the B<--root> option.
When looking for packages in a Debian archive, lintian constructs the
path to the archive from the I<archivedir>, I<distdir>, I<release>,
and I<arch> as follows:
I<archivedir>/dists/I<distdir>/I<release>/I<arch>
Lintian always expects the "/dists/" path component in paths to Debian archives.
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 EXIT STATUS
=over 4
=item B<0>
No policy violations or major errors detected.
(There may have been warnings, though.)
=item B<1>
Policy violations or major errors detected.
=item B<2>
Lintian run-time error. An error message is sent to stderr.
=back
=head1 EXAMPLES
=over 4
=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 +minor/possible>
Check source package foo given by foo.dsc, including minor/possible
tags.
=item B<$ lintian foo>
Search for package foo in the Debian archive and check it. (Depending
on what is found, this command will check either the source or binary
package foo, or both.)
=item B<$ lintian --archivedir /var/packages --dist custom --section main>
Check all packages found in the Debian archive at
I</var/packages/dists/custom/main>.
=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 -c --binary foo>
Search for binary package foo in the Debian archive and check it.
=item B<$ lintian -C cpy --source foo>
Run the copyright checks on source package foo.
=item B<$ lintian -u foo>
Unpack package foo in the Lintian laboratory up to level 1. (If it's
already unpacked at level 1 or 2, nothing is done.)
=item B<$ lintian -l1 -r foo>
Search for package foo in the Debian archive and, if found, reduce the
package disk usage in the laboratory to level 1.
=item B<$ lintian -r foo>
Remove package foo from the Lintian laboratory.
=back
=head1 BUGS
Lintian does not have any locking mechanisms yet.
(Running several checks simultaneously is likely to fail.)
If you discover any other bugs in lintian, please contact the authors.
=head1 SEE ALSO
L<lintian-info(1)>, Lintian User Manual
(file:/usr/share/doc/lintian/lintian.html/index.html)
Packaging tools: L<debhelper(7)>, L<dh_make(8)>,
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
#!/usr/bin/perl
use strict;
use Util qw(read_dpkg_control fail);
open(my $file, "<", "man/lintian.pod.in") or fail("man/lintian.pod.in: $1");
while(my $line = <$file>){
chomp($line);
if($line eq '@CHECKS@'){
extract_data('checks', 'check-script', 'abbrev');
} elsif($line eq '@COLLECTION@'){
extract_data('collection', 'collector-script');
} else {
print "$line\n";
}
}
close($file);
sub prettify {
my $text = shift;
$text =~ s/\n\s\.\n\s/\n\n\n/og;
$text =~ s/\n\s/\n/og;
$text =~ s/\&([^;]+)\;/E<$1>/og; # do > -> E<gt>
$text =~ s/(\S+\(\d+\))/L<$1>/og; # link to manpages
return $text;
}
sub extract_data {
my ($folder, $name, $abname) = @_;
print "=over 4\n\n";
foreach my $file (<$folder/*.desc>) {
my ($header, @ignore) = read_dpkg_control($file);
my $name = $header->{$name};
my $abbr;
my $desc;
next if($name eq 'lintian');
if(defined($abname)){
$abbr = $header->{$abname};
}
if(!defined($header->{'manpage'})){
$desc = $header->{'info'};
} else {
$desc = $header->{'manpage'};
}
$desc = prettify($desc);
if($abbr){
print "=item B<$name> (B<$abbr>)";
} else {
print "=item B<$name>"
}
print "\n\n$desc\n\n";
}
print "=back\n\n";
}
Attachment:
lintian-info.pod.sig
Description: Binary data
Attachment:
lintian.pod.in.sig
Description: Binary data
Attachment:
generate-lintian-pod.sig
Description: Binary data