Debian Codegraph @

upstream/debian-unstable/man1/pbmtextps.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Pbmtextps User Manual" 1 "17 February 2023" "netpbm documentation"
7
8 .SH NAME
9 pbmtextps - render text into a PBM image using a postscript interpreter
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBpbmtextps\fP
15 [\fB-font\fP \fIfontname\fP]
16 [\fB-fontsize\fP \fIfloat\fP]
17 [\fB-resolution\fP \fIn\fP]
18 [\fB-leftmargin=\fP\fIn\fP]
19 [\fB-rightmargin=\fP\fIn\fP]
20 [\fB-topmargin=\fP\fIn\fP]
21 [\fB-bottommargin=\fP\fIn\fP]
22 [\fB-ascent=\fP\fIn\fP]
23 [\fB-descent=\fP\fIn\fP]
24 [\fB-pad\fP]
25 [\fB-crop\fP]
26 [\fB-stroke\fP \fIn\fP]
27 [\fB-asciihex\fP]
28 [\fB-ascii85\fP]
29 [\fB-verbose\fP]
30 [\fB-dump-ps\fP]
31 \fItext\fP [\fItext\fP ...]
32
33 .UN description
34 .SH DESCRIPTION
35 .PP
36 This program is part of
37 .BR "Netpbm" (1)\c
38 \&.
39 .PP
40 \fBpbmtextps\fP takes a single line of text from the command line and
41 renders it into a PBM image. The image is of a single line of text; newline
42 characters in the input have no effect.
43 .PP
44 See \fBpbmtext\fP for a more sophisticated generator of text, but using
45 less common font formats. \fBpbmtext\fP can generate multiple lines of text.
46 .PP
47 The \fB-plain\fP
48 .UR index.html#commonoptions
49 common option
50 .UE
51 \& has
52 no effect before Netpbm 10.42 (March 2008). The output is always raw PBM.
53
54 .UN margins
55 .SS Margins
56 .PP
57 By default, the image is cropped at the top and the right. It is not
58 cropped at the left or bottom so that the text begins at the same position
59 relative to the origin. The size of the default left and bottom margins is
60 explained below.
61 .PP
62 You can set whatever margin you want with options
63 \fB-leftmargin\fP, \fB-rightmargin\fP, \fB-topmargin\fP and
64 \fB-bottommargin\fP. The specified amount of white space gets added to the
65 far edge of type, e.g. if you specify 10 points for \fB-topmargin\fP, you
66 will get 10 points of white space above the highest character on the line.
67 Specify 0 to crop a side.
68 .PP
69 \fB-ascent\fP adds white space to the top to reach a specified distance
70 above the text baseline, and \fB-descent\fP adds white space to to the bottom
71 to reach a specified distance below the text baseline.
72 .PP
73 \fB-ascent\fP and \fB-descent\fP are more useful than \fB-topmargin\fP
74 and \fB-bottomargin\fP when you render two pieces of text (in separate
75 invocations of \fBpbmtextps\fP) that you will concatenate horizontally.
76 With \fB-ascent\fP and \fB-descent\fP, as long as you specify a value
77 greater than the height or detph of every character in the font, the two
78 images will be the same height with the text baseline in the same place.
79 With \fB-topmargin\fP and \fB-bottommargin\fP, that may not be the case.
80 .PP
81 Example:
82
83 .nf
84 \f(CW
85 $ pbmtextps -font=Times-Roman -descent=20 \e
86 'The soup is called' > a1.pbm
87 $ pbmtextps -font=Itallic -descent=20 'Goulash.' > a2.pbm
88 $ pamcat -leftright -jbottom a1.pbm a2.pbm > out.pbm
89 \fP
90
91 .fi
92 .PP
93 If you're using \fB-descent\fP to line up the segments of text you are
94 concatenating horizontally with \fBpamcat\fP, use the \fB-jbottom\fP
95 (justify to bottom) option on \fBpamcat\fP as in the example above. If you
96 use \fB-ascent\fP, use \fB-jtop\fP instead.
97 .PP
98 Similarly, if you render two lines of text (in separate invocations of
99 \fBpbmtextps\fP) that you will concatenate vertically, \fB-ascent\fP and
100 \fB-descent\fP with sufficiently large values will ensure your baselines
101 are uniformly spaced.
102 .PP
103 If you have \fB-ascent\fP, there is probably no point in specifying
104 \fB-topmargin\fP too, but if you do, the effect is cumulative. The same is
105 true of \fB-descent\fP and \fB-bottommargin\fP.
106 .PP
107 \fB-pad\fP pads the image on the top and bottom to the where the highest
108 and lowest characters in the font would reach, even if you don't have those
109 characters in your text. This is useful if you will generate multiple images
110 of text (with multiple invocations of \fBpbmtextps\fP) and concatenate them
111 vertically to create a multiline text image. \fB-pad\fP makes sure the lines
112 in this image are equally spaced.
113 .PP
114 Example:
115
116 .nf
117 \f(CW
118 $ pbmtextps 'cat' | pamfile
119 $ pbmtextps 'Catty' | pamfile
120 \fP
121
122 .fi
123 .PP
124 The commands above, with no \fB-pad\fP, show that the 'Catty'
125 image is higher because capital C reaches high and 'y' reaches low.
126
127 .nf
128 \f(CW
129 $ pbmtextps -pad 'cat' | pamfile
130 $ pbmtextps -pad 'Catty' | pamfile
131 \fP
132
133 .fi
134 .PP
135 The commands above, with \fB-pad\fP, show that both images are the same
136 height.
137 .PP
138 If you specify \fB-pad\fP with \fB-ascent\fP or \fB-descent\fP, the
139 larger value is effective.
140 .PP
141 \fB-crop\fP makes the program crop all sides to the far edge of the type.
142 It is the same as \f(CW-leftmargin=0 -rightmargin=0 -topmargin=0
143 -bottommargin=0\fP.
144 .PP
145 You cannot specify any other margin-affecting options with \fB-crop\fP.
146 .PP
147 The default top margin, when you specify neither \fB-ascent\fP,
148 \fB-topmargin\fP, nor \fB-pad\fP, is as if you specified
149 \fBtopmargin=0\fP.
150 .PP
151 The default bottom margin, when you specify neither \fB-descent\fP,
152 \fB-bottommargin\fP, nor \fB-pad\fP, is as if you specified
153 \fB-descent=\fP\fI1.5*fontsize\fP.
154 .PP
155 The default left margin, when you do not specify \fB-leftmargin\fP, is
156 as if you specified \fB-leftmargin=\fP\fI0.5*fontsize\fP.
157 .PP
158 The default right margin, when you do not specify \fB-rightmargin\fP,
159 is as if you specified \fB-rightmargin=0\fP.
160
161
162 .UN input_text
163 .SS Input Text
164 .PP
165 The simplest way to specify the text to render is just to specify it,
166 in ASCII, as the sole argument of the command. For example,
167
168 .nf
169 \f(CW
170 $ pbmtextps 'hello world'
171 \fP
172
173 .fi
174 .PP
175 But you can also spread it across multiple arguments. \fBpbmtextps\fP
176 concatenates them right to left with a single space in between:
177
178 .nf
179 \f(CW
180 $ pbmtextps hello world
181 \fP
182
183 .fi
184 .PP
185 With an \fB-asciihex\fP option, you can specify the text in
186 Postscript's ASCII-HEX code:
187
188 .nf
189 \f(CW
190 $ pbmtextps -asciihex 68656c6c6f20776f726c64
191 \fP
192
193 .fi
194 .PP
195 You can optionally include the ASCII-HEX text delimiters that would appear
196 around the text in a Postscript program:
197
198 .nf
199 \f(CW
200 $ pbmtextps -asciihex '<68656c6c6f20776f726c64>'
201 \fP
202
203 .fi
204 .PP
205 Note that the <> delimiters have special meaning to command shells, so if
206 you are invoking \fBpbmtextps\fP via a command shell, be sure to quote them,
207 as is done in this example.
208
209 .PP
210 With \fB-asciihex\fP, you can include white space anywhere in the coded
211 text; it has no effect. And you can spread the argument across multiple
212 arguments as for plain ASCII input:
213
214 .nf
215 \f(CW
216 $ pbmtextps -asciihex '<' 68656c6c6f 20 776f726c64 '>'
217 \fP
218
219 .fi
220 .PP
221 But note that while Postscript allows an ASCII NUL character as white
222 space, there is no way to pass an argument including a NUL character to
223 \fBpbmtextps\fP.
224
225 .PP
226 With an \fB-ascii85\fP option, you can specify the text in
227 Postscript's ASCII-85 code. This is analogous to \fB-asciihex\fP. The
228 Postscript delimiters for an ASCII-85 text string are <~ ~>.
229
230
231 .UN options
232 .SH OPTIONS
233 .PP
234 In addition to the options common to all programs based on libnetpbm
235 (most notably \fB-quiet\fP, see
236 .UR index.html#commonoptions
237 Common Options
238 .UE
239 \&), \fBpbmtextps\fP recognizes the following
240 command line options:
241
242
243 .TP
244 \fB-font=\fP\fIfontname\fP
245 .sp
246 This specifies the font to use. \fIfontname\fP is the name of any valid
247 Postscript font which is installed on the system.
248 .sp
249 The default is \fBTimesRoman\fP.
250 .sp
251 Here is a way to get a list of the names of all the available fonts:
252
253 .nf
254 \f(CW
255 $ gs -c '(*) {==} 256 string /Font resourceforall'
256 \fP
257
258 .fi
259 .sp
260 \fBWarning:\fP if \fIfontname\fP does not name a valid font,
261 \fBpbmtextps\fP just uses the default font. It does not tell you it is doing
262 this.
263
264 .TP
265 \fB-fontsize=\fP\fIfloat\fP
266 This is the size of the font in points. See the \fB-resolution\fP option for
267 information on how to interpret this size.
268 .sp
269 The default is 24 points.
270 .sp
271 Before Netpbm 10.75 (June 2016), this has to be a whole number.
272
273 .TP
274 \fB-resolution=\fP\fIn\fP
275 This is the resolution in dots per inch of distance measurements pertaining to
276 generation of the image. PBM images don't have any inherent resolution, so a
277 distance such as "1 inch" doesn't mean anything unless you separately specify
278 what resolution you're talking about. That's what this option does.
279 .sp
280 In particular, the meaning of the font size is determined by this
281 resolution. If the font size is 24 points and the resolution is 150 dpi, then
282 the font size is 50 pixels.
283 .sp
284 The default is 150 dpi.
285
286 .TP
287 \fB-leftmargin=\fP\fIn\fP
288 .TP
289 \fB-rightmargin=\fP\fIn\fP
290 .TP
291 \fB-topmargin=\fP\fIn\fP
292 .TP
293 \fB-bottommargin=\fP\fIn\fP
294 These options control the margins added to the image, measured from the far
295 edge of the type. See
296 .UR #margins
297 Margins
298 .UE
299 \& for details.
300 .sp
301 All sizes are in points, as a floating point number.
302 .sp
303 These options were new in Netpbm 10.75 (June 2016).
304
305 .TP
306 \fB-ascent=\fP\fIn\fP
307 .TP
308 \fB-descent=\fP\fIn\fP
309 These options control the margins added to the image, measured from
310 the text baseline. See
311 .UR #margins
312 Margins
313 .UE
314 \& for details.
315 .sp
316 Sizes are in points, as a floating point number.
317 .sp
318 These options were new in Netpbm 10.75 (June 2016).
319
320 .TP
321 \fB-pad\fP
322 This pads the image on the top and bottom to the where the highest and lowest
323 characters in the font would reach, even if you don't have those characters in
324 your text. See
325 .UR #margins
326 Margins
327 .UE
328 \& for details.
329 .sp
330 This option was new in Netpbm 10.75 (June 2016).
331
332 .TP
333 \fB-crop\fP
334 This makes the program crop all sides to the far edge of the type. It is the
335 same as \f(CW-leftmargin=0 -rightmargin=0 -topmargin=0 -bottommargin=0\fP.
336 See
337 .UR #margins
338 Margins
339 .UE
340 \& for details.
341 .sp
342 This option was new in Netpbm 10.75 (June 2016).
343
344 .TP
345 \fB-asciihex\fP
346 This means the text in the arguments is in Postscript ASCII-HEX code.
347 See
348 .UR #input_text
349 Input Text
350 .UE
351 \&.
352 .sp
353 You cannot specify this together with \fB-ascii85\fP.
354 .sp
355 This option was new in Netpbm 11.02 (March 2023)
356
357 .TP
358 \fB-ascii85\fP
359 This means the text in the arguments is in Postscript ASCII-85 code.
360 See
361 .UR #input_text
362 Input Text
363 .UE
364 \&.
365 .sp
366 You cannot specify this together with \fB-asciihex\fP.
367 .sp
368 This option was new in Netpbm 11.02 (March 2023)
369
370 .TP
371 \fB-stroke=\fP\fIn\fP
372 This is the width of line, in points, to use for stroke font. There is no
373 default stroke width because the characters are solid by default.
374
375 .TP
376 \fB-verbose\fP
377 This option makes \fBpbmtextps\fP display extra information on Standard Error
378 about its processing.
379
380 .TP
381 \fB-dump-ps\fP
382 This option makes \fBpbmtextps\fP write to Standard Output the Postscript
383 program it would use to create the image, rather than the image itself. You
384 can use this as input to a Postscript interpreter (such as Ghostscript or a
385 printer) or to understand the program better.
386 .sp
387 This option was new in Netpbm 10.75 (June 2016).
388
389
390
391 .UN usage
392 .SH USAGE
393
394 You can generate antialiased text by using a larger resolution than the
395 default and scaling the image down using \fBpamscale\fP.
396 .PP
397 See the manual for the similar \fBpbmtext\fP for more advice on
398 usage.
399
400 .UN history
401 .SH HISTORY
402 .PP
403 \fBpbmtextps\fP was added to Netpbm in Release 10.0 (June 2002).
404
405
406 .UN seealso
407 .SH SEE ALSO
408 .BR "pbmtext" (1)\c
409 \&,
410 .BR "pamcut" (1)\c
411 \&,
412 .BR "pnmcrop" (1)\c
413 \&,
414 .BR "pamcomp" (1)\c
415 \&,
416 .BR "ppmchange" (1)\c
417 \&,
418 .BR "pnmrotate" (1)\c
419 \&,
420 .BR "pamscale" (1)\c
421 \&,
422 .BR "ppmlabel" (1)\c
423 \&,
424 .BR "pbm" (1)\c
425 \&
426
427 .UN author
428 .SH AUTHOR
429
430 Copyright (C) 2002 by James McCann
431 .SH DOCUMENT SOURCE
432 This manual page was generated by the Netpbm tool 'makeman' from HTML
433 source. The master documentation is at
434 .IP
435 .B http://netpbm.sourceforge.net/doc/pbmtextps.html
436 .PP