Debian Codegraph @

texmf-dist/doc/man/man1/pdfxup.1

raw
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])