Use italics in man pages to highlight which parts of command lines are file names...

diff --git a/debian/changelog b/debian/changelog
index 3cfe55e..672c0b9 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,10 @@
+pristine-tar (1.01) UNRELEASED; urgency=low
+
+  * Use italics in man pages to highlight which parts of command
+    lines are file names. Closes: #561015
+
+ -- Joey Hess <joeyh@debian.org>  Mon, 14 Dec 2009 14:07:44 -0500
+
 pristine-tar (1.00) unstable; urgency=low
 
   * pristine-gz: Fall back to storing a binary delta, in the rare

diff --git a/pristine-bz2 b/pristine-bz2
index 212e350..abd1ba9 100755 (executable)
--- a/pristine-bz2
+++ b/pristine-bz2
@@ -6,9 +6,9 @@ pristine-bz2 - regenerate pristine bz2 files
 
 =head1 SYNOPSIS
 
-B<pristine-bz2> [-vdk] genbz2 delta file
+B<pristine-bz2> [-vdk] gendelta I<file.bz2> I<delta>
 
-B<pristine-bz2> [-vdk] gendelta file.bz2 delta
+B<pristine-bz2> [-vdk] genbz2 I<delta> I<file>
 
 =head1 DESCRIPTION
 
@@ -16,14 +16,14 @@ This is a complement to the pristine-tar(1) command. Normally you
 don't need to run it by hand, since pristine-tar calls it as necessary
 to handle .tar.bz2 files.
 
-pristine-bz2 gendelta takes the specified bz2 file, and generates a
-small binary delta file that can later be used by pristine-bz2 genbz2
+pristine-bz2 gendelta takes the specified I<bz2> file, and generates a
+small binary I<delta> file that can later be used by pristine-bz2 genbz2
 to recreate the original file.
 
-pristine-bz2 genbz2 takes the specified delta file, and compresses the
-specified input file (which must be identical to the contents of the
-original bz2 file). The resulting bz2 file will be identical to the
-original bz2 file.
+pristine-bz2 genbz2 takes the specified I<delta> file, and compresses the
+specified input I<file> (which must be identical to the contents of the
+original bz2 file). The resulting file will be identical to
+the original gz file used to create the delta.
 
 The approach used to regenerate the original bz2 file is to figure out
 how it was produced -- what compression level was used, whether it was
@@ -88,8 +88,8 @@ my $debug=0;
 my $keep=0;
 
 sub usage {
-       print STDERR "Usage: pristine-bz2 [-vdk] genbz2 delta file\n";
-       print STDERR "       pristine-bz2 [-vdk] gendelta file.bz2 delta\n";
+       print STDERR "Usage: pristine-bz2 [-vdk] gendelta file.bz2 delta\n";
+       print STDERR "       pristine-bz2 [-vdk] genbz2 delta file\n";
 }
 
 sub debug {

diff --git a/pristine-gz b/pristine-gz
index a29b428..f225dde 100755 (executable)
--- a/pristine-gz
+++ b/pristine-gz
@@ -6,9 +6,9 @@ pristine-gz - regenerate pristine gz files
 
 =head1 SYNOPSIS
 
-B<pristine-gz> [-vdk] gengz delta file
+B<pristine-gz> [-vdk] gendelta I<file.gz> I<delta>
 
-B<pristine-gz> [-vdk] gendelta file.gz delta
+B<pristine-gz> [-vdk] gengz I<delta> I<file>
 
 =head1 DESCRIPTION
 
@@ -16,14 +16,14 @@ This is a complement to the pristine-tar(1) command. Normally you don't
 need to run it by hand, since pristine-tar calls it as necessary to handle
 .tar.gz files.
 
-pristine-gz gendelta takes the specified gz file, and generates a
-small binary delta file that can later be used by pristine-gz gengz
+pristine-gz gendelta takes the specified I<gz> file, and generates a
+small binary I<delta> file that can later be used by pristine-gz gengz
 to recreate the original file.
 
-pristine-gz gengz takes the specified delta file, and compresses
-the specified input file (which must be identical to the contents
-of the original gz file). The resulting gz file will be identical to the
-original gz file.
+pristine-gz gengz takes the specified I<delta> file, and compresses
+the specified input I<file> (which must be identical to the contents
+of the original gz file). The resulting file will be identical to
+the original gz file used to create the delta.
 
 The approach used to regenerate the original gz file is to figure out how
 it was produced -- what compression level was used, whether it was built
@@ -133,8 +133,8 @@ my $debug=0;
 my $keep=0;
 
 sub usage {
-       print STDERR "Usage: pristine-gz [-vdk] gengz delta file\n";
-       print STDERR "       pristine-gz [-vdk] gendelta file.gz delta\n";
+       print STDERR "Usage: pristine-gz [-vdk] gendelta file.gz delta\n";
+       print STDERR "       pristine-gz [-vdk] gengz delta file\n";
 }
 
 sub debug {

diff --git a/pristine-tar b/pristine-tar
index d2942fc..2a97090 100755 (executable)
--- a/pristine-tar
+++ b/pristine-tar
@@ -6,22 +6,23 @@ pristine-tar - regenerate pristine tarballs
 
 =head1 SYNOPSIS
 
-B<pristine-tar> [-vdk] gentar delta tarball
+B<pristine-tar> [-vdk] gendelta I<tarball> I<delta>
 
-B<pristine-tar> [-vdk] gendelta tarball delta
+B<pristine-tar> [-vdk] gentar I<delta> I<tarball>
 
-B<pristine-tar> [-vdk] [-m message] commit tarball [upstream]
+B<pristine-tar> [-vdk] [-m message] commit I<tarball> [I<upstream>]
 
-B<pristine-tar> [-vdk] checkout tarball
+B<pristine-tar> [-vdk] checkout I<tarball>
 
 =head1 DESCRIPTION
 
-pristine-tar can regenerate a pristine upstream tarball using only a small
-binary delta file and a revision control checkout of the upstream branch.
+pristine-tar can regenerate an exact copy of a pristine upstream tarball
+using only a small binary I<delta> file and the contents of the tarball,
+which are typically kept in an I<upstream> branch in version control.
  
-The delta file is designed to be checked into revision control along-side
-the upstream branch, thus allowing Debian packages to be built entirely
-using sources in revision control, without the need to keep copies of
+The I<delta> file is designed to be checked into version control along-side
+the I<upstream> branch, thus allowing Debian packages to be built entirely
+using sources in version control, without the need to keep copies of
 upstream tarballs.
 
 pristine-tar supports compressed tarballs, calling out to pristine-gz(1)
@@ -31,32 +32,32 @@ and pristine-bz2(1) to produce the pristine gzip and bzip2 files.
 
 =over 4
 
-=item pristine-tar gendelta
+=item pristine-tar gendelta I<tarball> I<delta>
 
-This takes the specified upstream tarball, and generates a small binary
+This takes the specified upstream I<tarball>, and generates a small binary
 delta file that can later be used by pristine-tar gentar to recreate the
 tarball.
 
 If the delta filename is "-", it is written to standard output.
 
-=item pristine-tar gentar 
+=item pristine-tar gentar I<delta> I<tarball>
 
-This takes the specified delta file, and the files in the current
+This takes the specified I<delta> file, and the files in the current
 directory, which must have identical content to those in the upstream
-tarball, and uses these to regenerate the pristine upstream tarball.
+tarball, and uses these to regenerate the pristine upstream I<tarball>.
 
 If the delta filename is "-", it is read from standard input.
 
-=item pristine-tar commit
+=item pristine-tar commit I<tarball> [I<upstream>]
 
 B<pristine-tar commit> generates a pristine-tar delta file for the specified
-tarball, and commits it to version control. The B<pristine-tar checkout>
+I<tarball>, and commits it to version control. The B<pristine-tar checkout>
 command can later be used to recreate the original tarball based only
 on the information stored in version control.
 
 For B<pristine-tar checkout> to work, you also need to store the precise
 contents of the tarball in version control. To specify in which tag (or
-branch or other treeish object) it's stored, use the B<upstream> parameter.
+branch or other treeish object) it's stored, use the I<upstream> parameter.
 This defaults to "refs/heads/upstream", or if there's no such branch, any
 branch matching "upstream". The name of the tree it points to will be
 recorded for later use by B<pristine-tar checkout>.
@@ -65,10 +66,10 @@ The delta files are stored in a branch named "pristine-tar", with filenames
 corresponding to the input tarball, with ".delta" appended. This
 branch is created or updated as needed to add each new delta.
 
-=item pristine-tar checkout
+=item pristine-tar checkout I<tarball>
 
-This regenerates a copy of the specified tarball using information
-previously saved to revision control by B<pristine-tar commit>.
+This regenerates a copy of the specified I<tarball> using information
+previously saved in version control by B<pristine-tar commit>.
 
 =back
 
@@ -150,8 +151,8 @@ my $message;
 $ENV{LANG}='C';
 
 sub usage {
-       print STDERR "Usage: pristine-tar [-vdk] gentar delta tarball\n";
-       print STDERR "       pristine-tar [-vdk] gendelta tarball delta\n";
+       print STDERR "Usage: pristine-tar [-vdk] gendelta tarball delta\n";
+       print STDERR "       pristine-tar [-vdk] gentar delta tarball\n";
        print STDERR "       pristine-tar [-vdk] [-m message] commit tarball [upstream]\n";
        print STDERR "       pristine-tar [-vdk] checkout tarball\n";
        exit 1;