From 813134ccd910249b87938662194698937268333b Mon Sep 17 00:00:00 2001
From: Jari Aalto <jari.aalto@cante.net>
Date: Mon, 29 Mar 2010 21:55:33 +0300
Subject: [PATCH] Convert man/dpkg-parsechangelog.1 into POD format.
Organization: Private
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 8bit

Add sections EXAMPLES, SEE ALSO. Adjust AUTHORS to include 'version 2'
excerpt from GNU GPL verbatim. Order OPTTIONS section alphabetically,
except the --help and --version options. Mentiont that if option
--all is in use, other options have no effect.

Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 man/dpkg-parsechangelog.1.pod |  209 +++++++++++++++++++++++++++++++++++++++++
 1 files changed, 209 insertions(+), 0 deletions(-)
 create mode 100644 man/dpkg-parsechangelog.1.pod

diff --git a/man/dpkg-parsechangelog.1.pod b/man/dpkg-parsechangelog.1.pod
new file mode 100644
index 0000000..b1c708e
--- /dev/null
+++ b/man/dpkg-parsechangelog.1.pod
@@ -0,0 +1,209 @@
+#   License
+#
+#       This program is free software; you can redistribute it and/or modify
+#       it 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 program 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 program. If not, see <http://www.gnu.org/licenses/>.
+#
+#   Description
+#
+#	This manual page is in Perl POD format. Read more at
+#	http://perldoc.perl.org/perlpod.html
+#
+#	See also POSIX/Susv standard and "Utility Description Defaults" at
+#	http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_11
+
+=pod
+
+=head1 NAME
+
+dpkg-parsechangelog - parse Debian changelog files
+
+=head1 SYNOPSIS
+
+    dpkg-parsechangelog [options]
+
+=head1 DESCRIPTION
+
+dpkg-parsechangelog reads and parses the changelog file of an unpacked
+Debian source tree and outputs the information in it to standard
+output in a machine-readable form.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-Fchangelogformat>
+
+Specifies the format of the changelog. By default the format is read
+from a special line near the bottom of the changelog or failing that
+defaults to the debian standard format.
+
+=item B<-lchangelogfile>
+
+Specifies the change log file to read information from. The default is
+C<debian/changelog>.
+
+=item B<-Llibdir>
+
+Specify an additional directory to search for parser scripts. This
+directory is searched before the default directories which are
+currently C</usr/local/lib/dpkg/parsechangelog> and
+C</usr/lib/dpkg/parsechangelog>.
+
+=item B<-h, --help>
+
+Show the usage message and exit.
+
+=item B<--version>
+
+Show the version and exit.
+
+=back
+
+=head2 Parser Options
+
+The following options can be used to influence the output of the
+changelog parser, e.g. the range of entries or the format of the
+output. They need to be supported by the parser script in question.
+See also section CAVEATS.
+
+=over 4
+
+=item B<--all>
+
+Include all changes. Note: other options have no effect if this is in
+use.
+
+=item B<--count NUMBER, -cNUMBER, -nNUMBER>
+
+Include NUMBER entries from the top (or the tail if number is lower
+than 0).
+
+=item B<--format OUTPUT_FORMAT>
+
+Set the output format. Currently supported values are I<dpkg> and
+I<rfc822>. I<dpkg> is the classic output format (from before this
+option existed) and the default. It consists of one paragraph in
+Debian control format; see deb-control(5). If more than one entry is
+requested, then most fields are taken from the latest entry, except
+otherwise stated:
+
+    Source: <pkg name>
+
+    Version: <version>
+
+    Distribution: <target distribution>
+
+    Urgency: <urgency>
+           The highest urgency of all included entries is used.
+
+    Maintainer: <author>
+
+    Date: <date>
+
+    Closes: <bug number>
+           The Closes fields of all included entries are merged.
+
+    Changes: <changelog entries>
+           The text of all changelog entries is concatenated. To make
+           this field a valid Debian control format multiline field
+           empty lines are replaced with a single full stop and all
+           lines is intended by one space character. The exact content
+           depends on the changelog format.
+
+There might be additional user-defined fields present.
+
+The rfc822 format uses the same fields but outputs a separate
+paragraph for each changelog entry so that all metadata for each entry
+is preserved.
+
+=item B<--from VERSION, -fVERSION>
+
+Include all changes equal or later than version.
+
+=item B<--offset NUMBER, -oNUMBER>
+
+Change the starting point for B<--count>, counted from the top (or the
+tail if number is lower than 0).
+
+=item B<--since version, -sversion, -vversion>
+
+Include all changes later than VERSION.
+
+=item B<--to VERSION, -tVERSION>
+
+Include all changes up to or equal than VERSION.
+
+=item B<--until VERSION, -uVERSION>
+
+Include all changes earlier than VERSION.
+
+=back
+
+=head1 EXAMPLES
+
+Display three latest entries:
+
+    dpkg-parsechangelog --count 3
+
+Display when was package first worked on:
+
+    dpkg-parsechangelog --count -1
+
+Display second latest entry:
+
+    dpkg-parsechangelog --offset 1 --count 1
+
+=head1 CAVEATS
+
+All I<Parser Options> except for B<--since> are only supported in
+dpkg(1), version 1.14.16 and later. Third party parsers for changelog
+formats other than debian might not support all options.
+
+=head1 ENVIRONMENT
+
+None.
+
+=head1 FILES
+
+=over 4
+
+=item B<debian/changelog>
+
+The changelog file, used to obtain version-dependent information about
+the source package, such as the urgency and distribution of an upload,
+the changes made since a particular release, and the source version
+number itself.
+
+=back
+
+=head1 SEE ALSO
+
+dpkg(1)
+dpkg-query(1)
+
+=head1 AUTHORS
+
+Program was written by Ian Jackson.
+
+This manual page was is:
+
+       Copyright © 2010 Jari Aalto <jari.aalto@cante.net>
+       Copyright © 2007, 2008 Frank Lichtenheld
+       Copyright © 2000 Wichert Akkerman
+       Copyright © 1995-1996 Ian Jackson
+
+Released under license GNU GPL version 2 or (at your option) any later
+version. There is NO WARRANTY. For more information about license,
+visit <http://www.gnu.org/copyleft/gpl.html>.
+
+=cut
-- 
1.7.0

