Documentation

1 files changed, 76 insertions, 3 deletions

diff --git a/pdftool.pl b/pdftool.pl
index 0761ad1..589aa8c 100755
--- a/pdftool.pl
+++ b/pdftool.pl
@@ -20,7 +20,39 @@ B<pdftool.pl> [-s I<pages>] [-p I<paper>] [-m I<margin>] [-c] [-b]
 
 =head1 DESCRIPTION
 
-I<PDFTool>
+I<PDFTool> combines the tools in the PSUtils bundle in a nice way. The
+input should be either a Portable Document Format (PDF) file, or a
+PostScript file. The output format is the same as the input one.
+
+If no input file is given, or if a single hyphen-minus (B<->) is given as
+file name, I<PDFTool> will read the PDF or PostScript data from the standard
+input. In that case, and if the input data is in PDF format, an
+auxiliary file will be created (since the conversion from PDF to PS
+requires random access to the data), and removed afterwards.
+An other auxiliary file may be created by I<PSResize2>, see its man page
+for details.
+
+If no output file is given, or if a single hyphen-minus (B<->) is given as
+file name, I<PDFTool> will send the data (of the same type as the input) to
+the standard output.
+
+The document will be treated as follows:
+
+=over 8
+
+=item Conversion from PDF to PostScript (if necessary),
+
+=item Selection of the page range,
+
+=item Resizing to the given papersize, adding a margin, and croping, 
+
+=item Rearranging pages for printing books or booklets,
+
+=item Putting several pages per sheets,
+
+=item Conversion from PS to PDF (if necessary).
+
+=back
 
 =head1 OPTIONS
 
@@ -28,16 +60,55 @@ I<PDFTool>
 
 =item B<-s, --select>
 
+Specifies the pages which are to be selected.
+I<Pages> is a comma separated list of page ranges, each of which
+may be a page number, or a page range of the form
+I<first>-I<last>. If I<first> is omitted, the first page is assumed,
+and if I<last> is omitted,  the last page is assumed.
+
+The prefix character `_' indicates that the page number is relative
+to the end of the document, counting backwards. If just this
+character with no page number is used, a blank page will be inserted.
+
 =item B<-p, --paper>
 
+Specify the paper size of the output file.
+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<-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.
+
+If the nup option (B<-n>I<nup>) is set to more than one page per sheet,
+and if the booklet option (B<-b>) is not set, the margin will be the
+same beetween two logical pages, and between a logical page and the
+sheet border.
+Otherwise, the margin beetween two logical pages will be twice bigger
+the one between a logical page and the sheet border.
+
 =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<-b, --book>
 
+Rearrange pages for printing books or booklets.
+
 =item B<-n, --nup>
 
+Puts multiple logical pages onto each physical sheet of paper. The inner
+margin might be same as the outer one (depending on the booklet option
+B<-b>), see B<-m> for details.
+
+If I<nup> is less than 10, the option B<->I<nup> may be used as an
+alternative.
+
 =item B<-q, --quiet>
 
 I<PDFTool> normally prints the page numbers of the pages output; this
@@ -59,8 +130,10 @@ Display the manual page.
 
 =head1 REQUIRE
 
-Requires psutils installed and available in the command line
-http://www.tardis.ed.ac.uk/~ajcd/psutils/
+Requires PSUtils installed and available in the command line
+http://www.tardis.ed.ac.uk/~ajcd/psutils/.
+
+PSResize2 is also required, mostly for the crop option B<-c>.
 
 =head1 AUTHOR