1Pbmtext User Manual(0)                                  Pbmtext User Manual(0)
2
3
4

NAME

6       pbmtext - render text into a PBM image
7
8

SYNOPSIS

10       pbmtext  [-wchar]  [-font fontfile] [-builtin fontname] [-space pixels]
11       [-lspace  pixels]  [-nomargins]  [-width  pixels]   [-load-entire-font]
12       [-verbose] [-dry-run] [-text-dump] [text]
13
14       Minimum  unique abbreviation of option is acceptable.  You may use dou‐
15       ble hyphens instead of single hyphen to denote options.   You  may  use
16       white space in place of the equals sign to separate an option name from
17       its value.
18
19
20

DESCRIPTION

22       This program is part of Netpbm(1).
23
24       pbmtext takes the specified text, either a single line from the command
25       line  or  multiple lines from standard input, and renders it into a PBM
26       graphical image.
27
28       The text rendered is all the non-option command line  arguments,  sepa‐
29       rated  by  spaces,  except that if there are no non-option command line
30       arguments, it is Standard Input.
31
32
33       In the image, each line of input is a line of output.  Lines are
34         delimited by newline characters.
35
36       The program renders any character in an input line that is not  in  the
37       font
38         as a space.  Note that control characters usually aren't in the font,
39       but
40         some fonts have glyphs for them.  The newline characters that delimit
41       lines
42         in of Standard Input are not in any line.
43
44       Tab  characters  are  rendered  as a number of spaces; any entry in the
45       font
46         for the tab code point is irrelevant.  The number of spaces  is  such
47       as to
48         create tab stops every 8 characters.  Note that this is not useful if
49       the
50         font is proportional.
51
52
53       The image is just wide enough for the longest line of text,  plus  mar‐
54       gins, and just high enough to contain the lines of text, plus margins.
55
56       The  left and right margins are twice the width of the widest character
57       in the font; the top and bottom margins are the height of  the  tallest
58       character  in the font.  But if the text is only one line, all the mar‐
59       gins are half of this.  You can use the -nomargins option to  eliminate
60       the margins.
61
62       pbmtext renders left to right.  It cannot render vertically or right to
63       left.
64
65       pbmtextps does the same thing as pbmtext, but uses Ghostscript to  gen‐
66       erate the characters, which means you can use Postscript fonts.  But it
67       also means you have to have Ghostscript installed and it isn't as fast.
68       Also,  pbmtextps  generates  only one line of text, whereas pbmtext can
69       create multiple lines.
70
71       pbmtext is meant for simple text.  If you're working with  a  document,
72       you  would be better off using a document formatting program to "print"
73       to a Postscript file, then feeding that Postscript to pstopnm.
74
75

OPTIONS

77       In addition to the options common to all programs  based  on  libnetpbm
78       (most notably -quiet, see
79        Common  Options  ⟨index.html#commonoptions⟩  ), pbmtext recognizes the
80       following command line options:
81
82
83
84
85       -wchar
86
87              By default, pbmtext takes a single-byte character stream as  in‐
88              put.   When you specify -wchar, it treats input text as a multi‐
89              byte character stream encoded according to the  current  locale.
90              Normally,  the  user  would  supply  a  BDF font file encoded in
91              ISO-10646-1 with a -font option.
92
93              With -wchar, you cannot supply the text on the command line;  it
94              must be fed from standard input.
95
96              This option was new in Netpbm 10.82 (March 2018).
97
98
99
100       -font
101
102       -builtin
103              -builtin selects a font among those built into Netpbm.
104
105              -font  selects  a  font  that you supply yourself either as an X
106              Window    System    BDF     (Bitmap     Distribution     Format)
107http://xfree86.org/current/bdf.pdf⟩  file or as a PBM file in a
108              special form.
109
110              The default is the built in font "bdf."
111
112              "bdf" is Times-Roman 15 pixels high.   (That's  about  14  point
113              type printed at 75 dpi).
114
115              "fixed" is a built in fixed width font.
116
117              For  information  about other fonts, and how to make one of your
118              own, see Fonts ⟨#fonts⟩  below.
119
120
121
122       -space pixels
123               Add pixels pixels of space between characters.  This is in  ad‐
124              dition  to  whatever  space surrounding characters is built into
125              the font, which is usually enough to produce a reasonable string
126              of text.
127
128              pixels  may  be  fractional,  in which case the number of pixels
129              added varies so as to achieve the specified average.  For  exam‐
130              ple  -space=1.5 causes half the spaces to be 1 pixel and half to
131              be 2 pixels.
132
133              pixels may be negative to crowd text together,  but  the  author
134              has not put much thought or testing into how this works in every
135              possible case, so it might cause disastrous results.
136
137
138       -lspace pixels
139               Add pixels pixels of space between lines.  This is in  addition
140              to  whatever  space above and below characters is built into the
141              font, which is usually enough to produce a reasonable line spac‐
142              ing.
143
144              pixels must be a whole number.
145
146              pixels  may  be negative to crowd lines together, but the author
147              has not put much thought or testing into how this works in every
148              possible case, so it might cause disastrous results.
149
150
151       -nomargins
152              By  default,  pbmtext  adds  margins all around the image as de‐
153              scribed above.  This option causes pbmtext not to add  any  mar‐
154              gins.
155
156              Note  that there may still be space beyond the edges of the type
157              because a character itself may include space at its  edges.   To
158              eliminate  all  surrounding  background, so the type touches all
159              four edges of the image, use pnmcrop.
160
161
162       -width pixels
163              This specifies how much horizontal space the text is supposed to
164              fit into.
165
166              If  the input is one line, pbmtext breaks it into multiple lines
167              as needed to fit the specified  width.   It  breaks  it  between
168              characters,  but  does  not pay attention to white space; it may
169              break in the middle of a word and a line may begin or  end  with
170              white space.
171
172              If the input is multiple lines, pbmtext assumes you already have
173              line breaks where they make sense, and pbmtext simply  truncates
174              each line as needed to fit the specified width.
175
176
177       -load-entire-font
178
179              When  you  use  a  BDF font, pbmtext will normally load from the
180              font
181                  only the characters needed for your text, not  wasting  time
182              loading other
183                  characters.  With this option, pbmtext will instead read the
184              entire
185                  font.  It won't make any difference in the rendered  output,
186              but it lets
187                  you check the integrity of the font file.
188
189              This  option  was new in Netpbm 10.91 (June 2020).  Before that,
190              pbmtext always reads the entire font.
191
192
193       -verbose
194              This makes pbmtext issue informtional messages  about  its  pro‐
195              cessing.
196
197
198       -dry-run
199
200              With  this  option,  instead of outputting an image of the text,
201              pbmtext just writes to Standard Output a message telling the di‐
202              mensions of the image it would have produced.
203
204              You can specify only one of -dry-run and -text-dump.
205
206              This option was new in Netpbm 10.75 (June 2016).
207
208
209       -text-dump
210              This  option causes pbmtext just to write to Standard Output the
211              text in ASCII that would be rendered.  The output  reflects  any
212              text  formatting, unprintable character substitution, tab expan‐
213              sion, etc.  It is for diagnosing problems.  This option was  new
214              in Netpbm 10.82 (March 2018).
215
216              When  -wchar is in effect, the output text will be in the encod‐
217              ing specified by the current locale.
218
219              You can specify only one of -dry-run and -text-dump.
220
221              This option was new in Netpbm 10.82 (March 2018).
222
223
224
225
226

USAGE

228       Often, you want to place text over another image.  One way to  do  this
229       is  with  ppmlabel.  For more flexible (but complex) drawing of text on
230       an image, there is ppmdraw.  These do not give  you  the  font  options
231       that pbmtext does, though.
232
233       Another  way  is to use pbmtext to create an image containing the text,
234       then use pamcomp to overlay the text image onto your  base  image.   To
235       make  only  the text (and not the entire rectangle containing it) cover
236       the base image, you will need to give pamcomp a mask,  via  its  -alpha
237       option.  You can just use the text image itself as the mask, as long as
238       you also specify the -invert option to pamcomp.
239
240       If you want to overlay colored text instead of  black,  just  use  ppm‐
241       change  to  change  all black pixels to the color of your choice before
242       overlaying the text image.  But still use the original black and  white
243       image for the transparency mask.
244
245       If  you want the text at an angle, use pnmrotate on the text image (and
246       transparency mask) before overlaying.
247
248

FONTS

250       There are three kinds of fonts you an use with pbmtext:
251
252
253
254       •      built in
255
256       •      BDF
257
258       •      PBM
259
260
261
262   Built In Fonts
263       There are two built in fonts: bdf and fixed.  You  select  these  fonts
264       with a -builtin option.
265
266       bdf  is the default when you specify no font information on the command
267       line.  The naming reflects the fact that it shares many characteristics
268       of  BDF  style  fonts.  When this font was implemented, pbmtext did not
269       have the ability to read arbitrary BDF fonts specified by the -font op‐
270       tion.  There is no external font file involved.
271
272       bdf  is encoded in ISO 8859-1 (Latin 1, 8-bit).  In addition to English
273       it can handle most West European languages  (Spanish,  French,  German,
274       Swedish ...)  This set lacks the Euro currency sign.
275
276       fixed is ASCII (7-bit) only.
277
278       While  it is not an error to do so, you should not use the above built-
279       in fonts with -wchar.
280
281
282
283   BDF Font
284       BDF is an ancient font format that at one time was standard for  the  X
285       Window System.  Now, you don't see it very often, but you can find some
286       BDF            fonts             on             the             Xfree86
287http://cvsweb.xfree86.org/cvsweb/xc/fonts/bdf/⟩  web site.
288
289       You  can get the full package of the BDF fonts from XFree86 (see above)
290       from the Netpbm web site ⟨http://netpbm.sourceforge.net/bdffont.tgz⟩ .
291
292
293   PBM Font
294       To create a font as a PBM file (to use with the -font option), you just
295       create a PBM image of the text matrix below.
296
297       The  first  step is to display text matrix below on the screen, e.g. in
298       an X11 window.
299
300
301           M ",/^_[`jpqy| M
302
303           /  !"#$%&'()*+ /
304           < ,-./01234567 <
305           > 89:;<=>?@ABC >
306           @ DEFGHIJKLMNO @
307           _ PQRSTUVWXYZ[ _
308           { \]^_`abcdefg {
309           } hijklmnopqrs }
310           ~ tuvwxyz{|}~  ~
311
312           M ",/^_[`jpqy| M
313
314
315
316       Make sure it's a fixed width font -- This should display as  a  perfect
317       rectangle.
318
319       Also, try to use a simple display program.  Pbmtext divides this into a
320       matrix of cells, all the same size, each containing one  character,  so
321       it  is  important that whatever you use to display it display with uni‐
322       form horizontal and vertical spacing.  Fancy word  processing  programs
323       sometimes  stretch  characters in both directions to fit certain dimen‐
324       sions, and that won't work.  Sometimes a display program scales a  font
325       to  show a character larger or smaller than its natural size.  That too
326       won't often work because the rounding involved in such  scaling  causes
327       non-uniform distances between characters.
328
329       If  you  display  the text matrix improperly, the usual symptom is that
330       when you try to use the font,  pbmtext  fails  with  an  error  message
331       telling you that the number of lines in the font isn't divisible by 11,
332       or it can't find the blank band around the inner rectangle.   Sometimes
333       the  symptom is that one of the characters displays with a piece of the
334       character that is next to it in the matrix.   For  example,  "l"  might
335       display with a little piece of the "m" attached on its right.
336
337       Do  a  screen grab or window dump of that text, using for instance xwd,
338       xgrabsc, or screendump.  Convert the result into a pbm file.  If neces‐
339       sary, use pamcut to remove anything you grabbed in addition to the text
340       pictured above (or be a wimp and use a graphical editor such as  Gimp).
341       Finally,  run  it  through  pnmcrop to make sure the edges are right up
342       against the text.  pbmtext can figure out the sizes and  spacings  from
343       that.
344
345       There  are  some  historical  computer  fonts, such as that used by the
346       original IBM PC, in the form that you can screen-grab and turn  into  a
347       PBM  font  file available from Stewart C Russell" (1).  There are fonts
348       with various duodecimal digit glyphs at
349        treisara.deviantart.com
350http://treisaran.deviantart.com/gallery/38695571/NetPBM-Fonts⟩ .
351
352       PBM fonts cannot be used with -wchar.
353
354
355
356

MULTI-BYTE INPUT

358       In the past, English text was encoded in 7-bit ASCII.  8-bit and multi‐
359       byte encodings were needed only for non-English languages.  This is not
360       the  case  today.  As of this writing, 90% of all web pages are encoded
361       in UTF-8.  While many of them are actually restricted to  7-bit  ASCII,
362       which  is a subset of UTF-8, English text encoded in UTF-8 commonly em‐
363       ploys "66 99" style quotation marks, which do not appear in ASCII.
364
365       If your input text is UTF-8, you should use -wchar.  You  may  have  to
366       tweak  the locale setting.  pbmtext recognizes code points up to 65535.
367       This is sufficient for the vast majority of text written in modern lan‐
368       guages.
369
370       In  the  default  single-byte (or "narrow") character mode, pbmtext can
371       handle 7-bit and 8-bit character sets.  Examples are  ASCII,  ISO  8859
372       family, koi8-r/u and VISCII.  It is up to the user to supply a BDF file
373       covering the necessary glyphs with the "-font" option.  The  font  file
374       must be in the right encoding.
375
376       pbmtext does not inspect the encoding of the font file.
377
378
379

LIMITATIONS

381       If  the  text  is  from Standard Input, no line may be longer than 4999
382       characters.  If one is, the program aborts with  an  appropriate  error
383       message.
384
385       If  the  text is from Standard Input and contains a null character, the
386       results are abnormal.  Lines may be truncated, and a single line may be
387       considered  multiple  lines.  Normal text does not contain null charac‐
388       ters, so this isn't a big problem.
389
390
391

TIPS

393       If you get garbled output, check the input text encoding and font  file
394       encoding.  When using -wchar, also check the current locale.
395
396       To convert the encoding of a text file, use iconv or luit.
397
398       To  check the encoding of a BDF file, examine the CHARSET_REGISTRY line
399       and the next line, which should be CHARSET_ENCODING:
400
401           $ grep -A1 CHARSET_REGISTRY font-a.bdf
402           CHARSET_REGISTRY "ISO8859"
403           CHARSET_ENCODING "1"
404
405           $ grep -A1 CHARSET_REGISTRY font-b.bdf
406           CHARSET_REGISTRY "ISO10646"
407           CHARSET_ENCODING "1"
408
409
410       The latter is Unicode.  BDF files coded in ISO 16046-1 usually work for
411       Western  European  languages,  because  ISO  16046-1 expands ISO 8859-1
412       (also called "Latin-1") while maintaining the first  256  code  points.
413       ISO  8859-1  itself  is a superset of ASCII.  Run the above command and
414       verify the necessary  glyphs are present.
415
416       IMPORTANT: For input text, a different rule applies.  If you  feed  ISO
417       8859-1 text to pbmtext -wchar set up for UTF-8, the output will be gar‐
418       bled.  Unicode provides several encoding schemes and different ones are
419       in  effect  for  input  text  and font.  The difference between Unicode
420       codepoint and the various encodings is a  formidable  stumbling  block;
421       beware of web pages that get the concept wrong.
422
423       75%  of  the BDF files in the font collection available from the Netpbm
424       website  ⟨http://netpbm.sourceforge.net/bdffont.tgz⟩     are   in   ISO
425       10646-1.   Many  have  the Euro sign, Greek letters, etc., but they are
426       placed at code points available to pbmtext only with -wchar.
427
428       Before pbmtext had the -wchar option, one often had to  produce  a  BDF
429       file  in  an  8-bit  encoding  from  a  master  BDF file encoded in ISO
430       10646-1.
431
432       There are several programs that perform BDF  encoding  conversion.   If
433       you have the X Window System installed, first look for ucs2any.  If you
434       don't, you can download ucs2any.pl from Unicode  fonts  and  tools  for
435       X11" (1).  This website has much useful information on fonts.
436
437       Another converter is trbdf, included in the "trscripts" package, avail‐
438       able in some GNU/Linux distributions.
439
440       BDF files encoded in ISO 8859-2, ISO 8859-7, koi8-r, etc. are available
441       from  ISO  8859  Alphabet  Soup"  (1)  and its sister page The Cyrillic
442       Charset Soup" (1).  Though the information is dated, these pages give a
443       good overview of 8-bit character sets.
444
445       To convert OTF or TTF font files to BDF, use
446        otf2bdf                 by                 Mike                Leisher
447http://www.math.nmsu.edu/~mleisher/Software/otf2bdf⟩ .
448
449
450

SEE ALSO

452       pbmtextps(1), pamcut(1), pnmcrop(1), pamcomp(1),  ppmchange(1),  pnmro‐
453       tate(1),    ppmlabel(1),    ppmdraw(1),   pstopnm(1),   pbm(1),   Pango
454       http://www.pango.org, Cairo ⟨http://cairographics.org
455
456

AUTHOR

458       Copyright (C) 1993 by Jef Poskanzer and George Phillips
459

DOCUMENT SOURCE

461       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
462       source.  The master documentation is at
463
464              http://netpbm.sourceforge.net/doc/pbmtext.html
465
466netpbm documentation              29 May 2020           Pbmtext User Manual(0)
Impressum