From bd6101e9469f271e7e61acff7b74a6fcf13aa21e Mon Sep 17 00:00:00 2001 From: Martin Mares Date: Sat, 28 Apr 2018 21:26:24 +0200 Subject: [PATCH] Added a manual page --- Makefile | 10 +- paperjam.1.txt | 465 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 474 insertions(+), 1 deletion(-) create mode 100644 paperjam.1.txt diff --git a/Makefile b/Makefile index 0129889..dd2ec24 100644 --- a/Makefile +++ b/Makefile @@ -5,7 +5,7 @@ BUILD_COMMIT:=$(shell if git rev-parse >/dev/null 2>/dev/null ; then git describ CXXFLAGS=-O2 -Wall -Wextra -Wno-parentheses -std=gnu++11 -g -all: paperjam +all: paperjam paperjam.1 paperjam.1.html MODULES=paperjam pdf-tools parse cmds pdf OBJS=$(addsuffix .o, $(MODULES)) @@ -19,6 +19,14 @@ $(OBJS): jam.h pdf-tools.h paperjam.o: CXXFLAGS += -DVERSION='"$(VERSION)"' -DYEAR='"$(YEAR)"' -DBUILD_DATE='"$(BUILD_DATE)"' -DBUILD_COMMIT='"$(BUILD_COMMIT)"' +paperjam.1: paperjam.1.txt + a2x -f manpage $< + +# The dependency on paperjam.1 is there to serialize both calls of asciidoc, +# which does not name temporary files safely. +paperjam.1.html: paperjam.1.txt paperjam.1 + a2x -f xhtml -D . $< + clean: rm -f *.o rm -f paperjam diff --git a/paperjam.1.txt b/paperjam.1.txt new file mode 100644 index 0000000..7c8a4a1 --- /dev/null +++ b/paperjam.1.txt @@ -0,0 +1,465 @@ +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. -- 2.39.2