documentation

1 files changed, 111 insertions, 39 deletions

diff --git a/psresize2.pl b/psresize2.pl
index a5311bd..d37e2d4 100755
--- a/psresize2.pl
+++ b/psresize2.pl
@@ -1,25 +1,91 @@
 #!/usr/bin/perl -w
 
+=head1 NAME
+
+psresize2.pl - a better I<psresize>
+
 =head1 SYNOPSIS
 
-psnup2.pl - a better psnup
+B<psresize2.pl> [-w I<width> ] [-h I<heigth>] [-p I<paper>] [-W I<width>]
+[-H I<heigth>] [-P I<paper>] [-r I<rotation>] [-m I<margin>] [-c] [-q]
+[I<infile> [I<outfile>]]
+
+=head1 DESCRIPTION
+
+I<PSResize2> rescales and centres a document on a different size of paper.
+The input PostScript file should follow the Adobe Document Structuring
+Conventions.
+
+=head1 OPTIONS
+
+=over 8
+
+=item B<-w,--width>
+
+Specify the width of the output file. If the height is not specified as
+well, it will be ignored. The known units are B<pt>, B<in>, B<cm> and
+B<mm>. The default unit is B<pt>.
+
+=item B<-h,--height>
+
+Specify the height of the output file. If the width is not specified as
+well, it will be ignored. The known units are B<pt>, B<in>, B<cm> and
+B<mm>. The default unit is B<pt>.
+
+=item B<-p,--paper>
+
+Specify the paper size of the output file, as an alternative to B<-w>
+and B<-h>. Can be set to B<a0>, B<a1>, B<a2>, B<a3>, B<a4>, B<a5>, B<b5>,
+B<letter>, B<legal>, B<tabloid>, B<statement>, B<executive>, B<folio>,
+B<quarto>, or B<10x14>. The  default output paper size is B<a4>.
+
+=item B<-W,--Width>
+
+Same as the option B<-w>, but for the input file.
+
+=item B<-H,--Height>
 
-For details, see http://consodoc.com/psnup2/
+Same as the option B<-h>, but for the input file.
 
-=head1 USAGE
+=item B<-P,--paper>
 
-psnup2.pl -d -m <margin> -w <page_width> -h <page_height>
-          -l <n_long_edge> -s <n_short_edge> -r <reverse> -D
-          SOURCE [DEST]
+Same as the option B<-p>, but for the input file. By default,
+I<PSResize2> will try to guess this value from the header of the file,
+and fail if the information is missing. This option is useless if the
+crop option (B<-c>) is set.
 
--d  If specified, only prints out the command.
--m  Margin, in centimeters, that should be kept around the page. Default to 1.
--w  Resulting page width, in centimeters. Default to 21.
--h  Resulting page height, in centimeters. Default to 29.7.
--l  Number of pages to fit on the long edge. Default to 2.
--s  Number of pages to fit on the short edge. Default to 1.
--r  If specified, the order is reversed on the long edge.
--D  Rotation direction, if needed ("L" or "R"). Default to "L".
+=item B<-r,rotdir>
+
+If the file has to be rotated, this option determines the direction of
+the rotation. Can be set to B<L>, B<left>, B<R>, or B<right>. The default
+direction is B<L>.
+
+=item B<-m,--margin>
+
+Add a margin to the output file. Possible units are B<pt>, B<in>, B<cm>
+and B<mm>. The default unit is B<pt>. The default margin is B<1cm> if the
+crop option (B<-c>) is set, and B<0> otherwise.
+
+=item B<-c,--crop>
+
+If this option is set, I<PSResize2> will interpret the PostScript code to
+calculate the maximal effective bounding box. This operation may be quite
+demanding for the CPU.
+
+=item B<-q,--quiet>
+
+I<PSResize2> normally prints the page numbers of the pages output; this
+option suppresses this.
+
+=item B<--help>
+
+Display a brief help.
+
+=item B<--man>
+
+Display the manual page.
+
+=back
 
 =head1 REQUIRE
 
@@ -28,14 +94,17 @@ http://www.tardis.ed.ac.uk/~ajcd/psutils/
 
 =head1 AUTHOR
 
-Public domain, (c) Oleg Parashchenko, Lionel Guy
+I<PSResize2> is based on psnup2, by Oleg Parashchenko and Lionel Guy.
+
+Public domain, (c) Guilhem Moulin.
 
 =head1 VERSION
 
-Version: 0.0.5, 23 October 2008
+Version: 0.1, 25 September 2010
 
 =cut
 
+
 use Getopt::Long qw(:config no_ignore_case bundling); 
 use Pod::Usage;
 use IPC::Open2;
@@ -58,18 +127,18 @@ my $man;
 my $help;
 
 # TODO: "-m h1cm:v3cm": horizontal, vertical
-GetOptions( "w|width=s"    => \$outwidth,
-            "h|height=s"   => \$outheight,
-            "p|paper=s"    => sub { &papersize ($_[1],\$outwidth,\$outheight) },
-            "W|Width=s"    => \$inwidth,
-            "H|Height=s"   => \$inheight,
-            "P|Paper=s"    => sub { &papersize ($_[1],\$inwidth,\$inheight) },
-            "m|margin=s"   => \$margin,
-            "c|crop"       => \$crop,
-            "r|rotation=s" => \$rotdir,
-            "q|quiet"      => \$quiet,
-            "help"         => \$help,
-            "man"          => \$man )
+GetOptions( "w|width=s"  => \$outwidth,
+            "h|height=s" => \$outheight,
+            "p|paper=s"  => sub { &papersize ($_[1],\$outwidth,\$outheight) },
+            "W|Width=s"  => \$inwidth,
+            "H|Height=s" => \$inheight,
+            "P|Paper=s"  => sub { &papersize ($_[1],\$inwidth,\$inheight) },
+            "r|rotdir=s" => \$rotdir,
+            "m|margin=s" => \$margin,
+            "c|crop"     => \$crop,
+            "q|quiet"    => \$quiet,
+            "help"       => \$help,
+            "man"        => \$man )
     or  pod2usage(2);
 
 pod2usage(1)  if  (defined $help  or $#ARGV > 1);
@@ -142,10 +211,10 @@ if (defined $crop) {
     my ($x0, $y0, $x1, $y1) = (1<<16, 1<<16, -(1<<16), -(1<<16));
     while (<GS>) {
         if ($_ =~ m/^\%\%BoundingBox: (\d+) (\d+) (\d+) (\d+)/) {
-    	    $x0 = $1 if $1 < $x0;
-    	    $y0 = $2 if $2 < $y0;
-    	    $x1 = $3 if $3 > $x1;
-    	    $y1 = $4 if $4 > $y1;
+            $x0 = $1 if $1 < $x0;
+            $y0 = $2 if $2 < $y0;
+            $x1 = $3 if $3 > $x1;
+            $y1 = $4 if $4 > $y1;
             print STDERR "[", ++$n, "] ";
         }
     }
@@ -205,9 +274,9 @@ while (defined ($l = <FINPS2PS>)  &&  $l ne "\%\%EndComments\n") {
     next if $l =~ m/^\%\%DocumentMedia:/;
 
     if ($l =~ m/^\%\%BoundingBox:/) {
-	    print FOUT "\%\%BoundingBox: 0 0 $outwidth $outheight\n"
+        print FOUT "\%\%BoundingBox: 0 0 $outwidth $outheight\n"
             or  die "Can't print: $!";
-	    next;
+        next;
     }
     print FOUT $l  or  die "Can't print: $!";
 }
@@ -228,8 +297,8 @@ while (<FINPS2PS>) {
     # PStoPSclip hack: increase clipping box by 10
     if ($_ =~ m/^userdict\/PStoPSclip{0 0 moveto$/) {
         $l = <FINPS2PS>;
-	    $l =~ s/\./0./g;
-	    print FOUT $l  or  die "Can't print: $!";
+        $l =~ s/\./0./g;
+        print FOUT $l  or  die "Can't print: $!";
     }
 }
 
@@ -239,6 +308,10 @@ close FOUT;
 # No zombie processes
 waitpid $pid, 0;
 
+# Useless, but Perl doesn't see that this filehandle is used more than
+# one time (and even automatically closed by `open3')
+exit 0;
+close KIDFIN;
 
 
 
@@ -299,8 +372,7 @@ sub calculate_coordinates {
     my ($length, $margin) = @_;
     my $skip     = $length - $margin;
     my $outwidth = $skip - $margin;
-    my @coords = ( &round( &round($skip) - $outwidth ), &round($skip) );
-    return @coords;
+    return ( &round( &round($skip) - $outwidth ), &round($skip) );
 }
 
 
@@ -338,7 +410,7 @@ sub topoints {
 
 
 #
-# In-place set the given width and length to the predefined papersize
+# In-place set the given width and height to the predefined papersize
 #
 sub papersize {
     my ($p,$w,$h) = @_;