From 9e7adbfd8d6eabb4c3a2a3a4b350215414d84c6a Mon Sep 17 00:00:00 2001 From: Martin Mares Date: Sat, 28 Apr 2018 22:11:53 +0200 Subject: [PATCH] Documentation: Minor fixes, trimming of TODO --- TODO | 70 ++------------------------------------- paperjam.1.txt | 89 +++++++++++++++++++++++++++++--------------------- 2 files changed, 54 insertions(+), 105 deletions(-) diff --git a/TODO b/TODO index d5a20d3..4953852 100644 --- a/TODO +++ b/TODO @@ -1,80 +1,14 @@ - Integrate pdf-tools.cc with the rest of the code - What if an input page specifies /Rotate? - "-f" switch +- What should do modulo(half) with an odd number of tuples? Improve, or at least document. -| # Position bbox on a new paper -| paper("a4") -| paper(w=210mm,h=297mm,pos=(t|b|c)(l|r|c)) - -| # Scale paper to a new size -| scaleto("a4") -| scaleto(w=210mm,h=297mm,pos=tl) - -| # Fit image to a paper -| # If paper is given: scale image -| # If no paper is given: adjust paper to image + margins -| fit("a4") -| fit(w=, h=) -| margin= hmargin= vmargin= -| lmargin= rmargin= tmargin= bmargin= -| pos= - -| # Adjust paper size -| expand(10mm) -| expand(h=10mm, v=20mm) -| expand(l=10mm, r=10mm, t=10mm, b=10mm) - -| # Adjust image size (in terms of margins around) -| margins ... params like expand - -| cropmarks -| mark=box # Box around image -| mark=cross # Crosses in the corners -| mark=out # Out-pointing half-crosses in the corners (default) -| mark=in # In-pointing half-crosses -| mark=bg # Colored background -| pen=1pt # Line width -| len=5mm # Cross arm length -| offset=5mm # Distance from border -| color="RRGGBB" - -| book -| signature= - -| # Clip to image box -| clip -| bleed=5mm # Allow bleeding over the image box +Ideas for further commands: # Can be written as: mix(cat) { modulo(2){1}, modulo(2){2} } duplex long-edge -| merge - -| modulo -| half - -| # Add an empty page after the current one -| add-blank -| n= -| paper... - -| # Set either: -| # - paper size + margins -| # - scale + margins -| nup(hnum, vnum) -| by=rows/cols # Filling order (default: rows) -| by=tile # Tile with copies of a single page -| paper / w / h # Specify paper size, default=copy from 1st image -| + fit options (*margin, pos) -| tpos=... # Position of images inside their tiles (default: tl) -| crop # Crop to image -| mixed # Allow images of different sizes -| rotate=1 # Override rotation decision -| scale=1 # Override scaling factor -| hspace / vspace / space # Distance between tiles -| cmark, cpen, clen, coffset, ccolor # Cropmark parameters - # Send pages to multiple pipes and merge their results mix { ..., ..., ...} cat # Concatenate results (default is interleave) diff --git a/paperjam.1.txt b/paperjam.1.txt index 1fc9546..d238c9c 100644 --- a/paperjam.1.txt +++ b/paperjam.1.txt @@ -19,7 +19,7 @@ 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 +of the 'physical page' (paper), 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 @@ -45,7 +45,7 @@ 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 +underscores, and dashes, which begins 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 @@ -95,7 +95,7 @@ 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. +for parsing the names. You can call +paperconf -a+ to get the list of known names. Margins ~~~~~~~ @@ -112,11 +112,11 @@ to vertical. Positioning ~~~~~~~~~~~ -Multiple commands require positioning an image on a larger page. The image +Multiple commands involve 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. +*c* for center, *r* for right. COMMANDS -------- @@ -131,7 +131,7 @@ Add blank page(s) after each page. 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.) + Paper size of the blank pages (see Paper formats above). apply ~~~~~ @@ -142,7 +142,7 @@ Applies commands on a sub-set of pages: 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. +the page is left unchanged. If multiple stages match, the first one wins. book ~~~~ @@ -170,7 +170,7 @@ 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 +and heights and the new image box to the minimal rectangle containing all image boxes. cropmarks @@ -179,11 +179,11 @@ 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. + *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). @@ -229,11 +229,11 @@ 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=]*'string', *w=*'dimen', *h=*'dimen':: Paper format, or paper width and height (see Paper formats above for details). -*pos=*'string': +*pos=*'string':: Specify position of the image on the paper (see Positioning above). Defaults to *cc*. @@ -244,10 +244,10 @@ flip ~~~~ Flip pages horizontally or vertically. -*h=*'switch': +*h=*'switch':: Flip horizontally. -*v=*'switch': +*v=*'switch':: Flip vertically. margins @@ -289,7 +289,7 @@ Arguments: *[n=]*'int' (mandatory):: Number of pages in a single tuple. -*half=*'switch': +*half=*'switch':: Process only the first half of n-tuples. This is often used in conjunction with negative page numbers. @@ -303,7 +303,7 @@ While this command skips every other page: move ~~~~ -Shift (translate) contents on the page. +Shift contents on the page. Paper size does not change, the image box moves. *[x=]*'dimen', *[y=]*'dimen':: Move everything right/up by the given distance. @@ -315,8 +315,8 @@ 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 +parameters, but if only a subset of the parameters is given (in the most trivial case, +just 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, @@ -338,26 +338,26 @@ each page to fit in its tile. *[m=]*'number':: The number of columns of the grid of tiles. -*by=*'string': +*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=*'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': +*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': +*rotate=*'switch':: Specify if the pages should be rotated. Default: choose automatically. -*scale=*'number': +*scale=*'number':: Scaling factor. Default: choose automatically. *[paper=]*'string', *w=*'dimen', *h=*'dimen':: @@ -372,27 +372,27 @@ each page to fit in its tile. 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': +*cmark=*'string', *cpen=*'dimen', *clen=*'dimen', *coffset=*'dimen', *ccolor=*'string':: Draw cropmarks around each tile. See *crop* for the meaning of arguments. -*tpos=*'string': +*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': +*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 +Place image on a given paper. Sets a new paper size and translates the image box according to the given position. *[paper=]*'string', *w=*'dimen', *h=*'dimen':: Paper size (see Paper formats above). -*pos=*'string': +*pos=*'string':: Position of the image on the paper (see Positioning above). Default: *cc*. rotate @@ -406,7 +406,7 @@ scale ~~~~~ Scale the page by a given factor. -*[x=]*'number', *[y=]*'number': +*[x=]*'number', *[y=]*'number':: Set horizontal and vertical scaling factor. If only one is given, it is used in both directions. @@ -417,7 +417,7 @@ Scale the entire page to a given size. *[paper=]*'string', *w=*'dimen', *h=*'dimen':: Paper size (see Paper formats above). -*pos=*'string': +*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. @@ -430,15 +430,16 @@ right. For each stage, it assembles a temporary document containing the selected 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: +For example, the following command selects pages 1, 10 to 19, and 20 to 29 in reverse order. +The rest of the document is discarded. select { 1 10..19 29..20 } -This is the same: +This has the same effect: select { 1, 10..19, 29..20 } -This select two pages and rotates them differently: +This selects two pages and rotates them differently: select { 1: rotate(90), 2: rotate(-90) } @@ -452,7 +453,7 @@ a difference sometimes: 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 +three 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 @@ -463,3 +464,17 @@ 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. + +HISTORY +------- +I conceived the idea of a document processor like Paperjam when struggling with pre-press +formatting in the early 2000's. At that time, the basic ideas behind the language were born, +but everything was deeply rooted in the then standard PostScript world. After some years, +I managed to convince a student of mine Ales Snuparek to implement my ideas as his bachelor's project. +He wrote the program PsPdfTool for transforming both PostScript and PDF documents, which turned +out to be terribly useful. + +In the 2010's, limitations of the old design became clear and many PDF documents were using +features not known to PsPdfTool (most prominently object streams). After several years of +pondering, I became fond of the QPDF library and wrote Paperjam as a modern successor of +PsPdfTool. -- 2.39.2