Debian Codegraph @

upstream/debian-unstable/man1/pbmtext.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 "Pbmtext User Manual" 1 "29 May 2020" "netpbm documentation"
7
8 .SH NAME
9 pbmtext - render text into a PBM image
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBpbmtext\fP
15 [\fB-wchar\fP]
16 [\fB-font\fP \fIfontfile\fP]
17 [\fB-builtin\fP \fIfontname\fP]
18 [\fB-space\fP \fIpixels\fP]
19 [\fB-lspace\fP \fIpixels\fP]
20 [\fB-nomargins\fP]
21 [\fB-width\fP \fIpixels\fP]
22 [\fB-load-entire-font\fP]
23 [\fB-verbose\fP]
24 [\fB-dry-run\fP]
25 [\fB-text-dump\fP]
26 [\fItext\fP]
27 .PP
28 Minimum unique abbreviation of option is acceptable. You may use double
29 hyphens instead of single hyphen to denote options. You may use white
30 space in place of the equals sign to separate an option name from its value.
31
32
33 .UN description
34 .SH DESCRIPTION
35 .PP
36 This program is part of
37 .BR "Netpbm" (1)\c
38 \&.
39 .PP
40 \fBpbmtext\fP takes the specified text, either a single line from
41 the command line or multiple lines from standard input, and renders it
42 into a PBM graphical image.
43 .PP
44 The text rendered is all the non-option command line arguments, separated
45 by spaces, except that if there are no non-option command line arguments, it
46 is Standard Input.
47
48 .PP
49 In the image, each line of input is a line of output. Lines are
50 delimited by newline characters.
51 .PP
52 The program renders any character in an input line that is not in the font
53 as a space. Note that control characters usually aren't in the font, but
54 some fonts have glyphs for them. The newline characters that delimit lines
55 in of Standard Input are not in any line.
56 .PP
57 Tab characters are rendered as a number of spaces; any entry in the font
58 for the tab code point is irrelevant. The number of spaces is such as to
59 create tab stops every 8 characters. Note that this is not useful if the
60 font is proportional.
61
62 .PP
63 The image is just wide enough for the longest line of text, plus
64 margins, and just high enough to contain the lines of text, plus
65 margins.
66 .PP
67 The left and right margins are twice the width of the widest
68 character in the font; the top and bottom margins are the height of
69 the tallest character in the font. But if the text is only one line,
70 all the margins are half of this. You can use the \fB-nomargins\fP option
71 to eliminate the margins.
72 .PP
73 \fBpbmtext\fP renders left to right. It cannot render vertically
74 or right to left.
75 .PP
76 \fBpbmtextps\fP does the same thing as \fBpbmtext\fP, but uses
77 Ghostscript to generate the characters, which means you can use
78 Postscript fonts. But it also means you have to have Ghostscript
79 installed and it isn't as fast. Also, \fBpbmtextps\fP generates only
80 one line of text, whereas \fBpbmtext\fP can create multiple lines.
81 .PP
82 \fBpbmtext\fP is meant for simple text. If you're working with
83 a \fIdocument\fP, you would be better off using a document formatting
84 program to "print" to a Postscript file, then feeding that Postscript
85 to \fBpstopnm\fP.
86
87 .UN options
88 .SH OPTIONS
89 .PP
90 In addition to the options common to all programs based on libnetpbm
91 (most notably \fB-quiet\fP, see
92 .UR index.html#commonoptions
93 Common Options
94 .UE
95 \&), \fBpbmtext\fP recognizes the following
96 command line options:
97
98
99
100 .TP
101 \fB-wchar\fP
102 .sp
103 By default, \fBpbmtext\fP takes a single-byte character stream as input.
104 When you specify \fB-wchar\fP, it treats input text as a multibyte character
105 stream encoded according to the current locale. Normally, the user would
106 supply a BDF font file encoded in ISO-10646-1 with a \fB-font\fP option.
107 .sp
108 With \fB-wchar\fP, you cannot supply the text on the command line; it must
109 be fed from standard input.
110 .sp
111 This option was new in Netpbm 10.82 (March 2018).
112
113
114 .TP
115 \fB-font\fP
116 .TP
117 \fB-builtin\fP
118 \fB-builtin\fP selects a font among those built into Netpbm.
119
120 \fB-font\fP selects a font that you supply yourself either as an X Window
121 System BDF (Bitmap Distribution Format) file or as a PBM file in a special
122 form.
123 .sp
124 The default is the built in font "bdf."
125 .sp
126 "bdf" is Times-Roman 15 pixels high. (That's about 14
127 point type printed at 75 dpi).
128 .sp
129 "fixed" is a built in fixed width font.
130 .sp
131 For information about other fonts, and how to make one of your own,
132 see
133 .UR #fonts
134 Fonts
135 .UE
136 \& below.
137
138
139 .TP
140 \fB-space\fP \fIpixels\fP
141 Add \fIpixels\fP pixels of space between characters. This is in
142 addition to whatever space surrounding characters is built into the
143 font, which is usually enough to produce a reasonable string of text.
144 .sp
145 \fIpixels\fP may be fractional, in which case the number of
146 pixels added varies so as to achieve the specified average. For
147 example \fB-space=1.5\fP causes half the spaces to be 1 pixel and
148 half to be 2 pixels.
149 .sp
150 \fIpixels\fP may be negative to crowd text together, but the
151 author has not put much thought or testing into how this works in
152 every possible case, so it might cause disastrous results.
153
154 .TP
155 \fB-lspace\fP \fIpixels\fP
156 Add \fIpixels\fP pixels of space between lines. This is in
157 addition to whatever space above and below characters is built into
158 the font, which is usually enough to produce a reasonable line
159 spacing.
160 .sp
161 \fIpixels\fP must be a whole number.
162 .sp
163 \fIpixels\fP may be negative to crowd lines together, but the
164 author has not put much thought or testing into how this works in
165 every possible case, so it might cause disastrous results.
166
167 .TP
168 \fB-nomargins\fP
169 By default, \fBpbmtext\fP adds margins all around the image as
170 described above. This option causes \fBpbmtext\fP not to add any
171 margins.
172 .sp
173 Note that there may still be space beyond the edges of the type
174 because a character itself may include space at its edges. To eliminate
175 all surrounding background, so the type touches all four edges of the
176 image, use \fBpnmcrop\fP.
177
178 .TP
179 \fB-width\fP \fIpixels\fP
180 This specifies how much horizontal space the text is supposed to fit
181 into.
182 .sp
183 If the input is one line, \fBpbmtext\fP breaks it into multiple
184 lines as needed to fit the specified width. It breaks it between
185 characters, but does not pay attention to white space; it may break in
186 the middle of a word and a line may begin or end with white space.
187 .sp
188 If the input is multiple lines, \fBpbmtext\fP assumes you already
189 have line breaks where they make sense, and \fBpbmtext\fP simply
190 truncates each line as needed to fit the specified width.
191
192 .TP
193 \fB-load-entire-font\fP
194
195 When you use a BDF font, \fBpbmtext\fP will normally load from the font
196 only the characters needed for your text, not wasting time loading other
197 characters. With this option, \fBpbmtext\fP will instead read the entire
198 font. It won't make any difference in the rendered output, but it lets
199 you check the integrity of the font file.
200 .sp
201 This option was new in Netpbm 10.91 (June 2020). Before that,
202 \fBpbmtext\fP always reads the entire font.
203
204 .TP
205 \fB-verbose\fP
206 This makes \fBpbmtext\fP issue informtional messages about its processing.
207
208 .TP
209 \fB-dry-run\fP
210 .sp
211 With this option, instead of outputting an image of the text,
212 \fBpbmtext\fP just writes to Standard Output a message telling the dimensions
213 of the image it would have produced.
214 .sp
215 You can specify only one of \fB-dry-run\fP and \fB-text-dump\fP.
216 .sp
217 This option was new in Netpbm 10.75 (June 2016).
218
219 .TP
220 \fB-text-dump\fP
221 This option causes \fBpbmtext\fP just to write to Standard Output the text in
222 ASCII that would be rendered. The output reflects any text formatting,
223 unprintable character substitution, tab expansion, etc. It is for diagnosing
224 problems. This option was new in Netpbm 10.82 (March 2018).
225 .sp
226 When \fB-wchar\fP is in effect, the output text will be in the encoding
227 specified by the current locale.
228 .sp
229 You can specify only one of \fB-dry-run\fP and \fB-text-dump\fP.
230 .sp
231 This option was new in Netpbm 10.82 (March 2018).
232
233
234
235
236 .UN usage
237 .SH USAGE
238 .PP
239 Often, you want to place text over another image. One way to do this is
240 with \fBppmlabel\fP. For more flexible (but complex) drawing of text on an
241 image, there is \fBppmdraw\fP. These do not give you the font options that
242 \fBpbmtext\fP does, though.
243 .PP
244 Another way is to use \fBpbmtext\fP to create an image containing
245 the text, then use \fBpamcomp\fP to overlay the text image onto your
246 base image. To make only the text (and not the entire rectangle
247 containing it) cover the base image, you will need to give
248 \fBpamcomp\fP a mask, via its \fB-alpha\fP option. You can just use
249 the text image itself as the mask, as long as you also specify the
250 \fB-invert\fP option to \fBpamcomp\fP.
251 .PP
252 If you want to overlay colored text instead of black, just use
253 \fBppmchange\fP to change all black pixels to the color of your
254 choice before overlaying the text image. But still use the original
255 black and white image for the transparency mask.
256 .PP
257 If you want the text at an angle, use \fBpnmrotate\fP on the text
258 image (and transparency mask) before overlaying.
259
260 .UN fonts
261 .SH FONTS
262 .PP
263 There are three kinds of fonts you an use with \fBpbmtext\fP:
264
265
266 .IP \(bu
267 built in
268 .IP \(bu
269 BDF
270 .IP \(bu
271 PBM
272
273
274 .SS Built In Fonts
275 .PP
276 There are two built in fonts: \fBbdf\fP and \fBfixed\fP. You select
277 these fonts with a \fB-builtin\fP option.
278 .PP
279 \fBbdf\fP is the default when you specify no font information on the
280 command line. \fIThe naming reflects the fact that it shares many
281 characteristics of BDF style fonts. When this font was implemented,
282 \fBpbmtext\fP did not have the ability to read arbitrary BDF fonts
283 specified by the \fB-font\fP option. There is no external font file
284 involved.\fP
285 .PP
286 \fBbdf\fP is encoded in ISO 8859-1 (Latin 1, 8-bit). In addition to
287 English it can handle most West European languages (Spanish, French, German,
288 Swedish ...) This set lacks the Euro currency sign.
289 .PP
290 \fBfixed\fP is ASCII (7-bit) only.
291 .PP
292 While it is not an error to do so, you should not use the above built-in
293 fonts with \fB-wchar\fP.
294
295
296 .SS BDF Font
297 .PP
298 BDF is an ancient font format that at one time was standard for the X
299 Window System. Now, you don't see it very often. Until about 2024, you could
300 find some BDF fonts on the Xfree86 web site. Today, you can get the full
301 package of the BDF fonts from XFree86 from
302 the
303 .UR http://netpbm.sourceforge.net/bdffont.tgz
304 Netpbm web site
305 .UE
306 \&.
307
308 .SS PBM Font
309 .PP
310 To create a font as a PBM file (to use with the \fB-font\fP
311 option), you just create a PBM image of the text matrix below.
312 .PP
313 The first step is to display text matrix below on the screen,
314 e.g. in an X11 window.
315
316 .nf
317
318 M ",/^_[`jpqy| M
319
320 / !"#$%&'()*+ /
321 < ,-./01234567 <
322 > 89:;<=>?@ABC >
323 @ DEFGHIJKLMNO @
324 _ PQRSTUVWXYZ[ _
325 { \e]^_`abcdefg {
326 } hijklmnopqrs }
327 ~ tuvwxyz{|}~ ~
328
329 M ",/^_[`jpqy| M
330
331
332 .fi
333 .PP
334 Make sure it's a fixed width font -- This should display as a
335 perfect rectangle.
336 .PP
337 Also, try to use a simple display program. Pbmtext divides this
338 into a matrix of cells, all the same size, each containing one
339 character, so it is important that whatever you use to display it
340 display with uniform horizontal and vertical spacing. Fancy word
341 processing programs sometimes stretch characters in both directions to
342 fit certain dimensions, and that won't work. Sometimes a display
343 program scales a font to show a character larger or smaller than its
344 natural size. That too won't often work because the rounding involved
345 in such scaling causes non-uniform distances between characters.
346 .PP
347 If you display the text matrix improperly, the usual symptom is
348 that when you try to use the font, \fBpbmtext\fP fails with an error
349 message telling you that the number of lines in the font isn't
350 divisible by 11, or it can't find the blank band around the inner
351 rectangle. Sometimes the symptom is that one of the characters
352 displays with a piece of the character that is next to it in the
353 matrix. For example, "l" might display with a little piece
354 of the "m" attached on its right.
355 .PP
356 Do a screen grab or window dump of that text, using for instance
357 \fBxwd\fP, \fBxgrabsc\fP, or \fBscreendump\fP. Convert the result into a
358 pbm file. If necessary, use \fBpamcut\fP to remove anything you grabbed in
359 addition to the text pictured above (or be a wimp and use a graphical editor
360 such as Gimp). Finally, run it through \fBpnmcrop\fP to make sure the edges
361 are right up against the text. \fBpbmtext\fP can figure out the sizes and
362 spacings from that.
363 .PP
364 There are some historical computer fonts, such as that used by the original
365 IBM PC, in the form that you can screen-grab and turn into a PBM font file
366 available from
367 .BR "Stewart
368 C Russell" (1)\c
369 \&. There are fonts with various duodecimal digit glyphs at
370 .UR http://treisaran.deviantart.com/gallery/38695571/NetPBM-Fonts
371 treisara.deviantart.com
372 .UE
373 \&.
374 .PP
375 PBM fonts cannot be used with \fB-wchar\fP.
376
377
378
379 .UN multibyte
380 .SH MULTI-BYTE INPUT
381 .PP
382 In the past, English text was encoded in 7-bit ASCII. 8-bit and multibyte
383 encodings were needed only for non-English languages. This is not the case
384 today. As of this writing, 90% of all web pages are encoded in UTF-8. While
385 many of them are actually restricted to 7-bit ASCII, which is a subset of
386 UTF-8, English text encoded in UTF-8 commonly employs "66 99" style quotation
387 marks, which do not appear in ASCII.
388 .PP
389 If your input text is UTF-8, you should use \fB-wchar\fP. You may have to
390 tweak the locale setting. \fBpbmtext\fP recognizes code points up to 65535.
391 This is sufficient for the vast majority of text written in modern languages.
392 .PP
393 In the default single-byte (or "narrow") character
394 mode, \fBpbmtext\fP can handle 7-bit and 8-bit character sets.
395 Examples are ASCII, ISO 8859 family, koi8-r/u and VISCII. It is up to
396 the user to supply a BDF file covering the necessary glyphs with the
397 "-font" option. The font file must be in the right encoding.
398 .PP
399 \fBpbmtext\fP does not inspect the encoding of the font file.
400
401
402 .UN limitations
403 .SH LIMITATIONS
404 .PP
405 If the text is from Standard Input, no line may be longer than 4999
406 characters. If one is, the program aborts with an appropriate error message.
407 .PP
408 If the text is from Standard Input and contains a null character, the
409 results are abnormal. Lines may be truncated, and a single line may be
410 considered multiple lines. Normal text does not contain null characters, so
411 this isn't a big problem.
412
413
414 .UN tips
415 .SH TIPS
416 .PP
417 If you get garbled output, check the input text encoding and font file
418 encoding. When using \fB-wchar\fP, also check the current locale.
419 .PP
420 To convert the encoding of a text file, use \fBiconv\fP or \fBluit\fP.
421 .PP
422 To check the encoding of a BDF file, examine the CHARSET_REGISTRY
423 line and the next line, which should be CHARSET_ENCODING:
424
425 .nf
426 \f(CW
427 $ grep -A1 CHARSET_REGISTRY font-a.bdf
428 CHARSET_REGISTRY "ISO8859"
429 CHARSET_ENCODING "1"
430
431 $ grep -A1 CHARSET_REGISTRY font-b.bdf
432 CHARSET_REGISTRY "ISO10646"
433 CHARSET_ENCODING "1"
434 \fP
435
436 .fi
437 .PP
438 The latter is Unicode. BDF files coded in ISO 16046-1 usually work for
439 Western European languages, because ISO 16046-1 expands ISO 8859-1 (also
440 called "Latin-1") while maintaining the first 256 code points. ISO
441 8859-1 itself is a superset of ASCII. Run the above command and verify the
442 necessary glyphs are present.
443 .PP
444 \fBIMPORTANT:\fP For input text, a different rule applies. If
445 you feed ISO 8859-1 text to \fBpbmtext -wchar\fP set up for UTF-8, the output
446 will be garbled. Unicode provides several encoding schemes and different ones
447 are in effect for input text and font. \fIThe difference between Unicode
448 codepoint and the various encodings is a formidable stumbling block; beware of
449 web pages that get the concept wrong.\fP
450 .PP
451 75% of the BDF files in the font collection available from
452 .UR http://netpbm.sourceforge.net/bdffont.tgz
453 the Netpbm website
454 .UE
455 \& are
456 in ISO 10646-1. Many have the Euro sign, Greek letters, etc., but they are
457 placed at code points available to \fBpbmtext\fP only with \fB-wchar\fP.
458 .PP
459 Before \fBpbmtext\fP had the \fB-wchar\fP option, one often had to
460 produce a BDF file in an 8-bit encoding from a master BDF file encoded in ISO
461 10646-1.
462 .PP
463 There are several programs that perform BDF encoding conversion. If you
464 have the X Window System installed, first look for \fBucs2any\fP. If you
465 don't, you can download \fBucs2any.pl\fP from
466 .BR "Unicode fonts and tools
467 for X11" (1)\c
468 \&. This website has much useful information on fonts.
469 .PP
470 Another converter is \fBtrbdf\fP, included in the "trscripts"
471 package, available in some GNU/Linux distributions.
472 .PP
473 BDF files encoded in ISO 8859-2, ISO 8859-7, koi8-r, etc. are available
474 from
475 .BR "ISO 8859 Alphabet
476 Soup" (1)\c
477 \& and its sister page
478 .BR "The Cyrillic Charset
479 Soup" (1)\c
480 \&. Though the information is dated, these pages give a good overview
481 of 8-bit character sets.
482 .PP
483 To convert OTF or TTF font files to BDF, use
484 \fBotf2bdf\fP by Mike Leisher or \fBotftobdf\fP (part of the \fBlibotf\fP
485 package, which is part of the
486 .UR https://www.nongnu.org/m17n/
487 \fBm17n\fP
488 .UE
489 \& project).
490
491
492 .UN seealso
493 .SH SEE ALSO
494 .BR "pbmtextps" (1)\c
495 \&,
496 .BR "pamcut" (1)\c
497 \&,
498 .BR "pnmcrop" (1)\c
499 \&,
500 .BR "pamcomp" (1)\c
501 \&,
502 .BR "ppmchange" (1)\c
503 \&,
504 .BR "pnmrotate" (1)\c
505 \&,
506 .BR "ppmlabel" (1)\c
507 \&,
508 .BR "ppmdraw" (1)\c
509 \&,
510 .BR "pstopnm" (1)\c
511 \&,
512 .BR "pbm" (1)\c
513 \&,
514 \fB
515 .UR http://www.pango.org
516 Pango
517 .UE
518 \&\fP,
519 \fB
520 .UR http://cairographics.org
521 Cairo
522 .UE
523 \&\fP
524
525 .UN author
526 .SH AUTHOR
527
528 Copyright (C) 1993 by Jef Poskanzer and George Phillips
529 .SH DOCUMENT SOURCE
530 This manual page was generated by the Netpbm tool 'makeman' from HTML
531 source. The master documentation is at
532 .IP
533 .B http://netpbm.sourceforge.net/doc/pbmtext.html
534 .PP