Debian Codegraph @

upstream/debian-unstable/man1/pstops.1

raw
1 .TH PSTOPS "1" "2025\-09\-08" "psutils 3.3.14" "User Commands"
2 .SH NAME
3 pstops
4 .SH SYNOPSIS
5 .B pstops
6 [OPTION...] [INFILE [OUTFILE]]
7 .SH DESCRIPTION
8 Rearrange pages of a PDF or PostScript document.
9 PostScript files should follow the Adobe Document Structuring
10 Conventions.
11 .PP
12 .I Pstops
13 can be used to perform arbitrary re-arrangements of documents. For many tasks,
14 it is simpler to use the other utilities in the PSUtils suite: see
15 .BR psutils (1).
16
17 .TP
18 \fBINFILE\fR
19 `\-' or no INFILE argument means standard input
20
21 .TP
22 \fBOUTFILE\fR
23 `\-' or no OUTFILE argument means standard output
24
25 .SH OPTIONS
26 .TP
27 \fB\-S\fR \fI\,SPECS\/\fR, \fB\-\-specs\fR \fI\,SPECS\/\fR
28 page specifications (see below)
29
30 .TP
31 \fB\-R\fR \fI\,PAGERANGE\/\fR, \fB\-\-pages\fR \fI\,PAGERANGE\/\fR
32 select the given page ranges
33
34 .TP
35 \fB\-e\fR, \fB\-\-even\fR
36 select even\-numbered output pages
37
38 .TP
39 \fB\-o\fR, \fB\-\-odd\fR
40 select odd\-numbered output pages
41
42 .TP
43 \fB\-r\fR, \fB\-\-reverse\fR
44 reverse the order of the output pages
45
46 .TP
47 \fB\-p\fR \fI\,PAPER\/\fR, \fB\-\-paper\fR \fI\,PAPER\/\fR
48 output paper name or dimensions (WIDTHxHEIGHT)
49
50 .TP
51 \fB\-P\fR \fI\,INPAPER\/\fR, \fB\-\-inpaper\fR \fI\,INPAPER\/\fR
52 input paper name or dimensions (WIDTHxHEIGHT)
53
54 .TP
55 \fB\-d\fR \fI\,[DIMENSION]\/\fR, \fB\-\-draw\fR \fI\,[DIMENSION]\/\fR
56 draw a line of given width (relative to original
57 page) around each page [argument defaults to 1pt;
58 default is no line; width is fixed for PDF]
59
60 .TP
61 \fB\-v\fR, \fB\-\-version\fR
62 show program's version number and exit
63
64 .TP
65 \fB\-q\fR, \fB\-\-quiet\fR
66 don't show progress
67
68 .SH COMMENTS
69 PAGES is a comma\-separated list of pages and page ranges.
70
71 SPECS is a list of page specifications [default is "0", which selects
72 each page in its normal order].
73 .PP
74 Pagespecs have the following syntax:
75 .RS
76 .TP 12
77 .I pagespecs
78 =
79 .RI [ modulo\fB:\fP ] specs
80 .TP
81 .I specs
82 =
83 .IR spec [ \fB+\fPspecs | \fB,\fPspecs ]
84 .TP
85 .I spec
86 =
87 .RB [ - ] \fIpageno\fP [\fItransform...\fP][ @\fIscale\fP ][ ( \fIxoff\fP , \fIyoff\fP ) ]
88 .TP
89 .I transform
90 =
91 .BR L | R | U | H | V
92 .RE
93 .sp
94 .I modulo
95 is the number of pages in each block.
96 The value of
97 .I modulo
98 should be greater than 0; the default value is 1.
99 .PP
100 .I specs
101 are the page specifications for the pages in each block.
102 The value of the
103 .I pageno
104 in each
105 .I spec
106 should be between 0 (for the first page in the block) and \fImodulo\fR\-1
107 (for the last page in each block) inclusive.
108 If there is only one page specification,
109 the \fIpageno\fR (0) may be omitted.
110 .PP
111 The optional dimensions
112 .I xoff
113 and
114 .I yoff
115 shift the page by the specified amount.
116 .I xoff
117 and
118 .I yoff
119 may either be lengths (see
120 .BR psutils (1))
121 or followed by
122 .B "w"
123 or
124 .B "h"
125 to indicate a multiple of the output page width or height.
126 .PP
127 The optional transformations
128 .BR L ,
129 .BR R ,
130 .BR U ,
131 .BR H ,
132 and
133 .B V
134 rotate the page left, right, or upside-down around its lower left corner,
135 and flip (mirror) the page horizontally or vertically respectively.
136 The optional
137 .I scale
138 parameter scales the page by the factor specified.
139 If the optional minus sign is specified, the page number is relative to the end of
140 the document, instead of the start.
141 .PP
142 Pages whose
143 .IR spec s
144 are separated by
145 .B +
146 will be merged into a single page; otherwise,
147 they will remain as separate pages.
148 .PP
149 The shift, rotation, and scaling are applied
150 to the PostScript transformation matrix
151 in that order, regardless of the order
152 in which they appear on the command line.
153 .PP
154 Paper size names are converted to dimensions using
155 .BR paper (1).
156 The output page size, if set, is used (after scaling) to set the
157 clipping path for each page.
158 .SH EXAMPLES
159 To put two A or B series pages (e.g. A4 or B5) on one sheet of paper, the pagespec to use is:
160 .sp
161 .ce
162 2:[email protected](1w,0)[email protected](1w,0.5h)
163 .sp
164 To select all of the odd pages in reverse order, use:
165 .sp
166 .ce
167 2:-0
168 .sp
169 To re-arrange pages for printing 2-up booklets, use
170 .sp
171 .ce
172 4:[email protected](1w,0h)[email protected](1w,0.5h)
173 .sp
174 for the front sides, and
175 .sp
176 .ce
177 4:[email protected](1w,0h)[email protected](1w,0.5h)
178 .sp
179 for the reverse sides, or, for long-edge duplex printing, join the two specs thus:
180 .sp
181 .ce
182 4:[email protected](1w,0h)[email protected](1w,0.5h),[email protected](1w,0h)[email protected](1w,0.5h)
183 .sp
184 For short-edge duplex, the incantation is:
185 .sp
186 .ce
187 4:[email protected](1w,0h)[email protected](1w,0.5h),[email protected](0w,0.5h)[email protected](0w,1h)
188 .sp
189
190 .SH AUTHOR
191 .nf
192 .SH BUGS
193 .B pstops
194 does not accept all DSC comments.
195 .fi