-----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 <ni...@thykier.net> Richard Braakman <d...@xs4all.nl> Christian Schwarz <schw...@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 <ni...@thykier.net> Richard Braakman <d...@xs4all.nl> Christian Schwarz <schw...@monet.m.isar.de> Please use the email address <lintian-ma...@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"; }
lintian-info.pod.sig
Description: Binary data
lintian.pod.in.sig
Description: Binary data
generate-lintian-pod.sig
Description: Binary data