--- /dev/null
+PAPERJAM(1)
+===========
+
+NAME
+----
+paperjam - a PDF document processor
+
+SYNOPSIS
+--------
+*paperjam* 'options' 'commands' 'input' 'output'
+
+DESCRIPTION
+-----------
+Paperjam is a tool for transform PDF files. It can re-order pages, scale,
+rotate, or translate their contents, put multiple pages on one sheet, and
+a lot of other things.
+
+Paperjam takes an input file, splits it to a list of pages, applies a sequence
+of commands on this list, and finally writes the results to an output file.
+
+For each page, Paperjam tracks two sets of dimensions: the width and height
+of the 'physical page', and the 'image box', which is a rectangle on the
+physical page containing all useful contents. Initially, the physical
+page is equal to the *CropBox* of the PDF page and the image box to its
+*ArtBox* (which is optional and it defaults to the *CropBox*). Further
+commands can modify these dimensions.
+
+OPTIONS
+-------
+*-b, --bbox*::
+ Recalculate image box of each page to enclose the contents really
+ drawn on the page. This is done by asking GhostScript to render each
+ page.
+
+*-d, --debug*::
+ Show debugging messages. Increases verbosity when given multiple times.
+
+*--help*::
+ Show help on options and commands.
+
+GENERAL SYNTAX
+--------------
+Paperjam takes a list of commands separated by spaces, like this:
+
+ paperjam 'common scaleto("a4") nup(2, hspace=5mm)' in.pdf out.pdf
+
+Each command starts with its identifier (a sequence of alphanumeric characters,
+underscores, and dashes, which starts with a letter). Then come arguments enclosed
+in parentheses. All arguments can be written as 'name'='value' (where the name is
+an identifier). For some of them, the name can be omitted and the meaning
+follows from the position in the argument list (hence these are called
+'positional' arguments).
+
+There are several types of arguments:
+
+numbers::
+ Ordinary decimal numbers, possibly fractional.
+
+dimensions::
+ Numbers with a unit of length. We support these units:
+ mm, cm, dm, m, in (inch), pt (printers' point, that is 1/72 in).
+
+strings::
+ Strings written in double quotes. If you want to include the double
+ quote character or a backslash in the string, precede it with a backslash.
+ For convenience, the double quotes can be omitted if the string value
+ satisfies the syntax of an identifier. In case of positional arguments,
+ the identifier must not match the name of any argument. Please avoid
+ using this shortcut in scripts, because they could be easily broken
+ by parameters introduced in newer versions of Paperjam.
+
+switches::
+ Boolean value: either 0 (false) or 1 (true). If only the name is given (with no value
+ and no equal sign), the switch is set to true.
+
+Pipelines
+~~~~~~~~~
+Several commands apply other commands on a subset of pages. This is usually
+described by a 'pipeline' like:
+
+ { 1: rotate(90), 2: flip(h) flip(v) }
+ { 1..10: common }
+ { 1 2, 11..20, 30..21 }
+
+The pipeline is enclosed in curly braces. It consists of one or more 'stages'
+separated by commas. Each stage has one or more 'page selectors' (page numbers
+or ranges) and an optional list of commands to apply on these pages (separated
+from the selectors by a semicolon).
+
+When a range is written backwards (the first page number is greater than the
+second one), the pages are processed in reverse order.
+
+Paper formats
+~~~~~~~~~~~~~
+When a paper format is expected, it is given either by its width and height
+(the corresponding arguments are usually called *w* and *h*), or by the standard
+name of the format (called *paper*). Paperjam currently uses the libpaper library
+for parsing the names. You can call *paperconf -a* to get the list of known names.
+
+Margins
+~~~~~~~
+Many commands take a specification of margins on all sides of an image.
+You can set either a common value for all margins, or two values for vertical
+and horizontal margins, or separate values for all margins. You can also
+combine these ways: for example you can set a horizontal, top, and bottom
+margin.
+
+More formally, there are 7 arguments controlling margins: common,
+horizontal, vertical, left, right, top, and bottom. Horizontal and vertical
+default to common, left and right default to horizontal, top and bottom default
+to vertical.
+
+Positioning
+~~~~~~~~~~~
+Multiple commands require positioning an image on a larger page. The image
+is placed according to a two-letter position specification (usually an argument
+called *pos*). The first letter specifies vertical placement: *t* for top,
+*c* for center, *b* for bottom. The second one horizontal placement: *l* for left,
+*c* for center, *r* for right. If no position is given, *cc* is assumed.
+
+COMMANDS
+--------
+Paperjam knows the following commands and arguments. Positional arguments
+have their names enclosed in square brackets.
+
+add-blank
+~~~~~~~~~
+Add blank page(s) after each page.
+
+*[n=]*'int'::
+ The number of blank pages to add. Defaults to 1.
+
+*[paper=]*'string', *w=*'dimen', *h=*'dimen'::
+ Paper format of the blank pages. (See Paper formats above.)
+
+apply
+~~~~~
+Applies commands on a sub-set of pages:
+
+ apply { 1: rotate(90), 2: flip(h) }
+
+Takes a pipeline. For each input page, it finds the pipeline stage
+matching the page index (its position in the input document, starting with 1)
+and applies the commands in the stage on the page. If no stage matches,
+the page is left unchanged. If multiple stages, the first one wins.
+
+book
+~~~~
+Prepares booklets (also known as signatures) for book binding.
+With no argument, it re-orders pages in the document, so that a subsequent
+*nup(2)* produces the correct booklet layout: two pages on one sheet
+and when the document is printed double-sided and folded in half,
+you have a booklet. If the number of input pages is not divisible by 4,
+blank pages are added.
+
+*[n=]*'int'::
+ Split the document in parts per 'n' pages and produce a separate
+ booklet from each part. The 'n' must be divisible by 4.
+
+clip
+~~~~
+Suppress page contents drawn outside the image box.
+
+*bleed=*'dimen'::
+ Let the image bleed this far outside the image box.
+ (Technically, it sets the crop box to the image box enlarged
+ at all sides by this amount.)
+
+common
+~~~~~~
+Use a common page size and image box for all pages. More specifically,
+the new page width and height are set to the maximum of all page widths
+and heights and the new image box is the minimal rectangle containing all
+image boxes.
+
+cropmarks
+~~~~~~~~~
+Draw cropping marks around the image box.
+
+*mark=*'string'::
+ Set cropmark style:
+ 'box' for a rectangle around the image box,
+ 'cross' for crosses in the corners of the box,
+ 'in' for two arms of a cross in each corner, pointing inwards,
+ 'out' for two arms pointing outwards,
+ 'bg' for drawing a filled rectangle under the box.
+
+*pen=*'dimen'::
+ Pen width for drawing cropmarks (for all styles except bg).
+ Default: 0.2 pt.
+
+*len=*'dimen'::
+ Cropmark arm length (for cross, in, out).
+ Default: 5 mm.
+
+*offset=*'dimen'::
+ Draw cropmarks around image box enlarged by this distance
+ on all sides.
+
+*color=*'string'::
+ Cropmark color, given as RRGGBB in hexadecimal.
+ Default: +000000+ (black).
+
+debug
+~~~~~
+Draw debugging information on each page: a red rectangle around the page,
+a green rectangle around the image box.
+
+expand
+~~~~~~
+Expand paper around the image. Recalculates paper size and the position
+of the image on the paper, so that the distance between each edge of the
+image box and the corresponding edge of the paper increases by the given
+amount.
+
+*[by=]*'dimen'::
+ Adjust all margins by the same amount. Defaults to 0.
+
+*h=*'dimen', *v=*'dimen', *l=*'dimen', *r=*'dimen', *t=*'dimen', *b=*'dimen'::
+ Adjust horizontal, vertical, left, right, top, and bottom margins.
+ See Margins above to see how these argument interact with each other.
+
+fit
+~~~
+If a paper size is given, scale and translate the image to fit on the
+paper (with given margins). If no paper is given, set the paper size
+and the position of the image according to the margins.
+
+If the paper and the image have different aspect ratios, the *pos*
+argument controls the position of the image on the paper.
+
+*[paper=]*'string', *w=*'dimen', *h=*'dimen'
+ Paper format, or paper width and height (see Paper formats above
+ for details).
+
+*pos=*'string':
+ Specify position of the image on the paper (see Positioning above).
+ Defaults to *cc*.
+
+*margin=*'dimen', *hmargin=*'dimen', *vmargin=*'dimen', *lmargin=*'dimen', *rmargin=*'dimen', *tmargin=*'dimen', *bmargin=*'dimen'::
+ Set margins (see Margins above). Defaults to 0.
+
+flip
+~~~~
+Flip pages horizontally or vertically.
+
+*h=*'switch':
+ Flip horizontally.
+
+*v=*'switch':
+ Flip vertically.
+
+margins
+~~~~~~~
+Define a new image box by dimensions of margins around it. More technically,
+the new image box is calculated from the page box by shrinking it by the appropriate
+margin on each side.
+
+*[size=]*'dimen'::
+ Set all margins at once.
+
+*h=*'dimen', *v=*'dimen', *l=*'dimen', *r=*'dimen', *t=*'dimen', *b=*'dimen'::
+ Set margins (see Margins above). Defaults to *size*.
+
+merge
+~~~~~
+Merge all pages to one by placing them one over another. (The first page is drawn
+first.)
+
+modulo
+~~~~~~
+Act on n-tuples of pages.
+The document is split to n-tuples (the partial n-tuple at the end is padded with
+blank pages, whose size matches the first page of the n-tuple).
+A pipeline is then run separately for each n-tuple, selecting pages from the tuple
+and applying commands on them.
+
+More specifically, the stages of the pipeline are processed from the left to the
+right. Each stage forms a temporary document by taking the selected pages from the n-tuple
+(numbered from 1 to n). Then it applies the commands on this document and appends the
+result to the end of the output of the whole modulo.
+
+Negative page numbers can be also used, which adresses pages in the "mirror-image
+tuple". Page number -'i' in tuple 'j' corresponds to page 'i' in the 'j'-th tuple
+from the end of the document.
+
+Arguments:
+
+*[n=]*'int' (mandatory)::
+ Number of pages in a single tuple.
+
+*half=*'switch':
+ Process only the first half of n-tuples. This is often used in conjunction
+ with negative page numbers.
+
+For example, the following command rotates every other page:
+
+ modulo(2) { 1, 2: rotate(180) }
+
+While this command skips every other page:
+
+ modulo(2) { 1 }
+
+move
+~~~~
+Shift (translate) contents on the page.
+
+*[x=]*'dimen', *[y=]*'dimen'::
+ Move everything right/up by the given distance.
+
+null
+~~~~
+Do nothing.
+
+nup
+~~~
+Combine multiple pages to one (n-up printing). Allows detailed control over the
+parameters. If only a subset of the parameters is given (in the most trivial cases,
+only the number of pages to put on a single sheet), the remaining parameters are
+adjusted to maximize coverage of the sheet.
+
+For example, when the input document is typeset on A4 paper,
++nup(2)+ rotates pages by 90 degrees, scales them to 70.7% size,
+and puts them side-by-side. On the same input, +nup(4)+ produces
+the same as +nup(2,2)+, that is a two-by-two grid of pages scaled
+to 50%.
+
+Technically, nup first splits the input document to n-tuples of pages
+(padding the last incomplete n-tuple with blank pages of the size of the
+first page of that n-tuple). For each n-tuple, it creates an output page,
+splits it to a grid-like arrangement of tiles, and scales and/or rotates
+each page to fit in its tile.
+
+*[n=]*'number'::
+ If *m* is also given, *n* is the number of rows of the grid of tiles.
+ Without *m*, the total number of tiles on a page.
+
+*[m=]*'number'::
+ The number of columns of the grid of tiles.
+
+*by=*'string':
+ Tile filling order: *rows* (default) fills rows from the top to the bottom,
+ inside each row from the left to the right; *cols* fills columns from
+ the left to the right, inside each column from the top to the bottom;
+ *tile* copies the same page to all tiles.
+
+*crop=*'switch':
+ Crop input pages to their image box. (By default, *nup* places the input
+ papers in tiles. With this option, it places the image boxes in tiles,
+ effectively cutting away original margins.)
+
+*mixed=*'switch':
+ By default, *nup* adjusts all input pages to a common paper size and
+ image box size (like the *common* command does). This switch disables
+ that.
+
+*rotate=*'switch':
+ Specify if the pages should be rotated. Default: choose automatically.
+
+*scale=*'number':
+ Scaling factor. Default: choose automatically.
+
+*[paper=]*'string', *w=*'dimen', *h=*'dimen'::
+ Paper size (see Paper formats above).
+
+*margin=*'dimen', *hmargin=*'dimen', *vmargin=*'dimen', *lmargin=*'dimen', *rmargin=*'dimen', *tmargin=*'dimen', *bmargin=*'dimen'::
+ Margins around the tile grid (see Margins above). Defaults to 0.
+
+*pos=*'string'::
+ Position of the tile grid on the page (see Positioning above).
+ This applies when the *scale* is fixed, or if the aspect ratio of the
+ paper (after subtracting margins) does not match the aspect ratio of
+ the tile grid. Defaults to *cc*.
+
+*cmark=*'string', *cpen=*'dimen', *clen=*'dimen', *coffset=*'dimen', *ccolor=*'string':
+ Draw cropmarks around each tile. See *crop* for the meaning of arguments.
+
+*tpos=*'string':
+ Position of original pages inside tiles (see Positioning above).
+ This applies when different pages have different sizes.
+ Defaults to *tl*.
+
+*space=*'dimen', *hspace=*'dimen', *vspace=*'dimen':
+ Insert extra spaces between adjacent tiles in the grid (in both directions,
+ horizontally, vertically). This is useful together with *crop*.
+
+paper
+~~~~~
+Place image on a given paper. Defines new paper size, translates the image box
+according to the given position.
+
+*[paper=]*'string', *w=*'dimen', *h=*'dimen'::
+ Paper size (see Paper formats above).
+
+*pos=*'string':
+ Position of the image on the paper (see Positioning above). Default: *cc*.
+
+rotate
+~~~~~~
+Rotate the page clockwise by multiples of 90 degrees.
+
+*[angle=]*'number'::
+ Rotation angle. Must be a multiple of 90 degrees.
+
+scale
+~~~~~
+Scale the page by a given factor.
+
+*[x=]*'number', *[y=]*'number':
+ Set horizontal and vertical scaling factor. If only one is given,
+ it is used in both directions.
+
+scaleto
+~~~~~~~
+Scale the entire page to a given size.
+
+*[paper=]*'string', *w=*'dimen', *h=*'dimen'::
+ Paper size (see Paper formats above).
+
+*pos=*'string':
+ Position of the old paper on the new one (see Positioning above). Default: *cc*.
+ This applies if the aspect ratios of both papers do not match.
+
+select
+~~~~~~
+Selects a subset of pages and optionally applies commands on them.
+
+The select command gets a pipeline. It processes the pipeline stages from the left to the
+right. For each stage, it assembles a temporary document containing the selected pages,
+applies the stage's commands on it, and appends the resulting document to the output of
+the whole select command.
+
+For example, this selects pages 1, 10 to 19, and 29 to 20 in reverse order:
+
+ select { 1 10..19 29..20 }
+
+This is the same:
+
+ select { 1, 10..19, 29..20 }
+
+This select two pages and rotates them differently:
+
+ select { 1: rotate(90), 2: rotate(-90) }
+
+The following examples show that the formation of temporary documents can make
+a difference sometimes:
+
+ select { 1..10 common, 21..30 common }
+ select { 1..10 21..30 common }
+ select { 1..10 21..30 } common
+ select { 1..10, 21..30 } common
+
+The first command forms two temporary documents and applies common to each of them separately
+(therefore pages 1 to 10 will have one common size and pages 21 to 30 another). The remaining
+commands give the same result. The second command forms a single temporary document with 20 pages
+and applies common to all of it at once. The third command forms a single temporary document,
+which immediately becomes the result of select, to which the final common is applied. And the fourth
+command forms two temporary documents, concatenates them to the result of select, and finally applies
+common.
+
+LICENSE
+-------
+Paperjam was written by Martin Mares.
+It can be distributed and used under the terms of the GNU
+General Public License version 2 or any later version.
projects / paperjam.git / commitdiff