Debian Codegraph @

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

raw
1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 . ds -- \(*W-
28 . ds PI pi
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31 . ds L" ""
32 . ds R" ""
33 . ds C` ""
34 . ds C' ""
35 'br\}
36 .el\{\
37 . ds -- \|\(em\|
38 . ds PI \(*p
39 . ds L" ``
40 . ds R" ''
41 . ds C`
42 . ds C'
43 'br\}
44 .\"
45 .\" Escape single quotes in literal strings from groff's Unicode transform.
46 .ie \n(.g .ds Aq \(aq
47 .el .ds Aq '
48 .\"
49 .\" If the F register is >0, we'll generate index entries on stderr for
50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51 .\" entries marked with X<> in POD. Of course, you'll have to process the
52 .\" output yourself in some meaningful fashion.
53 .\"
54 .\" Avoid warning from groff about undefined register 'F'.
55 .de IX
56 ..
57 .nr rF 0
58 .if \n(.g .if rF .nr rF 1
59 .if (\n(rF:(\n(.g==0)) \{\
60 . if \nF \{\
61 . de IX
62 . tm Index:\\$1\t\\n%\t"\\$2"
63 ..
64 . if !\nF==2 \{\
65 . nr % 0
66 . nr F 2
67 . \}
68 . \}
69 .\}
70 .rr rF
71 .\"
72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
73 .\" Fear. Run. Save yourself. No user-serviceable parts.
74 . \" fudge factors for nroff and troff
75 .if n \{\
76 . ds #H 0
77 . ds #V .8m
78 . ds #F .3m
79 . ds #[ \f1
80 . ds #] \fP
81 .\}
82 .if t \{\
83 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
84 . ds #V .6m
85 . ds #F 0
86 . ds #[ \&
87 . ds #] \&
88 .\}
89 . \" simple accents for nroff and troff
90 .if n \{\
91 . ds ' \&
92 . ds ` \&
93 . ds ^ \&
94 . ds , \&
95 . ds ~ ~
96 . ds /
97 .\}
98 .if t \{\
99 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
100 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
101 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
102 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
103 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
104 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
105 .\}
106 . \" troff and (daisy-wheel) nroff accents
107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
114 .ds ae a\h'-(\w'a'u*4/10)'e
115 .ds Ae A\h'-(\w'A'u*4/10)'E
116 . \" corrections for vroff
117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
119 . \" for low resolution devices (crt and lpr)
120 .if \n(.H>23 .if \n(.V>19 \
121 \{\
122 . ds : e
123 . ds 8 ss
124 . ds o a
125 . ds d- d\h'-1'\(ga
126 . ds D- D\h'-1'\(hy
127 . ds th \o'bp'
128 . ds Th \o'LP'
129 . ds ae ae
130 . ds Ae AE
131 .\}
132 .rm #[ #] #H #V #F C
133 .\" ========================================================================
134 .\"
135 .IX Title "A2PING 1"
136 .TH A2PING 1 "2019-11-28" "a2ping" "Peter Szabo"
137 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
138 .\" way too many mistakes in technical documents.
139 .if n .ad l
140 .nh
141 .ds pts-dev \*[.T]
142 .do if '\*[.T]'ascii' .ds pts-dev tty
143 .do if '\*[.T]'ascii8' .ds pts-dev tty
144 .do if '\*[.T]'latin1' .ds pts-dev tty
145 .do if '\*[.T]'nippon' .ds pts-dev tty
146 .do if '\*[.T]'utf8' .ds pts-dev tty
147 .do if '\*[.T]'cp1047' .ds pts-dev tty
148 .do if '\*[pts-dev]'tty' \{\
149 .ll 79
150 .pl 33333v
151 .nr IN 2n
152 .\}
153 .ad n
154 .SH "NAME"
155 a2ping.pl \-\- convert between PS, EPS and PDF and other page description
156 formats
157 .SH "SYNOPSIS"
158 .IX Header "SYNOPSIS"
159 \fBa2ping.pl\fR [\fB\-\-\fR]\fBhelp\fR
160 \fBa2ping.pl\fR [\fB\-\-\fR]\fBdoc\fR
161 \fBa2ping.pl\fR [\fIoptions\fR] <\fIinputfile\fR> [[\fIoutformat\fR:] \fIoutputfile\fR]
162 .SH "DESCRIPTION"
163 .IX Header "DESCRIPTION"
164 \&\fBa2ping\fR is a \s-1UNIX\s0 command line utility written in Perl that
165 converts many raster image and vector graphics formats to \s-1EPS\s0 or \s-1PDF\s0 and
166 other page description formats. Accepted input file formats are: \s-1PS\s0
167 (PostScript), \s-1EPS, PDF, PNG, JPEG, TIFF, PNM, BMP, GIF, LBM, XPM, PCX,
168 TGA.\s0 Accepted output formats are: \s-1EPS, PCL5, PDF, PDF1, PBM, PGM, PPM,
169 PS,\s0 markedEPS, markedPS, \s-1PNG, XWD, BMP, TIFF, JPEG, GIF, XPM.\s0
170 \&\fBa2ping\fR delegates the low-level work to
171 Ghostscript (\s-1GS\s0), \fBpdftops\fR and \fBsam2p\fR. \fBa2ping\fR fixes many glitches
172 during the \s-1EPS\s0 to \s-1EPS\s0 conversion, so its output is often more compatible
173 and better embeddable than its input.
174 .PP
175 Without the \f(CW\*(C`\-\-below\*(C'\fR option, it is guarenteed to start at the 0,0
176 coordinate. \f(CW\*(C`\-\-below\*(C'\fR, \f(CW\*(C`\-\-hires\*(C'\fR and \f(CW\*(C`\-v\*(C'\fR are recommended options.
177 .PP
178 The page size is set exactly corresponding to the BoundingBox.
179 This means that when Ghostscript renders it, the result needs no
180 cropping, and the \s-1PDF\s0 MediaBox is correct.
181 .PP
182 If the bounding box is not right, of course, you have problems. If you
183 feed crap in, you get crap. But you can supply the
184 \&\fB\-\-bboxfrom=compute\-gs\fR option to make \s-1GS\s0 recompute the bounding box.
185 .PP
186 The name of the input file doesn't matter \*(-- \fBa2ping\fR detects the file
187 format based on the first few bytes of the file. The name of the output
188 file matters if \fIoutformat\fR is missing from the command line: then the
189 extension of the output file determines the FileFormat (\fIoutformat\fR).
190 .SH "EXTERNAL PROGRAMS"
191 .IX Header "EXTERNAL PROGRAMS"
192 The internal file format of \fBa2ping.pl\fR is \s-1PS/EPS.\s0 Everything read is
193 first converted to \s-1PS\s0 or \s-1EPS,\s0 then processed by \fBa2ping.pl\fR, then
194 converted to the output format.
195 .PP
196 To analyse the bounding box and other properties of non-EPS \s-1PS\s0 files
197 (and \s-1EPS\s0 files with option \fB\-\-bboxfrom\fR other than \fB=guess\fR), \s-1GS\s0 is
198 used. Converting \s-1PS\s0 to \s-1EPS\s0 involves this analysis.
199 .PP
200 To write \s-1PDF\s0 files, \s-1GS\s0 is used.
201 .PP
202 To read \s-1PDF\s0 files, \fBpdftops\fR from the \fBxpdf\fR package is used.
203 .PP
204 Sampled input formats are \s-1PNG, JPEG, TIFF, PNM, BMP, GIF, LBM, XPM, PCX\s0
205 and \s-1TGA.\s0 To read sampled input formats, \fBsam2p\fR is used. \fBsam2p\fR is
206 a raster image converter written in \*(C+ by the author of \fBa2ping.pl\fR.
207 .PP
208 Extra output formats are \s-1PNG, XWD, BMP, TIFF, JPEG, GIF\s0 and \s-1XPM.\s0 To
209 write extra output formats, \fBsam2p\fR and \s-1GS\s0 are used.
210 .PP
211 \&\s-1PNM\s0 output formats are \s-1PGM, PGM\s0 and \s-1PPM.\s0 To write \s-1PNM\s0 output formats, \s-1GS\s0
212 is used.
213 .SH "OPTIONS"
214 .IX Header "OPTIONS"
215 .SS "General Options"
216 .IX Subsection "General Options"
217 .IP "\fB\-h\fR, \fB\-\-help\fR" 2
218 .IX Item "-h, --help"
219 Show a summary of the usage
220 .IP "\fB\-\-doc\fR" 2
221 .IX Item "--doc"
222 Show the man page
223 .IP "\fB\-v\fR, \fB\-\-(no)verbose\fR" 2
224 .IX Item "-v, --(no)verbose"
225 Show progress and debug messages (default: no)
226 .SS "Options for the Bounding box"
227 .IX Subsection "Options for the Bounding box"
228 .IP "\fB\-\-(no)hires\fR" 2
229 .IX Item "--(no)hires"
230 Use HiResBoundingBox in the input file, if present (default: yes)
231 .IP "\fB\-\-(no)exact\fR" 2
232 .IX Item "--(no)exact"
233 Use ExactBoundingBox in the input file, if present (default: no)
234 .IP "\fB\-\-(no)keepoldmediabox\fR" 2
235 .IX Item "--(no)keepoldmediabox"
236 keep only old, [0 0]\-based MediaBox in \s-1PDF\s0 (default: no)
237 .IP "\fB\-\-bboxfrom=\fR\fIadsc|compute\-gs|guess|pagesize\fR" 2
238 .IX Item "--bboxfrom=adsc|compute-gs|guess|pagesize"
239 Method for determining the BoundingBox (default: guess)
240 .IP "\fB\-\-(no)below\fR" 2
241 .IX Item "--(no)below"
242 Allow page content below and left of the origin (default: no)
243 .SS "Options for graphics and fonts"
244 .IX Subsection "Options for graphics and fonts"
245 .IP "\fB\-\-(no)compress\fR" 2
246 .IX Item "--(no)compress"
247 use compression (default: best)
248 .IP "\fB\-\-(no)antialias\fR" 2
249 .IX Item "--(no)antialias"
250 render shades at outlines. Possible values: (=\fIscale3yes\fR =\fIno\fR =\fIyes\fR) (default: scale3no)
251 .IP "\fB\-\-(no)lossy\fR" 2
252 .IX Item "--(no)lossy"
253 allow lossy image filters (\s-1EPS\-\s0>\s-1PDF\s0) (default: yes)
254 .IP "\fB\-\-papersize=\fR\fIunchanged|force\-unknown|600bpx5cm\fR" 2
255 .IX Item "--papersize=unchanged|force-unknown|600bpx5cm"
256 (default: default) (bp)
257 .IP "\fB\-\-threshold=\fR" 2
258 .IX Item "--threshold="
259 min color for 1 in 8\->1 bit conv (default: 128)
260 .SS "Options for debugging and changing internals"
261 .IX Subsection "Options for debugging and changing internals"
262 .IP "\fB\-\-(no)tmpunlink\fR" 2
263 .IX Item "--(no)tmpunlink"
264 Unlink temporary files (default: yes). Use \fB\-\-notmpunklink\fR if you
265 want to inspect intermediate files.
266 .IP "\fB\-\-gs\-cmd=\fR\fIpath\fR" 2
267 .IX Item "--gs-cmd=path"
268 path to Ghostscript program (default: gs or gswin32c)
269 .IP "\fB\-\-gs\-ccmd=\fR\fIpath\fR" 2
270 .IX Item "--gs-ccmd=path"
271 path to Ghostscript for BoundingBox calculation (default: gs or gswin32c)
272 .IP "\fB\-\-gsextra=\fR\fI\s-1GS_ARGS\s0\fR" 2
273 .IX Item "--gsextra=GS_ARGS"
274 Pass extra arguments to gs
275 .IP "\fB\-\-extra=\fR" 2
276 .IX Item "--extra="
277 Pass extra arguments to external program (i.e pdftops)
278 .SH "TIPS AND TRICKS"
279 .IX Header "TIPS AND TRICKS"
280 .IP "\(bu" 2
281 If your \s-1EPS\s0 contains a wrong bounding box, you can fix it by running
282 \&\f(CW\*(C`a2ping.pl \-v \-\-bboxfrom=compute\-gs thefile.eps \-\-\*(C'\fR
283 .IP "\(bu" 2
284 You can specify \fB\-\fR as \fIinputfile\fR to get stdin and as \fIoutputfile\fR
285 to get stdout. This works even for \s-1PDF\s0 files (which must be seekable),
286 because \fBa2ping\fR copies them to a temporary file automatically.
287 .IP "\(bu" 2
288 If \fIinputfile\fR and \fIoutputfile\fR are the same, \fBa2ping\fR copies the
289 \&\fIinputfile\fR to a temporary location first. However, this usage is
290 recommended only if there is a backup of the file to be restored in case
291 \&\fBa2ping\fR doesn't produce the desired result.
292 .IP "\(bu" 2
293 If you specify \fB\-\-\fR as \fIoutputfile\fR, it will be the same as \fIinputfile\fR.
294 .IP "\(bu" 2
295 \&\fBa2ping\fR respects \fB\-\-Duplex\fR for FileFormat \s-1PCL5,\s0 even though \s-1GS\s0 doesn't.
296 .IP "\(bu" 2
297 If you have an incompatible \s-1PS\s0 that \s-1GS\s0 can read but your printer cannot print,
298 just run \f(CW\*(C`a2ping.pl foo.ps PDF: \- | a2ping.pl \- PS: foo.ps\*(C'\fR
299 .IP "\(bu" 2
300 If you have a \s-1PS\s0 coming from Win32 (often with extension \f(CW\*(C`.prn\*(C'\fR), run
301 it through \fBa2ping\fR. It will remove the resolution changes and the
302 progress text printed to the terminal (which confuses \fBgv\fR\|(1) and makes
303 some filters in the print queue emit incorrect output).
304 .IP "\(bu" 2
305 \&\fBa2ping\fR does antialiasing (\fB\-\-antialias=scale3no\fR) of glyphs and
306 curves when emitting a sampled image (FileFormats such as \s-1PGM\s0 and \s-1PPM\s0).
307 This improves readability of the glyphs. \fB=yes\fR instructs \s-1GS\s0 to do
308 internal antialiasing, but it usually doesn't improve much. \fB=scale3no\fR
309 turns off \s-1GS\s0 internal antialiasing, but makes it render everything 3x3
310 as big, and then scales it back down. \fB=scale3no\fR turns on both 3x3
311 scaling and \s-1GS\s0 internal antialiasing, which results in thicker lines and
312 worse quality in general.
313 .IP "\(bu" 2
314 When creating a \s-1PBM\s0 file, antialiasing usually doesn't improve the
315 quality, so it is switched off by default. But if you set
316 \&\fB\-\-antialias=scale3no\fR or \fB\-\-antialias=scale3yes\fR, \s-1GS\s0 will render a \s-1PGM\s0 file,
317 and the value of \fB\-\-threshold\fR determines the minimum intensity for white in
318 the final \s-1PBM.\s0
319 .IP "\(bu" 2
320 If you need a bigger sampled output file, specify a larger
321 \&\fB\-\-Resolution\fR. The default is \fB\-\-Resolution=72\fR. If your sampled output file
322 is going to be really big, you should specify \fB\-\-AntiAlias=yes\fR instead of
323 the default \fB\-\-AntiAlias=scale3no\fR to speed up conversion.
324 .IP "\(bu" 2
325 To make sure fonts are included in a \s-1PDF\s0 file generated from eps, use
326 \&\fB\-\-gsextra='\-dEmbedAllFonts=true \-dPDFSETTINGS=/printer'\fR.
327 .SH "MISC"
328 .IX Header "MISC"
329 .IP "\(bu" 2
330 Doesn't depend on the filename or extension of the input file.
331 .IP "\(bu" 2
332 Conversion from \s-1EPS\s0 to \s-1PDF:\s0 fixes glitches etc., calls gs
333 \&\-sDEVICE=pdfwrite
334 .IP "\(bu" 2
335 Conversion from \s-1EPS\s0 to \s-1EPS:\s0 fixes various glitches, moves (llx,lly) to
336 (0,0), removes binary junk from the beginning of the \s-1EPS\s0 etc.
337 .IP "\(bu" 2
338 Conversion from \s-1PDF\s0 to \s-1PDF:\s0 keeps the file intact
339 .IP "\(bu" 2
340 Conversion from \s-1PDF\s0 to \s-1EPS:\s0 calls pdftops \-eps (of the xpdf package)
341 .IP "\(bu" 2
342 Conversion from \s-1PS\s0 to \s-1EPS:\s0 keeps 1st page only, removes setpagedevice etc.
343 .SH "AUTHORS"
344 .IX Header "AUTHORS"
345 The author of \fBa2ping\fR is Pe\*'ter Szabo\*' <\[email protected]\fR>.
346 .PP
347 \&\fBa2ping\fR is inspired by and historically based on the \fBepstopdf\fR Perl
348 script modified by Thomas Esser, Sept. 1998, but his modifications have
349 been removed from \fBa2ping\fR, and also \fBa2ping\fR and \fBepstopdf\fR do not
350 share common code anymore. \fBepstopdf\fR is written by Sebastian Rahtz,
351 for Elsevier Science. \fBepstopdf\fR contained extra tricks from Hans Hagen's
352 texutil.
353 .PP
354 \&\fBa2ping\fR contains contributions from several people, see the file
355 \&\fI\s-1HISTORY\s0.txt\fR for details. Thank you all for contributing!