pdfjam (2.05-2) man1/pdfjam.1

Summary

 man1/pdfjam.1 |  251 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 250 insertions(+), 1 deletion(-)

    
download this patch

Patch contents

--- pdfjam-2.05.orig/man1/pdfjam.1
+++ pdfjam-2.05/man1/pdfjam.1
@@ -3,7 +3,7 @@
 pdfjam \- A shell script for manipulating PDF files
 .SH "SYNOPSIS" 
 .PP 
-pdfjam [OPTION [OPTION] \&.\&.\&.] [SRC [PAGESPEC] [SRC [PAGESPEC]] \&.\&.\&.]
+pdfjam [\fIOPTIONS\fR] [\fI--\fR] [\fIFILE1 \fR[\fISEL1\fR]] [\fIFILE2 \fR[\fISEL2\fR]]...
 .PP 
 .SH "DESCRIPTION" 
 .PP 
@@ -17,6 +17,253 @@
 .PP 
 The pdfjam script is distributed as (the main) part of the PDFjam package.  The homepage of PDFjam is at
 http://go.warwick.ac.uk/pdfjam \&.
+.SH USAGE
+.PP
+\'FILE1' etc. in the example above are PDF files.  For input from /dev/stdin, use the special name 
+.IP
+\&'/dev/stdin' in place of any of FILE1, FILE2, etc: this can be mixed with
+\&'real' files as needed, to allow PDF data to be input through a pipe (note
+that if /dev/stdin is connected to tty, an error results).  If 'FILE1' is
+absent, pdfjam will use '/dev/stdin' (and will use '\-' for the page
+selection \fB\-\-\fR see next item).
+.PP
+\'SEL1' is a page selection for FILE1, etc.
+To select all pages (the default) use '\-'.
+
+See the pdfpages manual for more details.
+An example:
+
+\&... file1 '{},2,4\-5,9\-' ...
+
+makes an empty page, followed by pages 2,4,5,6 of file1, followed by pages
+9 onwards (up to the end of file1).
+A page selection can be applied to more than one file, e.g.,
+
+\&... file1 file2 file3 1\-7 ...
+
+applies page selection '1\-7' to all three files; but for example
+
+\&... file1 file2 2\- file3 1\-7 ...
+
+would apply the page selection '2\-' to file1 and file2, and '1\-7'
+to file3.  A page selection applies to all the files *immediately*
+preceding it in the argument list.  A missing page selection defaults to
+\&'\-'; this includes the case where 'FILE1' is absent and so /dev/stdin gets
+used by default. 'options' are pdfpages specifications in the form '\-\-KEY VALUE' (see
+below), or
+.TP
+\fB\-\-help\fR
+(or \fB\-h\fR, or \fB\-u\fR)
+.IP
+Output this text only; no processing of PDF files.
+.HP
+\fB\-\-configpath\fR
+.IP
+Output the 'configpath' variable and exit immediately; no
+processing of PDF files.
+.TP
+\fB\-\-quiet\fR
+(or \fB\-q\fR)
+.IP
+Suppress verbose commentary on progress.
+.HP
+\fB\-\-batch\fR
+.IP
+Run pdfjam sequentially on each input file in turn, and
+produce a separate output file for each input, rather
+than the default behaviour (which is a single run of
+pdfjam on all of the input files, producing a single
+output document).  For the location of output
+files, see '\-\-outfile'.  The \fB\-\-batch\fR option cannot be
+used in the case of input fron stdin.
+.TP
+\fB\-\-outfile\fR PATH
+(or \fB\-o\fR PATH)
+.IP
+Specifies where the output file(s) will go.  If PATH is an
+existing directory, pdfjam will attempt to write its
+output PDF file(s) there, with name(s) derived from the
+input file name(s) and the \fB\-\-suffix\fR option (see below).
+Otherwise the output file will be PATH.  If '/dev/stdin'
+is the only or last input file, PATH cannot be a directory.
+Your current default PATH for output is:
+/home/ed/debian/dev/pdfjam
+.HP
+\fB\-\-suffix\fR STRING
+.IP
+Specifies a suffix for output file names, to be used when
+\fB\-\-outfile\fR is either (a) a directory, or
+(b) not specified in a \fB\-\-batch\fR call.
+.IP
+A good STRING should be descriptive: for example,
+.IP
+\fB\-\-suffix\fR 'rotated'
+.IP
+would append the text '\-rotated' to the name of the input
+file in order to make the output file name, as in
+\&'myfile\-rotated.pdf'.  The STRING must not have zero
+length.
+[Default for you at this site: suffix=pdfjam]
+.HP
+\fB\-\-checkfiles\fR
+.HP
+\fB\-\-no\-checkfiles\fR
+.IP
+If the Unix 'file' utility is available, with options
+\fB\-L\fR and \fB\-b\fR, the output of 'file \fB\-Lb\fR FILE1' should be
+\&'PDF document...' where '...' gives version information.
+If this is the case on your system you should use
+\&'\-\-checkfiles'; otherwise use '\-\-no\-checkfiles',
+in which case all input PDF files must have .pdf or .PDF
+as their name extension.
+[Default for you at this site: checkfiles=false]
+.HP
+\fB\-\-preamble\fR STRING
+.IP
+Append the supplied STRING to the preamble of the LaTeX
+source file(s), immediately before the '\ebegin{document}'
+line.  An example:
+.IP
+pdfjam \fB\-\-nup\fR 2x2 myfile.pdf \fB\-o\fR myfile\-4up.pdf \e
+.IP
+\fB\-\-preamble\fR '\eusepackage{fancyhdr} \epagestyle{fancy}'
+.IP
+The \fB\-\-preamble\fR option can be used, for example, to load LaTeX
+packages and/or to set global options.
+.HP
+\fB\-\-keepinfo\fR
+.HP
+\fB\-\-no\-keepinfo\fR
+.IP
+Preserve (or not) Title, Author, Subject and Keywords
+(from the last input PDF file, if more than one) in the
+output PDF file.  This requires the pdfinfo utility, from
+the xpdf package, and the LaTeX 'hyperref' package; if
+either of those is not available, '\-\-keepinfo' is ignored.
+[Default for you at this site: keepinfo=false]
+.HP
+\fB\-\-pdftitle\fR STRING
+.HP
+\fB\-\-pdfauthor\fR STRING
+.HP
+\fB\-\-pdfsubject\fR STRING
+.HP
+\fB\-\-pdfkeywords\fR STRING
+.IP
+Provide text for the Title, Author, Subject and Keywords in the output PDF file. Requires the  LaTeX 'hyperref'
+package.
+These options, individually, over\-ride \fB\-\-keepinfo\fR.
+.HP
+\fB\-\-landscape\fR
+.HP
+\fB\-\-no\-landscape\fR
+.IP
+Specify landscape page orientation (or not) in the
+output PDF file.
+[Default for you at this site: landscape=]
+.HP
+\fB\-\-twoside\fR
+.HP
+\fB\-\-no\-twoside\fR
+.IP
+Specify (or not) the 'twoside' document class option.
+[Default for you at this site: twoside=]
+.TP
+\fB\-\-paper\fR PAPERSPEC
+(or simply \fB\-\-PAPERSPEC\fR)
+.IP
+Specify a LaTeX paper size, for example
+\&'\-\-paper a4paper' or simply '\-\-a4paper' for ISO A4 paper.
+If the LaTeX 'geometry' package is installed, a wider range
+of paper sizes is available.  For details see documentation
+for LaTeX and/or the 'geometry' package.
+[Default for you at this site: paper=a4paper]
+.HP
+\fB\-\-papersize\fR '{WIDTH,HEIGHT}'
+.IP
+Specify a custom paper size, e.g.,
+.IP
+\fB\-\-papersize\fR '{10in,18cm}'
+.IP
+(Note the braces, and the comma!)
+If the 'geometry' package is not found, this has no effect.
+.HP
+\fB\-\-pagecolor\fR RGBSPEC
+.IP
+Specify a background colour for the output pages.
+The
+RGBSPEC must be a comma\-separated trio of integers
+between 0 and 255.  An example:
+.IP
+\fB\-\-pagecolor\fR 150,200,150
+.IP
+[Default is no background colour]
+.HP
+\fB\-\-tidy\fR
+.HP
+\fB\-\-no\-tidy\fR
+.IP
+Specify whether the temporary directory created by
+pdfjam should be deleted.  Use '\-\-no\-tidy' to help debug
+most errors.
+[Default for you at this site: tidy=true]
+.HP
+\fB\-\-vanilla\fR
+.IP
+Suppress the reading of any site\-wide or user\-specific
+configuration files.
+.HP
+\fB\-\-KEY\fR VALUE
+.IP
+Specify options to '\eincludepdfmerge', in the LaTeX
+\&'pdfpages' package.  Here KEY is the name of any of the
+many options for '\eincludepdfmerge', and VALUE is a
+corresponding value.  Examples are:
+.TP
+\fB\-\-nup\fR 2x1
+(for 2\-up side\-by\-side imposition)
+.TP
+\fB\-\-scale\fR 0.7
+(to scale all input pages to 70% size)
+.IP
+\fB\-\-offset\fR '1cm 0.5cm'
+.IP
+(to offset all pages \fB\-\-\fR note the quotes!)
+.TP
+\fB\-\-frame\fR true
+(to put a frame round each input page)
+.IP
+\fB\-\-trim\fR '1cm 2cm 1cm 2cm' \fB\-\-clip\fR true
+.IP
+(to trim those amounts from left, bottom,
+.IP
+right and top, respectively, of input
+pages)
+.TP
+etc., etc.
+For more information see the manual for
+.IP
+the 'pdfpages' package, at
+http://www.ctan.org/tex\-archive/macros/latex/contrib/pdfpages
+.PP
+Argument '\-\-' can be used to signal that there are no more options to come.
+.PP
+Defaults for the options '\-\-suffix', '\-\-keepinfo', '\-\-paper', '\-\-outfile',
+\&'\-\-landscape', '\-\-twoside', '\-\-tidy' and '\-\-checkfiles' can be set in
+site\-wide or user\-specific configuration files.  The path that is searched
+for site\-wide configuration files (named pdfjam.conf) at this installation is
+.IP
+/etc:/usr/share/etc:/usr/local/share:/usr/local/etc
+.PP
+This configuration path can be changed by editing the pdfjam script if
+necessary.  Any user\-specific configuration should be put in a file named
+\&.pdfjam.conf in your home directory.  (All of these files are ignored
+if the '\-\-vanilla' argument is used.)
+.PP
+For more information, including an example configuration file, see
+http://go.warwick.ac.uk/pdfjam.
+
+
 .PP
 .SH "SETUP" 
 .PP
@@ -56,3 +303,5 @@
 .PP 
 The PDFjam package is written and maintained by David Firth\&.
 
+The USAGE chapter was inserted by Eduard Bloch <blade@debian.org> using pdfjam
+output processed with help2man and with manual corrections applied.