| 1 |
.\" Manpage for pdfxup. |
| 2 |
.\" Contact [email protected] to correct errors or typos. |
| 3 |
.TH man 1 "11 june 2024" "2.12" "pdfxup man page" |
| 4 |
.SH NAME |
| 5 |
pdfxup \- n-up tool with reduced margins |
| 6 |
.SH SYNOPSIS |
| 7 |
pdfxup [OPTIONS] [FILE] |
| 8 |
.SH DESCRIPTION |
| 9 |
pdfxup creates a PDF document where each page is obtained by combining |
| 10 |
several pages of a PDF file given as output. The important feature of |
| 11 |
pdfxup, compared to similar programs, is that it tries to compute the |
| 12 |
(global) bounding box of the input PDF file, in order to remove the |
| 13 |
margins and to keep the text only. Instead of having the font size |
| 14 |
divided by 2 (for the case of 2-up output), in some case you may end up |
| 15 |
with almost the same font size as in the original document (as is the |
| 16 |
case for a default 'article' document produced by LaTeX). |
| 17 |
|
| 18 |
pdfxup uses ghostscript for computing the maximal bounding box of (some |
| 19 |
of) the pages of the document, and then uses pdflatex (with graphicx |
| 20 |
package) in order to produce the new document. |
| 21 |
.SH OPTIONS |
| 22 |
pdfxup accepts numerous options. The most important ones are: |
| 23 |
.\" additional options should be lister here... |
| 24 |
.TP |
| 25 |
\fB\-x\fR m, \fB\-\-columns\fR m |
| 26 |
sets the number of columns of the output file (default 2); |
| 27 |
.TP |
| 28 |
\fB\-y\fR n, \fB\-\-rows\fR n |
| 29 |
sets the number of lines of the output file (default 1); |
| 30 |
.TP |
| 31 |
\fB\-nup\fR m\fBx\fRn, \fB\--nup\fR m\fBx\fRn |
| 32 |
sets the number of rows and columns of the output file (default 2x1); |
| 33 |
.TP |
| 34 |
\fB\-l\fR (0|1), \fB\-\-landscape\fR, \fB\-\-portrait\fR |
| 35 |
sets orientation of paper (of final document); |
| 36 |
.TP |
| 37 |
\fB\-cf\fR file, \fB\-\-config \fR file, \fB\-\-mode \fR file |
| 38 |
reads file (with extension \fB.xup\fR) and uses options defined in that |
| 39 |
file (see below for details about \fB.xup\fR files). |
| 40 |
All options are processed in the order the appear on the command-line, |
| 41 |
so that it is possible to modify the options set in the configuration |
| 42 |
file (and it is even possible to include several configuration files, the |
| 43 |
later one overwriting the options set by the previous ones). |
| 44 |
Files are looked-up using kpsewhich (if available). |
| 45 |
.TP |
| 46 |
\fB\-b\fR (le|se), \fB\-\-booklet\fR (le|se) |
| 47 |
configure for printing as a booklet. Value 'le' (which is the default |
| 48 |
value when \fB\-b\fR is used with no argument) means that two-sided |
| 49 |
printing is in 'long-edge' mode (you turn from one page to the next |
| 50 |
along the long edge of the paper). 'se' is the 'short-edge' option. |
| 51 |
.TP |
| 52 |
\fB\-c\fR, \fB\-\-clip\fR, \fB\-nc\fR, \fB\-\-no-clip\fR |
| 53 |
clip (or don't clip) pages to the computed bounding box. By default, |
| 54 |
content is clipped, to avoid overlap between neighbouring pages. |
| 55 |
With \fB--no-clip\fR, anything outside the bounding box will be |
| 56 |
displayed. |
| 57 |
.TP |
| 58 |
\fB\-o\fR file, \fB\-\-output\fR file |
| 59 |
name of output file. |
| 60 |
.TP |
| 61 |
\fB\-i\fR |
| 62 |
ask before overwriting output file. |
| 63 |
.TP |
| 64 |
\fB\-ow\fR |
| 65 |
overwrite output file without asking. |
| 66 |
.TP |
| 67 |
\fB\-ps\fR s, \fB\-\-paper\fR s |
| 68 |
sets paper size (default a4). The name must be known by package geometry |
| 69 |
(more precisely, "<s>paper" should be defined in that package). |
| 70 |
.TP |
| 71 |
\fB\-fw\fR d, \fB\-\-framewidth\fR d |
| 72 |
width of the frame around each page (default 0.4pt). Set to 0pt to have no |
| 73 |
frame at all. |
| 74 |
.TP |
| 75 |
\fB\-tf\fR [0|1], \fB\-\-tight-frame\fR [0|1] |
| 76 |
whether the frame should be tight around the page, leaving horizontal |
| 77 |
white space outside the frame, or should be wide and span the whole |
| 78 |
available width. |
| 79 |
.TP |
| 80 |
\fB\-im\fR d, \fB\-\-innermargins\fR d |
| 81 |
inner margin between frame and page (default 5pt). |
| 82 |
.TP |
| 83 |
\fB\-m\fR d, \fB\-\-margins\fR d |
| 84 |
margin of pages of the new document (default 5pt). |
| 85 |
.TP |
| 86 |
\fB\-is\fR d, \fB\-\-intspaces\fR d |
| 87 |
space between different pages (default 1pt). |
| 88 |
.TP |
| 89 |
\fB\-p\fR list, \fB\-\-pages\fR list |
| 90 |
only consider sublist of pages of input document. List is a |
| 91 |
comma-separated list of pages or ranges pages of the form a-b; a can |
| 92 |
be omitted to start from first page, and b can be omitted to end at |
| 93 |
the last page. Therefore, "\fB\-p\fR -" (which is the default) |
| 94 |
includes all pages. Also allows modulo, so that "\fB\-p\fR 0%2" would |
| 95 |
include only even-numbered pages. |
| 96 |
.TP |
| 97 |
\fB\-bb\fR list, \fB\-\-bb\fR list |
| 98 |
only consider sublist of pages of input document for computing bounding box. |
| 99 |
.TP |
| 100 |
\fB\-nobb\fR list, \fB\-\-no-bb\fR list |
| 101 |
omit list of pages of input document from computation of bounding box. |
| 102 |
.TP |
| 103 |
\fB\-g\fR, \fB\-\-get-bb\fR |
| 104 |
only compute (and output) bounding box. Will not produce any output file. |
| 105 |
.TP |
| 106 |
\fB\-kbb\fR, \fB\-\-keep-bb\fR |
| 107 |
do not compute bounding box, preserve current margins. |
| 108 |
.TP |
| 109 |
\fB\-s\fR x y W H, \fB\-\-set-bb\fR x y W H |
| 110 |
set the bounding box to the given values. Values are in pt; the first two |
| 111 |
elements correspond to the lower left corner, while the last two represent |
| 112 |
the width and height of the part to be displayed. |
| 113 |
.TP |
| 114 |
\fB\-w\fR file, \fB\-\-watermark\fR file |
| 115 |
use file as background watermark. file can be any format accepted by |
| 116 |
pdflatex (e.g. png or pdf). If file is a multipage PDF file, page n of |
| 117 |
the watermark file is used with page n of the input file, and the last |
| 118 |
page of the watermark file is repeated if the input file has more pages. |
| 119 |
.TP |
| 120 |
\fB\-wp\fR p, \fB\-\-watermark-period\fR p |
| 121 |
repeat the last p pages of the watermark file instead of only the last one. |
| 122 |
.TP |
| 123 |
\fB\-d\fR, \fB\-\-debug\fR |
| 124 |
debug mode: keep intermediary files. |
| 125 |
.TP |
| 126 |
\fB\-col\fR, \fB\-\-column-mode\fR, \fB\-\-vertical\fR |
| 127 |
fill in pages top-down first (instead of the default left-to-right mode). |
| 128 |
By default, pages are inserted from left-to-right, until the line is full; |
| 129 |
with this option, pages are inserted from top to bottom, until the column |
| 130 |
is full. For instance: |
| 131 |
.nf |
| 132 |
--------- --------- |
| 133 |
row-mode | 1 2 3 | column-mode | 1 4 7 | |
| 134 |
| 4 5 6 | | 2 5 8 | |
| 135 |
| 7 8 9 | | 3 6 9 | |
| 136 |
--------- --------- |
| 137 |
|
| 138 |
.fi |
| 139 |
.TP |
| 140 |
\fB\-row\fR, \fB\-\-row-mode\fR, \fB\-\-horizontal\fR |
| 141 |
fill in pages left to right. |
| 142 |
.TP |
| 143 |
\fB\-bal\fR, \fB\-\-balance-last\fR |
| 144 |
balance last page: when using column mode, the pages are filled in from |
| 145 |
top to bottom, and the last page is no exception. Still, it may be prefered |
| 146 |
that the columns in the last page remains "balanced", which is what this |
| 147 |
option achieves. Symmetrically, in row mode, this option would balance the |
| 148 |
rows. |
| 149 |
.nf |
| 150 |
--------- --------- |
| 151 |
row, no-balance | 1 2 3 | column, no-balance | 1 4 | |
| 152 |
| 4 5 | | 2 5 | |
| 153 |
| | | 3 | |
| 154 |
--------- --------- |
| 155 |
|
| 156 |
--------- --------- |
| 157 |
row, balance | 1 2 | column, balance | 1 3 5 | |
| 158 |
| 3 4 | | 2 4 | |
| 159 |
| 5 | | | |
| 160 |
--------- --------- |
| 161 |
|
| 162 |
.fi |
| 163 |
.TP |
| 164 |
\fB\-V [0-3]\fR, \fB\-\-verbose\fR [0-3] |
| 165 |
select verbosity (default: 1). |
| 166 |
.TP |
| 167 |
\fB\-q\fR, \fB\-\-quiet\fR |
| 168 |
run quietly (equiv. '-V 0'). |
| 169 |
.TP |
| 170 |
\fB\-v\fR, \fB\-\-version\fR |
| 171 |
print version number and exit. |
| 172 |
.TP |
| 173 |
\fB\-h\fR, \fB\-\-help\fR |
| 174 |
print help message and exit. |
| 175 |
.SH CONFIGURATION FILES |
| 176 |
Configuration files (extension \fB.xup\fR) are bash scripts used |
| 177 |
to set some variables. If option "\fB--config-file\fR <file>" |
| 178 |
(or equivalent) is used, <file> is looked up with kpsewhich |
| 179 |
first, if it contains no '/'. If kpsewhich does not find it, |
| 180 |
then pdfxup checks if the file exists (using 'test -e') before |
| 181 |
sourcing it (the \fBPATH\fR variable will not be used to find |
| 182 |
it). |
| 183 |
|
| 184 |
The script should only set some internal variables of pdfxup, such as |
| 185 |
\fBNB_ROWS\fR, \fBNB_COLUMNS\fR, \fBLANDSCAPE\fR (to set up a |
| 186 |
predefined layout). It can be used to set the bounding box, but it is |
| 187 |
often better to compute it on the first few pages of the document. |
| 188 |
Here are some examples of lines that can be put in a \fB.xup\fR file: |
| 189 |
.TP |
| 190 |
\fBNB_COLUMNS=1\fR |
| 191 |
set the number of columns to 1 |
| 192 |
.TP |
| 193 |
\fBNB_ROWS=2\fR |
| 194 |
set the number of rows to 2 |
| 195 |
.TP |
| 196 |
\fBLANDSCAPE=0\fR |
| 197 |
set portrait mode |
| 198 |
.TP |
| 199 |
\fBKEEP_ORIG_BBOX=1\fR |
| 200 |
do not crop margins |
| 201 |
.TP |
| 202 |
\fBSET_BBOX="75 47 540 755" |
| 203 |
set bounding box: lower left=(75,47); upper right=(540,755) |
| 204 |
.TP |
| 205 |
\fBTIGHT_FRAME=1\fR |
| 206 |
set tight frames around pages |
| 207 |
.TP |
| 208 |
\fBINNER_MARGINS=10pt\fR |
| 209 |
set margin around each page (inside the frame) to 10pt |
| 210 |
.TP |
| 211 |
\fBINTERM_SPACES=10pt\fR |
| 212 |
set space between pages to 10pt |
| 213 |
.TP |
| 214 |
\fBFRAME_WIDTH=2mm\fR |
| 215 |
set frame width to 2mm |
| 216 |
|
| 217 |
.PP |
| 218 |
Other available variables can be found in the \fBsetdefaultvalues\fR function. |
| 219 |
|
| 220 |
.SH EXAMPLES |
| 221 |
.TP |
| 222 |
\fB# pdfxup file.pdf\fR |
| 223 |
produces 2-up pdf file from file.pdf. |
| 224 |
.TP |
| 225 |
\fB# pdfxup -bb 1-4 file.pdf\fR |
| 226 |
same behaviour, but computes the bounding box only using the |
| 227 |
first 4 pages (this saves time when processing long documents). |
| 228 |
.TP |
| 229 |
\fB# pdfxup -b -o booklet.pdf file.pdf\fR |
| 230 |
same behaviour, but creates a booklet (as booklet.pdf). |
| 231 |
.TP |
| 232 |
\fB# pdfxup -kbb -x1 -y2 -l0 beamer-frames.pdf\fR |
| 233 |
arranges 2 beamer frames per page (not reducing margins). |
| 234 |
.TP |
| 235 |
\fB# pdfxup --mode beamer2 beamer-frames.pdf\fR |
| 236 |
arranges PDF pages according to beamer2.xup configuration file. |
| 237 |
.TP |
| 238 |
\fB# pdfxup -kbb -x2 -y2 -l beamer-frames.pdf:1-12,15-19\fR |
| 239 |
arranges 4 beamer frames per page (not reducing margins), including |
| 240 |
only frames 1 to 12 and 15 to 19. |
| 241 |
.SH SEE ALSO |
| 242 |
gs(1), pdflatex(1) |
| 243 |
.SH AUTHOR |
| 244 |
Nicolas Markey ([email protected]) |