paperjam.1.txt

   1 PAPERJAM(1)
   2 ===========
   3
   4 NAME
   5 ----
   6 paperjam - a PDF document processor
   7
   8 SYNOPSIS
   9 --------
  10 *paperjam* 'options' 'commands' 'input' 'output'
  11
  12 DESCRIPTION
  13 -----------
  14 PaperJam is a tool for transform PDF files. It can re-order pages, scale
  15 and rotate them, put multiple pages on a single sheet, draw cropmarks,
  16 and many other tricks.
  17
  18 PaperJam takes an input file, splits it to a list of pages, applies a sequence
  19 of commands on this list, and finally writes the results to an output file.
  20
  21 For each page, PaperJam tracks two sets of dimensions: the width and height
  22 of the 'physical page' (paper), and the 'image box', which is a rectangle on the
  23 physical page containing all useful contents. Initially, the physical
  24 page is equal to the *CropBox* of the PDF page and the image box to its
  25 *ArtBox* (which is optional and it defaults to the *CropBox*). Further
  26 commands can modify these dimensions.
  27
  28 OPTIONS
  29 -------
  30 *-b, --bbox*::
  31         Recalculate image box of each page to enclose the contents really
  32         drawn on the page. This is done by asking GhostScript to render each
  33         page.
  34
  35 *-d, --debug*::
  36         Show debugging messages. Increases verbosity when given multiple times.
  37
  38 *--help*::
  39         Show help on options and commands.
  40
  41 GENERAL SYNTAX
  42 --------------
  43 PaperJam takes a list of commands separated by spaces, like this:
  44
  45         paperjam 'common scaleto("a4") nup(2, hspace=5mm)' in.pdf out.pdf
  46
  47 Each command starts with its identifier (a sequence of alphanumeric characters,
  48 underscores, and dashes, which begins with a letter). Then come arguments enclosed
  49 in parentheses. All arguments can be written as 'name'='value' (where the name is
  50 an identifier). For some of them, the name can be omitted and the meaning
  51 follows from the position in the argument list (hence these are called
  52 'positional' arguments).
  53
  54 There are several types of arguments:
  55
  56 numbers::
  57         Ordinary decimal numbers, possibly fractional.
  58
  59 dimensions::
  60         Numbers with a unit of length. We support these units:
  61         mm, cm, dm, m, in (inch), pt (printers' point, that is 1/72 in).
  62
  63 strings::
  64         Strings written in double quotes. If you want to include the double
  65         quote character or a backslash in the string, precede it with a backslash.
  66         For convenience, the double quotes can be omitted if the string value
  67         satisfies the syntax of an identifier. In case of positional arguments,
  68         the identifier must not match the name of any argument. Please avoid
  69         using this shortcut in scripts, because they could be easily broken
  70         by parameters introduced in newer versions of PaperJam.
  71
  72 switches::
  73         Boolean value: either 0 (false) or 1 (true). If only the name is given (with no value
  74         and no equal sign), the switch is set to true.
  75
  76 Pipelines
  77 ~~~~~~~~~
  78 Several commands apply other commands on a subset of pages. This is usually
  79 described by a 'pipeline' like:
  80
  81         { 1: rotate(90), 2: flip(h) flip(v) }
  82         { 1..10: common }
  83         { 1 2, 11..20, 30..21 }
  84
  85 The pipeline is enclosed in curly braces. It consists of one or more 'stages'
  86 separated by commas. Each stage has one or more 'page selectors' (page numbers
  87 or ranges) and an optional list of commands to apply on these pages (separated
  88 from the selectors by a semicolon).
  89
  90 When a range is written backwards (the first page number is greater than the
  91 second one), the pages are processed in reverse order.
  92
  93 Paper formats
  94 ~~~~~~~~~~~~~
  95 When a paper format is expected, it is given either by its width and height
  96 (the corresponding arguments are usually called *w* and *h*), or by the standard
  97 name of the format (called *paper*). PaperJam currently uses the libpaper library
  98 for parsing the names. You can call +paperconf -a+ to get the list of known names.
  99
 100 Margins
 101 ~~~~~~~
 102 Many commands take a specification of margins on all sides of an image.
 103 You can set either a common value for all margins, or two values for vertical
 104 and horizontal margins, or separate values for all margins. You can also
 105 combine these ways: for example you can set a horizontal, top, and bottom
 106 margin.
 107
 108 More formally, there are 7 arguments controlling margins: common,
 109 horizontal, vertical, left, right, top, and bottom. Horizontal and vertical
 110 default to common, left and right default to horizontal, top and bottom default
 111 to vertical.
 112
 113 Positioning
 114 ~~~~~~~~~~~
 115 Multiple commands involve positioning an image on a larger page. The image
 116 is placed according to a two-letter position specification (usually an argument
 117 called *pos*). The first letter specifies vertical placement: *t* for top,
 118 *c* for center, *b* for bottom. The second one horizontal placement: *l* for left,
 119 *c* for center, *r* for right.
 120
 121 COMMANDS
 122 --------
 123 PaperJam knows the following commands and arguments. Positional arguments
 124 have their names enclosed in square brackets.
 125
 126 add-blank
 127 ~~~~~~~~~
 128 Add blank page(s) after each page.
 129
 130 *[n=]*'int'::
 131         The number of blank pages to add. Defaults to 1.
 132
 133 *[paper=]*'string', *w=*'dimen', *h=*'dimen'::
 134         Paper size of the blank pages (see Paper formats above).
 135
 136 apply
 137 ~~~~~
 138 Applies commands on a sub-set of pages:
 139
 140         apply { 1: rotate(90), 2: flip(h) }
 141
 142 Takes a pipeline. For each input page, it finds the pipeline stage
 143 matching the page index (its position in the input document, starting with 1)
 144 and applies the commands in the stage on the page. If no stage matches,
 145 the page is left unchanged. If multiple stages match, the first one wins.
 146
 147 book
 148 ~~~~
 149 Prepares booklets (also known as signatures) for book binding.
 150 With no argument, it re-orders pages in the document, so that a subsequent
 151 *nup(2)* produces the correct booklet layout: two pages on one sheet
 152 and when the document is printed double-sided and folded in half,
 153 you have a booklet. If the number of input pages is not divisible by 4,
 154 blank pages are added.
 155
 156 *[n=]*'int'::
 157         Split the document in parts per 'n' pages and produce a separate
 158         booklet from each part. The 'n' must be divisible by 4.
 159
 160 clip
 161 ~~~~
 162 Suppress page contents drawn outside the image box.
 163
 164 *bleed=*'dimen'::
 165         Let the image bleed this far outside the image box.
 166         (Technically, it sets the crop box to the image box enlarged
 167         at all sides by this amount.)
 168
 169 common
 170 ~~~~~~
 171 Use a common page size and image box for all pages. More specifically,
 172 the new page width and height are set to the maximum of all page widths
 173 and heights and the new image box to the minimal rectangle containing all
 174 image boxes.
 175
 176 cropmarks
 177 ~~~~~~~~~
 178 Draw cropping marks around the image box.
 179
 180 *mark=*'string'::
 181         Set cropmark style:
 182         *box* for a rectangle around the image box,
 183         *cross* for crosses in the corners of the box,
 184         *in* for two arms of a cross in each corner, pointing inwards,
 185         *out* for two arms pointing outwards,
 186         *bg* for drawing a filled rectangle under the box.
 187
 188 *pen=*'dimen'::
 189         Pen width for drawing cropmarks (for all styles except bg).
 190         Default: 0.2 pt.
 191
 192 *len=*'dimen'::
 193         Cropmark arm length (for cross, in, out).
 194         Default: 5 mm.
 195
 196 *offset=*'dimen'::
 197         Draw cropmarks around image box enlarged by this distance
 198         on all sides.
 199
 200 *color=*'string'::
 201         Cropmark color, given as RRGGBB in hexadecimal.
 202         Default: +000000+ (black).
 203
 204 debug
 205 ~~~~~
 206 Draw debugging information on each page: a red rectangle around the page,
 207 a green rectangle around the image box.
 208
 209 expand
 210 ~~~~~~
 211 Expand paper around the image. Recalculates paper size and the position
 212 of the image on the paper, so that the distance between each edge of the
 213 image box and the corresponding edge of the paper increases by the given
 214 amount.
 215
 216 *[by=]*'dimen'::
 217         Adjust all margins by the same amount. Defaults to 0.
 218
 219 *h=*'dimen', *v=*'dimen', *l=*'dimen', *r=*'dimen', *t=*'dimen', *b=*'dimen'::
 220         Adjust horizontal, vertical, left, right, top, and bottom margins.
 221         See Margins above to see how these argument interact with each other.
 222
 223 fit
 224 ~~~
 225 If a paper size is given, scale and translate the image to fit on the
 226 paper (with given margins). If no paper is given, set the paper size
 227 and the position of the image according to the margins.
 228
 229 If the paper and the image have different aspect ratios, the *pos*
 230 argument controls the position of the image on the paper.
 231
 232 *[paper=]*'string', *w=*'dimen', *h=*'dimen'::
 233         Paper format, or paper width and height (see Paper formats above
 234         for details).
 235
 236 *pos=*'string'::
 237         Specify position of the image on the paper (see Positioning above).
 238         Defaults to *cc*.
 239
 240 *margin=*'dimen', *hmargin=*'dimen', *vmargin=*'dimen', *lmargin=*'dimen', *rmargin=*'dimen', *tmargin=*'dimen', *bmargin=*'dimen'::
 241         Set margins (see Margins above). Defaults to 0.
 242
 243 flip
 244 ~~~~
 245 Flip pages horizontally or vertically.
 246
 247 *h=*'switch'::
 248         Flip horizontally.
 249
 250 *v=*'switch'::
 251         Flip vertically.
 252
 253 margins
 254 ~~~~~~~
 255 Define a new image box by dimensions of margins around it. More technically,
 256 the new image box is calculated from the page box by shrinking it by the appropriate
 257 margin on each side.
 258
 259 *[size=]*'dimen'::
 260         Set all margins at once.
 261
 262 *h=*'dimen', *v=*'dimen', *l=*'dimen', *r=*'dimen', *t=*'dimen', *b=*'dimen'::
 263         Set margins (see Margins above). Defaults to *size*.
 264
 265 merge
 266 ~~~~~
 267 Merge all pages to one by placing them one over another. (The first page is drawn
 268 first.)
 269
 270 modulo
 271 ~~~~~~
 272 Act on n-tuples of pages.
 273 The document is split to n-tuples (the partial n-tuple at the end is padded with
 274 blank pages, whose size matches the first page of the n-tuple).
 275 A pipeline is then run separately for each n-tuple, selecting pages from the tuple
 276 and applying commands on them.
 277
 278 More specifically, the stages of the pipeline are processed from the left to the
 279 right. Each stage forms a temporary document by taking the selected pages from the n-tuple
 280 (numbered from 1 to n). Then it applies the commands on this document and appends the
 281 result to the end of the output of the whole modulo.
 282
 283 Negative page numbers can be also used, which adresses pages in the "mirror-image
 284 tuple". Page number -'i' in tuple 'j' corresponds to page 'i' in the 'j'-th tuple
 285 from the end of the document.
 286
 287 Arguments:
 288
 289 *[n=]*'int' (mandatory)::
 290         Number of pages in a single tuple.
 291
 292 *half=*'switch'::
 293         Process only the first half of n-tuples. This is often used in conjunction
 294         with negative page numbers.
 295
 296 For example, the following command rotates every other page:
 297
 298         modulo(2) { 1, 2: rotate(180) }
 299
 300 While this command skips every other page:
 301
 302         modulo(2) { 1 }
 303
 304 move
 305 ~~~~
 306 Shift contents on the page. Paper size does not change, the image box moves.
 307
 308 *[x=]*'dimen', *[y=]*'dimen'::
 309         Move everything right/up by the given distance.
 310
 311 null
 312 ~~~~
 313 Do nothing.
 314
 315 nup
 316 ~~~
 317 Combine multiple pages to one (n-up printing). Allows detailed control over the
 318 parameters, but if only a subset of the parameters is given (in the most trivial case,
 319 just the number of pages to put on a single sheet), the remaining parameters are
 320 adjusted to maximize coverage of the sheet.
 321
 322 For example, when the input document is typeset on A4 paper,
 323 +nup(2)+ rotates pages by 90 degrees, scales them to 70.7% size,
 324 and puts them side-by-side. On the same input, +nup(4)+ produces
 325 the same as +nup(2,2)+, that is a two-by-two grid of pages scaled
 326 to 50%.
 327
 328 Technically, nup first splits the input document to n-tuples of pages
 329 (padding the last incomplete n-tuple with blank pages of the size of the
 330 first page of that n-tuple). For each n-tuple, it creates an output page,
 331 splits it to a grid-like arrangement of tiles, and scales and/or rotates
 332 each page to fit in its tile.
 333
 334 *[n=]*'number'::
 335         If *m* is also given, *n* is the number of rows of the grid of tiles.
 336         Without *m*, the total number of tiles on a page.
 337
 338 *[m=]*'number'::
 339         The number of columns of the grid of tiles.
 340
 341 *by=*'string'::
 342         Tile filling order: *rows* (default) fills rows from the top to the bottom,
 343         inside each row from the left to the right; *cols* fills columns from
 344         the left to the right, inside each column from the top to the bottom;
 345         *tile* copies the same page to all tiles.
 346
 347 *crop=*'switch'::
 348         Crop input pages to their image box. (By default, *nup* places the input
 349         papers in tiles. With this option, it places the image boxes in tiles,
 350         effectively cutting away original margins.)
 351
 352 *mixed=*'switch'::
 353         By default, *nup* adjusts all input pages to a common paper size and
 354         image box size (like the *common* command does). This switch disables
 355         that.
 356
 357 *rotate=*'switch'::
 358         Specify if the pages should be rotated. Default: choose automatically.
 359
 360 *scale=*'number'::
 361         Scaling factor. Default: choose automatically.
 362
 363 *[paper=]*'string', *w=*'dimen', *h=*'dimen'::
 364         Paper size (see Paper formats above).
 365
 366 *margin=*'dimen', *hmargin=*'dimen', *vmargin=*'dimen', *lmargin=*'dimen', *rmargin=*'dimen', *tmargin=*'dimen', *bmargin=*'dimen'::
 367         Margins around the tile grid (see Margins above). Defaults to 0.
 368
 369 *pos=*'string'::
 370         Position of the tile grid on the page (see Positioning above).
 371         This applies when the *scale* is fixed, or if the aspect ratio of the
 372         paper (after subtracting margins) does not match the aspect ratio of
 373         the tile grid. Defaults to *cc*.
 374
 375 *cmark=*'string', *cpen=*'dimen', *clen=*'dimen', *coffset=*'dimen', *ccolor=*'string'::
 376         Draw cropmarks around each tile. See *crop* for the meaning of arguments.
 377
 378 *tpos=*'string'::
 379         Position of original pages inside tiles (see Positioning above).
 380         This applies when different pages have different sizes.
 381         Defaults to *tl*.
 382
 383 *space=*'dimen', *hspace=*'dimen', *vspace=*'dimen'::
 384         Insert extra spaces between adjacent tiles in the grid (in both directions,
 385         horizontally, vertically). This is useful together with *crop*.
 386
 387 paper
 388 ~~~~~
 389 Place image on a given paper. Sets a new paper size and translates the image box
 390 according to the given position.
 391
 392 *[paper=]*'string', *w=*'dimen', *h=*'dimen'::
 393         Paper size (see Paper formats above).
 394
 395 *pos=*'string'::
 396         Position of the image on the paper (see Positioning above). Default: *cc*.
 397
 398 rotate
 399 ~~~~~~
 400 Rotate the page clockwise by multiples of 90 degrees.
 401
 402 *[angle=]*'number'::
 403         Rotation angle. Must be a multiple of 90 degrees.
 404
 405 scale
 406 ~~~~~
 407 Scale the page by a given factor.
 408
 409 *[x=]*'number', *[y=]*'number'::
 410         Set horizontal and vertical scaling factor. If only one is given,
 411         it is used in both directions.
 412
 413 scaleto
 414 ~~~~~~~
 415 Scale the entire page to a given size.
 416
 417 *[paper=]*'string', *w=*'dimen', *h=*'dimen'::
 418         Paper size (see Paper formats above).
 419
 420 *pos=*'string'::
 421         Position of the old paper on the new one (see Positioning above). Default: *cc*.
 422         This applies if the aspect ratios of both papers do not match.
 423
 424 select
 425 ~~~~~~
 426 Selects a subset of pages and optionally applies commands on them.
 427
 428 The select command gets a pipeline. It processes the pipeline stages from the left to the
 429 right. For each stage, it assembles a temporary document containing the selected pages,
 430 applies the stage's commands on it, and appends the resulting document to the output of
 431 the whole select command.
 432
 433 For example, the following command selects pages 1, 10 to 19, and 20 to 29 in reverse order.
 434 The rest of the document is discarded.
 435
 436         select { 1 10..19 29..20 }
 437
 438 This has the same effect:
 439
 440         select { 1, 10..19, 29..20 }
 441
 442 This selects two pages and rotates them differently:
 443
 444         select { 1: rotate(90), 2: rotate(-90) }
 445
 446 The following examples show that the formation of temporary documents can make
 447 a difference sometimes:
 448
 449         select { 1..10 common, 21..30 common }
 450         select { 1..10 21..30 common }
 451         select { 1..10 21..30 } common
 452         select { 1..10, 21..30 } common
 453
 454 The first command forms two temporary documents and applies common to each of them separately
 455 (therefore pages 1 to 10 will have one common size and pages 21 to 30 another). The remaining
 456 three commands give the same result. The second command forms a single temporary document with 20 pages
 457 and applies common to all of it at once. The third command forms a single temporary document,
 458 which immediately becomes the result of select, to which the final common is applied. And the fourth
 459 command forms two temporary documents, concatenates them to the result of select, and finally applies
 460 common.
 461
 462 slice
 463 ~~~~~
 464 Slices the image to several smaller pages. Each page receives a part of the original
 465 image, gluing the parts together produces the original image.
 466
 467 *[paper=]*'string', *w=*'dimen', *h=*'dimen'::
 468         Paper size of the produced pages (see Paper formats above).
 469
 470 *pos=*'string'::
 471         Position of the original image on a "canvas" obtained by gluing
 472         together non-margin parts of the produced pages (see Positioning above).
 473         Default: *cc*.
 474
 475 *margin=*'dimen', *hmargin=*'dimen', *vmargin=*'dimen', *lmargin=*'dimen', *rmargin=*'dimen', *tmargin=*'dimen', *bmargin=*'dimen'::
 476         Set margins of the produced pages (see Margins above). Defaults to 0.
 477
 478 *bleed=*'dimen'::
 479         Let the parts of the image bleed this far outside their boxes.
 480
 481 LICENSE
 482 -------
 483 PaperJam was written by Martin Mares.
 484 It can be distributed and used under the terms of the GNU
 485 General Public License version 2 or any later version.
 486
 487 HISTORY
 488 -------
 489 I conceived the idea of a document processor like PaperJam when struggling with pre-press
 490 formatting in the early 2000's. At that time, the basic ideas behind the language were born,
 491 but everything was deeply rooted in the then standard PostScript world. After some years,
 492 I managed to convince a student of mine Ales Snuparek to implement my ideas as his bachelor's project.
 493 He wrote the program PsPdfTool for transforming both PostScript and PDF documents, which turned
 494 out to be terribly useful.
 495
 496 In the 2010's, limitations of the old design became clear and many PDF documents were using
 497 features not known to PsPdfTool (most prominently object streams). After several years of
 498 pondering, I became fond of the QPDF library and wrote PaperJam as a modern successor of
 499 PsPdfTool.