1Pbmtextps User Manual(0) Pbmtextps User Manual(0)
2
6 pbmtextps - render text into a PBM image using a postscript interpreter
7
10 pbmtextps [-font fontname] [-fontsize float] [-resolution n] [-leftmar‐
11 gin=n] [-rightmargin=n] [-topmargin=n] [-bottommargin=n] [-ascent=n]
12 [-descent=n] [-pad] [-crop] [-stroke n] [-asciihex] [-ascii85] [-ver‐
13 bose] [-dump-ps] text [text ...]
14
17 This program is part of Netpbm(1).
18 pbmtextps takes a single line of text from the command line and renders
20 it into a PBM image. The image is of a single line of text; newline
21 characters in the input have no effect.
22 See pbmtext for a more sophisticated generator of text, but using less
24 common font formats. pbmtext can generate multiple lines of text.
25 The -plain common option ⟨index.html#commonoptions⟩ has no effect be‐
27 fore Netpbm 10.42 (March 2008). The output is always raw PBM.
28 Margins
31 By default, the image is cropped at the top and the right. It is not
32 cropped at the left or bottom so that the text begins at the same posi‐
33 tion relative to the origin. The size of the default left and bottom
34 margins is explained below.
35 You can set whatever margin you want with options -leftmargin, -right‐
37 margin, -topmargin and -bottommargin. The specified amount of white
38 space gets added to the far edge of type, e.g. if you specify 10 points
39 for -topmargin, you will get 10 points of white space above the highest
40 character on the line. Specify 0 to crop a side.
41 -ascent adds white space to the top to reach a specified distance above
43 the text baseline, and -descent adds white space to to the bottom to
44 reach a specified distance below the text baseline.
45 -ascent and -descent are more useful than -topmargin and -bottomargin
47 when you render two pieces of text (in separate invocations of pbm‐
48 textps) that you will concatenate horizontally. With -ascent and -de‐
49 scent, as long as you specify a value greater than the height or detph
50 of every character in the font, the two images will be the same height
51 with the text baseline in the same place. With -topmargin and -bottom‐
52 margin, that may not be the case.
53 Example:
55 $ pbmtextps -font=Times-Roman -descent=20 \
57 'The soup is called' > a1.pbm
58 $ pbmtextps -font=Itallic -descent=20 'Goulash.' > a2.pbm
59 $ pnmcat -leftright -jbottom a1.pbm a2.pbm > out.pbm
60 If you're using -descent to line up the segments of text you are
63 concatenating horizontally with pnmcat, use the -jbottom
64 (justify to bottom) option on pnmcat as in the example above. If you
65 use -ascent, use -jtop instead.
66 Similarly, if you render two lines of text (in separate invocations of
68 pbmtextps) that you will concatenate vertically, -ascent and
69 -descent with sufficiently large values will ensure your baselines
70 are uniformly spaced.
71 If you have -ascent, there is probably no point in specifying -topmar‐
73 gin too, but if you do, the effect is cumulative. The same is true of
74 -descent and -bottommargin.
75 -pad pads the image on the top and bottom to the where the highest and
77 lowest characters in the font would reach, even if you don't have those
78 characters in your text. This is useful if you will generate multiple
79 images of text (with multiple invocations of pbmtextps) and concatenate
80 them vertically to create a multiline text image. -pad makes sure the
81 lines in this image are equally spaced.
82 Example:
84 $ pbmtextps 'cat' | pamfile
86 $ pbmtextps 'Catty' | pamfile
87 The commands above, with no -pad, show that the 'Catty' image is higher
90 because capital C reaches high and 'y' reaches low.
91 $ pbmtextps -pad 'cat' | pamfile
93 $ pbmtextps -pad 'Catty' | pamfile
94 The commands above, with -pad, show that both images are the same
97 height.
98 If you specify -pad with -ascent or -descent, the larger value is ef‐
100 fective.
101 -crop makes the program crop all sides to the far edge of the type. It
103 is the same as -leftmargin=0 -rightmargin=0 -topmargin=0 -bottommar‐
104 gin=0.
105 You cannot specify any other margin-affecting options with -crop.
107 The default top margin, when you specify neither -ascent, -topmargin,
109 nor -pad, is as if you specified topmargin=0.
110 The default bottom margin, when you specify neither -descent, -bottom‐
112 margin, nor -pad, is as if you specified -descent=1.5*fontsize.
113 The default left margin, when you do not specify -leftmargin, is as if
115 you specified -leftmargin=0.5*fontsize.
116 The default right margin, when you do not specify -rightmargin, is as
118 if you specified -rightmargin=0.
119 <h3 id="input_text">Input Text</h2>
122 The simplest way to specify the text to render is just to specify it,
124 in ASCII, as the sole argument of the command. For example,
125 $ pbmtextps 'hello world'
128 But you can also spread it across multiple arguments. pbmtextps
132 concatenates them right to left with a single space in between:
133 $ pbmtextps hello world
136 With an -asciihex option, you can specify the text in Postscript's
140 ASCII-HEX code:
141 $ pbmtextps -asciihex 68656c6c6f20776f726c64
144 You can optionally include the ASCII-HEX text delimiters that would ap‐
148 pear around the text in a Postscript program:
149 $ pbmtextps -asciihex '<68656c6c6f20776f726c64>'
152 Note that the <> delimiters have special meaning to command shells, so
156 if you are invoking pbmtextps via a command shell, be sure to quote
157 them, as is done in this example.
158 With -asciihex, you can include white space anywhere in the coded text;
161 it has no effect. And you can spread the argument across multiple ar‐
162 guments as for plain ASCII input:
163 $ pbmtextps -asciihex '<' 68656c6c6f 20 776f726c64 '>'
166 But note that while Postscript allows an ASCII NUL character as white
170 space, there is no way to pass an argument including a NUL character
171 to
172 pbmtextps.
173 With an -ascii85 option, you can specify the text in Postscript's
176 ASCII-85 code. This is analogous to -asciihex. The Postscript delim‐
177 iters for an ASCII-85 text string are <~ ~>.
178
182 In addition to the options common to all programs based on libnetpbm
183 (most notably -quiet, see
184 Common Options ⟨index.html#commonoptions⟩ ), pbmtextps recognizes the
185 following command line options:
186 -font=fontname
190 This specifies the font to use. fontname is the name of any
192 valid Postscript font which is installed on the system.
193 The default is TimesRoman.
195 Here is a way to get a list of the names of all the available
197 fonts:
198 $ gs -c '(*) {==} 256 string /Font resourceforall'
200 Warning: if fontname does not name a valid font, pbmtextps just
203 uses the default font. It does not tell you it is doing this.
204 -fontsize=float
207 This is the size of the font in points. See the -resolution op‐
208 tion for information on how to interpret this size.
209 The default is 24 points.
211 Before Netpbm 10.75 (June 2016), this has to be a whole number.
213 -resolution=n
216 This is the resolution in dots per inch of distance measurements
217 pertaining to generation of the image. PBM images don't have
218 any inherent resolution, so a distance such as "1 inch" doesn't
219 mean anything unless you separately specify what resolution
220 you're talking about. That's what this option does.
221 In particular, the meaning of the font size is determined by
223 this resolution. If the font size is 24 points and the resolu‐
224 tion is 150 dpi, then the font size is 50 pixels.
225 The default is 150 dpi.
227 -leftmargin=n
230 -rightmargin=n
232 -topmargin=n
234 -bottommargin=n
236 These options control the margins added to the image, measured
237 from the far edge of the type. See Margins ⟨#margins⟩ for de‐
238 tails.
239 All sizes are in points, as a floating point number.
241 These options were new in Netpbm 10.75 (June 2016).
243 -ascent=n
246 -descent=n
248 These options control the margins added to the image, measured
249 from the text baseline. See Margins ⟨#margins⟩ for details.
250 Sizes are in points, as a floating point number.
252 These options were new in Netpbm 10.75 (June 2016).
254 -pad This pads the image on the top and bottom to the where the high‐
257 est and lowest characters in the font would reach, even if you
258 don't have those characters in your text. See Margins
259 ⟨#margins⟩ for details.
260 This option was new in Netpbm 10.75 (June 2016).
262 -crop This makes the program crop all sides to the far edge of the
265 type. It is the same as -leftmargin=0 -rightmargin=0 -topmar‐
266 gin=0 -bottommargin=0. See Margins ⟨#margins⟩ for details.
267 This option was new in Netpbm 10.75 (June 2016).
269 -asciihex
272 This means the text in the arguments is in Postscript ASCII-HEX
273 code. See Input Text ⟨#input_text⟩ .
274 You cannot specify this together with -ascii85.
276 This option was new in Netpbm 11.02 (March 2023)
278 -ascii85
281 This means the text in the arguments is in Postscript ASCII-85
282 code. See Input Text ⟨#input_text⟩ .
283 You cannot specify this together with -asciihex.
285 This option was new in Netpbm 11.02 (March 2023)
287 -stroke=n
290 This is the width of line, in points, to use for stroke font.
291 There is no default stroke width because the characters are
292 solid by default.
293 -verbose
296 This option makes pbmtextps display extra information on Stan‐
297 dard Error about its processing.
298 -dump-ps
301 This option makes pbmtextps write to Standard Output the Post‐
302 script program it would use to create the image, rather than the
303 image itself. You can use this as input to a Postscript inter‐
304 preter (such as Ghostscript or a printer) or to understand the
305 program better.
306 This option was new in Netpbm 10.75 (June 2016).
308
313 You can generate antialiased text by using a larger resolution than the
314 default and scaling the image down using pamscale.
315 See the manual for the similar pbmtext for more advice on usage.
317
320 pbmtextps was added to Netpbm in Release 10.0 (June 2002).
321
325 pbmtext(1), pamcut(1), pnmcrop(1), pamcomp(1), ppmchange(1), pnmro‐
326 tate(1), pamscale(1), ppmlabel(1), pbm(1)
327
330 Copyright (C) 2002 by James McCann
331
333 This manual page was generated by the Netpbm tool 'makeman' from HTML
334 source. The master documentation is at
335 http://netpbm.sourceforge.net/doc/pbmtextps.html
337netpbm documentation 17 February 2023 Pbmtextps User Manual(0)