Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Pbmtext	User Manual(0)					Pbmtext	User Manual(0)

NAME
       pbmtext - render	text into a PBM	image

SYNOPSIS
       pbmtext	[-wchar]  [-font fontfile] [-builtin fontname] [-space pixels]
       [-lspace	 pixels]  [-nomargins]	[-width	 pixels]   [-load-entire-font]
       [-dry-run] [-text-dump] [text]

       Minimum	unique abbreviation of option is acceptable.  You may use dou-
       ble hyphens instead of single hyphen to denote options.	 You  may  use
       white space in place of the equals sign to separate an option name from
       its value.

DESCRIPTION
       This program is part of Netpbm(1).

       pbmtext takes the specified text, either	a single line from the command
       line  or	 multiple lines	from standard input, and renders it into a PBM
       graphical image.

       The text	rendered is all	the non-option command line  arguments,	 sepa-
       rated  by  spaces,  except that if there	are no non-option command line
       arguments, it is	Standard Input.

       In the image, each line of input	is a line of output.  Lines are
	 delimited by newline characters.

       The program renders any character in an input line that is not  in  the
       font
	 as a space.  Note that	control	characters usually aren't in the font,
       but
	 some fonts have glyphs	for them.  The newline characters that delimit
       lines
	 in of Standard	Input are not in any line.

       Tab  characters	are  rendered  as a number of spaces; any entry	in the
       font
	 for the tab code point	is irrelevant.	The number of spaces  is  such
       as to
	 create	tab stops every	8 characters.  Note that this is not useful if
       the
	 font is proportional.

       The image is just wide enough for the longest line of text,  plus  mar-
       gins, and just high enough to contain the lines of text,	plus margins.

       The  left and right margins are twice the width of the widest character
       in the font; the	top and	bottom margins are the height of  the  tallest
       character  in the font.	But if the text	is only	one line, all the mar-
       gins are	half of	this.  You can use the -nomargins option to  eliminate
       the margins.

       pbmtext renders left to right.  It cannot render	vertically or right to
       left.

       pbmtextps does the same thing as	pbmtext, but uses Ghostscript to  gen-
       erate the characters, which means you can use Postscript	fonts.	But it
       also means you have to have Ghostscript installed and it	isn't as fast.
       Also,  pbmtextps	 generates  only one line of text, whereas pbmtext can
       create multiple lines.

       pbmtext is meant	for simple text.  If you're working with  a  document,
       you  would be better off	using a	document formatting program to "print"
       to a Postscript file, then feeding that Postscript to pstopnm.

OPTIONS
       -wchar

	      By default, pbmtext takes	a single-byte character	stream as  in-
	      put.   When you specify -wchar, it treats	input text as a	multi-
	      byte character stream encoded according to the  current  locale.
	      Normally,	 the  user  would  supply  a  BDF font file encoded in
	      ISO-10646-1 with a -font option.

	      With -wchar, you cannot supply the text on the command line;  it
	      must be fed from standard	input.

	      This option was new in Netpbm 10.82 (March 2018).

       -font

       -builtin
	      -builtin selects a font among those built	into Netpbm.

	      -font  selects  a	 font  that you	supply yourself	either as an X
	      Window	System	  BDF	  (Bitmap     Distribution     Format)
	      <http://xfree86.org/current/bdf.pdf>  file or as a PBM file in a
	      special form.

	      The default is the built in font "bdf."

	      "bdf" is Times-Roman 15 pixels high.   (That's  about  14	 point
	      type printed at 75 dpi).

	      "fixed" is a built in fixed width	font.

	      For  information	about other fonts, and how to make one of your
	      own, see Fonts <#fonts>  below.

       -space pixels
	       Add pixels pixels of space between characters.  This is in  ad-
	      dition  to  whatever  space surrounding characters is built into
	      the font,	which is usually enough	to produce a reasonable	string
	      of text.

	      pixels  may  be  fractional,  in which case the number of	pixels
	      added varies so as to achieve the	specified average.  For	 exam-
	      ple  -space=1.5 causes half the spaces to	be 1 pixel and half to
	      be 2 pixels.

	      pixels may be negative to	crowd text together,  but  the	author
	      has not put much thought or testing into how this	works in every
	      possible case, so	it might cause disastrous results.

       -lspace pixels
	       Add pixels pixels of space between lines.  This is in  addition
	      to  whatever  space above	and below characters is	built into the
	      font, which is usually enough to produce a reasonable line spac-
	      ing.

	      pixels must be a whole number.

	      pixels  may  be negative to crowd	lines together,	but the	author
	      has not put much thought or testing into how this	works in every
	      possible case, so	it might cause disastrous results.

       -nomargins
	      By  default,  pbmtext  adds  margins all around the image	as de-
	      scribed above.  This option causes pbmtext not to	add  any  mar-
	      gins.

	      Note  that there may still be space beyond the edges of the type
	      because a	character itself may include space at its  edges.   To
	      eliminate	 all  surrounding  background, so the type touches all
	      four edges of the	image, use pnmcrop.

       -width pixels
	      This specifies how much horizontal space the text	is supposed to
	      fit into.

	      If  the input is one line, pbmtext breaks	it into	multiple lines
	      as needed	to fit the specified  width.   It  breaks  it  between
	      characters,  but	does  not pay attention	to white space;	it may
	      break in the middle of a word and	a line may begin or  end  with
	      white space.

	      If the input is multiple lines, pbmtext assumes you already have
	      line breaks where	they make sense, and pbmtext simply  truncates
	      each line	as needed to fit the specified width.

       -load-entire-font

	      When  you	 use  a	 BDF font, pbmtext will	normally load from the
	      font
		  only the characters needed for your text, not	 wasting  time
	      loading other
		  characters.  With this option, pbmtext will instead read the
	      entire
		  font.	 It won't make any difference in the rendered  output,
	      but it lets
		  you check the	integrity of the font file.

	      This  option  was	new in Netpbm 10.91 (June 2020).  Before that,
	      pbmtext always reads the entire font.

       -dry-run

	      With this	option,	instead	of outputting an image	of  the	 text,
	      pbmtext just writes to Standard Output a message telling the di-
	      mensions of the image it would have produced.

	      You can specify only one of -dry-run and -text-dump.

	      This option was new in Netpbm 10.75 (June	2016).

       -text-dump
	      This option causes pbmtext just to write to Standard Output  the
	      text  in	ASCII that would be rendered.  The output reflects any
	      text formatting, unprintable character substitution, tab	expan-
	      sion,  etc.  It is for diagnosing	problems.  This	option was new
	      in Netpbm	10.82 (March 2018).

	      When -wchar is in	effect,	the output text	will be	in the	encod-
	      ing specified by the current locale.

	      You can specify only one of -dry-run and -text-dump.

	      This option was new in Netpbm 10.82 (March 2018).

USAGE
       Often,  you  want to place text over another image.  One	way to do this
       is with ppmlabel.  For more flexible (but complex) drawing of  text  on
       an  image,  there  is  ppmdraw.	These do not give you the font options
       that pbmtext does, though.

       Another way is to use pbmtext to	create an image	containing  the	 text,
       then  use  pamcomp  to overlay the text image onto your base image.  To
       make only the text (and not the entire rectangle	containing  it)	 cover
       the  base  image,  you will need	to give	pamcomp	a mask,	via its	-alpha
       option.	You can	just use the text image	itself as the mask, as long as
       you also	specify	the -invert option to pamcomp.

       If  you	want  to  overlay colored text instead of black, just use ppm-
       change to change	all black pixels to the	color of  your	choice	before
       overlaying  the text image.  But	still use the original black and white
       image for the transparency mask.

       If you want the text at an angle, use pnmrotate on the text image  (and
       transparency mask) before overlaying.

FONTS
       There are three kinds of	fonts you an use with pbmtext:

       o      built in

       o      BDF

       o      PBM

   Built In Fonts
       There  are  two	built in fonts:	bdf and	fixed.	You select these fonts
       with a -builtin option.

       bdf is the default when you specify no font information on the  command
       line.  The naming reflects the fact that	it shares many characteristics
       of BDF style fonts.  When this font was implemented,  pbmtext  did  not
       have the	ability	to read	arbitrary BDF fonts specified by the -font op-
       tion.  There is no external font	file involved.

       bdf is encoded in ISO 8859-1 (Latin 1, 8-bit).  In addition to  English
       it  can	handle	most West European languages (Spanish, French, German,
       Swedish ...)  This set lacks the	Euro currency sign.

       fixed is	ASCII (7-bit) only.

       While it	is not an error	to do so, you should not use the above	built-
       in fonts	with -wchar.

   BDF Font
       BDF  is	an ancient font	format that at one time	was standard for the X
       Window System.  Now, you	don't see it very often, but you can find some
       BDF	       fonts		 on		the	       Xfree86
       <http://cvsweb.xfree86.org/cvsweb/xc/fonts/bdf/>	 web site.

       You can get the full package of the BDF fonts from XFree86 (see	above)
       from the	Netpbm web site	<http://netpbm.sourceforge.net/bdffont.tgz> .

   PBM Font
       To create a font	as a PBM file (to use with the -font option), you just
       create a	PBM image of the text matrix below.

       The first step is to display text matrix	below on the screen,  e.g.  in
       an X11 window.

	   M ",/^_[`jpqy| M

	   /  !"#$%&'()*+ /
	   < ,-./01234567 <
	   > 89:;<=>?@ABC >
	   @ DEFGHIJKLMNO @
	   _ PQRSTUVWXYZ[ _
	   { \]^_`abcdefg {
	   } hijklmnopqrs }
	   ~ tuvwxyz{|}~  ~

	   M ",/^_[`jpqy| M

       Make  sure  it's	a fixed	width font -- This should display as a perfect
       rectangle.

       Also, try to use	a simple display program.  Pbmtext divides this	into a
       matrix  of  cells, all the same size, each containing one character, so
       it is important that whatever you use to	display	it display  with  uni-
       form  horizontal	 and vertical spacing.	Fancy word processing programs
       sometimes stretch characters in both directions to fit  certain	dimen-
       sions,  and that	won't work.  Sometimes a display program scales	a font
       to show a character larger or smaller than its natural size.  That  too
       won't  often  work because the rounding involved	in such	scaling	causes
       non-uniform distances between characters.

       If you display the text matrix improperly, the usual  symptom  is  that
       when  you  try  to  use	the  font, pbmtext fails with an error message
       telling you that	the number of lines in the font	isn't divisible	by 11,
       or  it can't find the blank band	around the inner rectangle.  Sometimes
       the symptom is that one of the characters displays with a piece of  the
       character  that	is  next  to it	in the matrix.	For example, "l" might
       display with a little piece of the "m" attached on its right.

       Do a screen grab	or window dump of that text, using for	instance  xwd,
       xgrabsc,	or screendump.	Convert	the result into	a pbm file.  If	neces-
       sary, use pamcut	to remove anything you grabbed in addition to the text
       pictured	 above (or be a	wimp and use a graphical editor	such as	Gimp).
       Finally,	run it through pnmcrop to make sure the	 edges	are  right  up
       against	the  text.  pbmtext can	figure out the sizes and spacings from
       that.

       There are some historical computer fonts, such  as  that	 used  by  the
       original	 IBM  PC, in the form that you can screen-grab and turn	into a
       PBM font	file available from Stewart C Russell" (1).  There  are	 fonts
       with various duodecimal digit glyphs at
	treisara.deviantart.com
       <http://treisaran.deviantart.com/gallery/38695571/NetPBM-Fonts> .

       PBM fonts cannot	be used	with -wchar.

MULTI-BYTE INPUT
       In the past, English text was encoded in	7-bit ASCII.  8-bit and	multi-
       byte encodings were needed only for non-English languages.  This	is not
       the case	today.	As of this writing, 90%	of all web pages  are  encoded
       in  UTF-8.   While many of them are actually restricted to 7-bit	ASCII,
       which is	a subset of UTF-8, English text	encoded	in UTF-8 commonly  em-
       ploys "66 99" style quotation marks, which do not appear	in ASCII.

       If  your	 input	text is	UTF-8, you should use -wchar.  You may have to
       tweak the locale	setting.  pbmtext recognizes code points up to	65535.
       This is sufficient for the vast majority	of text	written	in modern lan-
       guages.

       In the default single-byte (or "narrow")	character  mode,  pbmtext  can
       handle  7-bit  and  8-bit character sets.  Examples are ASCII, ISO 8859
       family, koi8-r/u	and VISCII.  It	is up to the user to supply a BDF file
       covering	 the  necessary	glyphs with the	"-font"	option.	 The font file
       must be in the right encoding.

       pbmtext does not	inspect	the encoding of	the font file.

LIMITATIONS
       If the text is from Standard Input, no line may	be  longer  than  4999
       characters.   If	 one  is, the program aborts with an appropriate error
       message.

       If the text is from Standard Input and contains a null  character,  the
       results are abnormal.  Lines may	be truncated, and a single line	may be
       considered multiple lines.  Normal text does not	contain	 null  charac-
       ters, so	this isn't a big problem.

TIPS
       If  you get garbled output, check the input text	encoding and font file
       encoding.  When using -wchar, also check	the current locale.

       To convert the encoding of a text file, use iconv or luit.

       To check	the encoding of	a BDF file, examine the	CHARSET_REGISTRY  line
       and the next line, which	should be CHARSET_ENCODING:

	   $ grep -A1 CHARSET_REGISTRY font-a.bdf
	   CHARSET_REGISTRY "ISO8859"
	   CHARSET_ENCODING "1"

	   $ grep -A1 CHARSET_REGISTRY font-b.bdf
	   CHARSET_REGISTRY "ISO10646"
	   CHARSET_ENCODING "1"

       The latter is Unicode.  BDF files coded in ISO 16046-1 usually work for
       Western European	languages, because  ISO	 16046-1  expands  ISO	8859-1
       (also  called  "Latin-1")  while	maintaining the	first 256 code points.
       ISO 8859-1 itself is a superset of ASCII.  Run the  above  command  and
       verify the necessary  glyphs are	present.

       IMPORTANT:  For	input text, a different	rule applies.  If you feed ISO
       8859-1 text to pbmtext -wchar set up for	UTF-8, the output will be gar-
       bled.  Unicode provides several encoding	schemes	and different ones are
       in effect for input text	and  font.   The  difference  between  Unicode
       codepoint  and  the  various encodings is a formidable stumbling	block;
       beware of web pages that	get the	concept	wrong.

       75% of the BDF files in the font	collection available from  the	Netpbm
       website	 <http://netpbm.sourceforge.net/bdffont.tgz>	  are  in  ISO
       10646-1.	 Many have the Euro sign, Greek	letters, etc.,	but  they  are
       placed at code points available to pbmtext only with -wchar.

       Before  pbmtext	had  the -wchar	option,	one often had to produce a BDF
       file in an 8-bit	encoding  from	a  master  BDF	file  encoded  in  ISO
       10646-1.

       There  are  several  programs that perform BDF encoding conversion.  If
       you have	the X Window System installed, first look for ucs2any.	If you
       don't,  you  can	 download  ucs2any.pl from Unicode fonts and tools for
       X11" (1).  This website has much	useful information on fonts.

       Another converter is trbdf, included in the "trscripts" package,	avail-
       able in some GNU/Linux distributions.

       BDF files encoded in ISO	8859-2,	ISO 8859-7, koi8-r, etc. are available
       from ISO	8859 Alphabet Soup" (1)	 and  its  sister  page	 The  Cyrillic
       Charset Soup" (1).  Though the information is dated, these pages	give a
       good overview of	8-bit character	sets.

       To convert OTF or TTF font files	to BDF,	use
	otf2bdf		       by		  Mike		       Leisher
       <http://www.math.nmsu.edu/~mleisher/Software/otf2bdf> .

SEE ALSO
       pbmtextps(1),  pamcut(1),  pnmcrop(1), pamcomp(1), ppmchange(1),	pnmro-
       tate(1),	  ppmlabel(1),	 ppmdraw(1),   pstopnm(1),    pbm(5),	 Pango
       <http://www.pango.org> ,	Cairo <http://cairographics.org>

AUTHOR
       Copyright (C) 1993 by Jef Poskanzer and George Phillips

DOCUMENT SOURCE
       This  manual  page was generated	by the Netpbm tool 'makeman' from HTML
       source.	The master documentation is at

	      http://netpbm.sourceforge.net/doc/pbmtext.html

netpbm documentation		  28 May 2020		Pbmtext	User Manual(0)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | USAGE | FONTS | MULTI-BYTE INPUT | LIMITATIONS | TIPS | SEE ALSO | AUTHOR | DOCUMENT SOURCE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pbmtext&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help