Pbmtextps User Manual(1) General Commands Manual Pbmtextps User Manual(1)
NAME
pbmtextps - render text into a PBM image using a postscript interpreter
SYNOPSIS
pbmtextps [-font fontname] [-fontsize float] [-resolution n] [-leftmar-
gin=n] [-rightmargin=n] [-topmargin=n] [-bottommargin=n] [-ascent=n]
[-descent=n] [-pad] [-crop] [-stroke n] [-asciihex] [-ascii85] [-ver-
bose] [-dump-ps] text [text ...]
DESCRIPTION
This program is part of Netpbm(1).
pbmtextps takes a single line of text from the command line and renders
it into a PBM image. The image is of a single line of text; newline
characters in the input have no effect.
See pbmtext for a more sophisticated generator of text, but using less
common font formats. pbmtext can generate multiple lines of text.
The -plain ]8;;index.html#commonoptions\common option]8;;\ has no effect before Netpbm 10.42 (March
2008). The output is always raw PBM.
Margins
By default, the image is cropped at the top and the right. It is not
cropped at the left or bottom so that the text begins at the same posi-
tion relative to the origin. The size of the default left and bottom
margins is explained below.
You can set whatever margin you want with options -leftmargin, -right-
margin, -topmargin and -bottommargin. The specified amount of white
space gets added to the far edge of type, e.g. if you specify 10 points
for -topmargin, you will get 10 points of white space above the highest
character on the line. Specify 0 to crop a side.
-ascent adds white space to the top to reach a specified distance above
the text baseline, and -descent adds white space to to the bottom to
reach a specified distance below the text baseline.
-ascent and -descent are more useful than -topmargin and -bottomargin
when you render two pieces of text (in separate invocations of pbm-
textps) that you will concatenate horizontally. With -ascent and -de-
scent, as long as you specify a value greater than the height or detph
of every character in the font, the two images will be the same height
with the text baseline in the same place. With -topmargin and -bottom-
margin, that may not be the case.
Example:
$ pbmtextps -font=Times-Roman -descent=20 \
'The soup is called' > a1.pbm
$ pbmtextps -font=Itallic -descent=20 'Goulash.' > a2.pbm
$ pamcat -leftright -jbottom a1.pbm a2.pbm > out.pbm
If you're using -descent to line up the segments of text you are
concatenating horizontally with pamcat, use the -jbottom
(justify to bottom) option on pamcat as in the example above. If you
use -ascent, use -jtop instead.
Similarly, if you render two lines of text (in separate invocations of
pbmtextps) that you will concatenate vertically, -ascent and
-descent with sufficiently large values will ensure your baselines
are uniformly spaced.
If you have -ascent, there is probably no point in specifying -topmargin
too, but if you do, the effect is cumulative. The same is true of -de-
scent and -bottommargin.
-pad pads the image on the top and bottom to the where the highest and
lowest characters in the font would reach, even if you don't have those
characters in your text. This is useful if you will generate multiple
images of text (with multiple invocations of pbmtextps) and concatenate
them vertically to create a multiline text image. -pad makes sure the
lines in this image are equally spaced.
Example:
$ pbmtextps 'cat' | pamfile
$ pbmtextps 'Catty' | pamfile
The commands above, with no -pad, show that the 'Catty' image is higher
because capital C reaches high and 'y' reaches low.
$ pbmtextps -pad 'cat' | pamfile
$ pbmtextps -pad 'Catty' | pamfile
The commands above, with -pad, show that both images are the same
height.
If you specify -pad with -ascent or -descent, the larger value is effec-
tive.
-crop makes the program crop all sides to the far edge of the type. It
is the same as -leftmargin=0 -rightmargin=0 -topmargin=0 -bottommar-
gin=0.
You cannot specify any other margin-affecting options with -crop.
The default top margin, when you specify neither -ascent, -topmargin,
nor -pad, is as if you specified topmargin=0.
The default bottom margin, when you specify neither -descent, -bottom-
margin, nor -pad, is as if you specified -descent=1.5*fontsize.
The default left margin, when you do not specify -leftmargin, is as if
you specified -leftmargin=0.5*fontsize.
The default right margin, when you do not specify -rightmargin, is as if
you specified -rightmargin=0.
Input Text
The simplest way to specify the text to render is just to specify it,
in ASCII, as the sole argument of the command. For example,
$ pbmtextps 'hello world'
But you can also spread it across multiple arguments. pbmtextps
concatenates them right to left with a single space in between:
$ pbmtextps hello world
With an -asciihex option, you can specify the text in Postscript's
ASCII-HEX code:
$ pbmtextps -asciihex 68656c6c6f20776f726c64
You can optionally include the ASCII-HEX text delimiters that would ap-
pear around the text in a Postscript program:
$ pbmtextps -asciihex '<68656c6c6f20776f726c64>'
Note that the <> delimiters have special meaning to command shells, so
if you are invoking pbmtextps via a command shell, be sure to quote
them, as is done in this example.
With -asciihex, you can include white space anywhere in the coded text;
it has no effect. And you can spread the argument across multiple argu-
ments as for plain ASCII input:
$ pbmtextps -asciihex '<' 68656c6c6f 20 776f726c64 '>'
But note that while Postscript allows an ASCII NUL character as white
space, there is no way to pass an argument including a NUL character
to
pbmtextps.
With an -ascii85 option, you can specify the text in Postscript's
ASCII-85 code. This is analogous to -asciihex. The Postscript delim-
iters for an ASCII-85 text string are <~ ~>.
OPTIONS
In addition to the options common to all programs based on libnetpbm
(most notably -quiet, see ]8;;index.html#commonoptions\ Common Options]8;;\ ), pbmtextps recognizes the
following command line options:
-font=fontname
This specifies the font to use. fontname is the name of any
valid Postscript font which is installed on the system.
The default is TimesRoman.
Here is a way to get a list of the names of all the available
fonts:
$ gs -c '(*) {==} 256 string /Font resourceforall'
Warning: if fontname does not name a valid font, pbmtextps just
uses the default font. It does not tell you it is doing this.
-fontsize=float
This is the size of the font in points. See the -resolution op-
tion for information on how to interpret this size.
The default is 24 points.
Before Netpbm 10.75 (June 2016), this has to be a whole number.
-resolution=n
This is the resolution in dots per inch of distance measurements
pertaining to generation of the image. PBM images don't have any
inherent resolution, so a distance such as "1 inch" doesn't mean
anything unless you separately specify what resolution you're
talking about. That's what this option does.
In particular, the meaning of the font size is determined by this
resolution. If the font size is 24 points and the resolution is
150 dpi, then the font size is 50 pixels.
The default is 150 dpi.
-leftmargin=n
-rightmargin=n
-topmargin=n
-bottommargin=n
These options control the margins added to the image, measured
from the far edge of the type. See ]8;;#margins\Margins]8;;\ for details.
All sizes are in points, as a floating point number.
These options were new in Netpbm 10.75 (June 2016).
-ascent=n
-descent=n
These options control the margins added to the image, measured
from the text baseline. See ]8;;#margins\Margins]8;;\ for details.
Sizes are in points, as a floating point number.
These options were new in Netpbm 10.75 (June 2016).
-pad This pads the image on the top and bottom to the where the high-
est and lowest characters in the font would reach, even if you
don't have those characters in your text. See ]8;;#margins\Margins]8;;\ for de-
tails.
This option was new in Netpbm 10.75 (June 2016).
-crop This makes the program crop all sides to the far edge of the
type. It is the same as -leftmargin=0 -rightmargin=0 -topmar-
gin=0 -bottommargin=0. See ]8;;#margins\Margins]8;;\ for details.
This option was new in Netpbm 10.75 (June 2016).
-asciihex
This means the text in the arguments is in Postscript ASCII-HEX
code. See ]8;;#input_text\Input Text]8;;\ .
You cannot specify this together with -ascii85.
This option was new in Netpbm 11.02 (March 2023)
-ascii85
This means the text in the arguments is in Postscript ASCII-85
code. See ]8;;#input_text\Input Text]8;;\ .
You cannot specify this together with -asciihex.
This option was new in Netpbm 11.02 (March 2023)
-stroke=n
This is the width of line, in points, to use for stroke font.
There is no default stroke width because the characters are solid
by default.
-verbose
This option makes pbmtextps display extra information on Standard
Error about its processing.
-dump-ps
This option makes pbmtextps write to Standard Output the Post-
script program it would use to create the image, rather than the
image itself. You can use this as input to a Postscript inter-
preter (such as Ghostscript or a printer) or to understand the
program better.
This option was new in Netpbm 10.75 (June 2016).
USAGE
You can generate antialiased text by using a larger resolution than the
default and scaling the image down using pamscale.
See the manual for the similar pbmtext for more advice on usage.
HISTORY
pbmtextps was added to Netpbm in Release 10.0 (June 2002).
SEE ALSO
pbmtext(1), pamcut(1), pnmcrop(1), pamcomp(1), ppmchange(1), pnmro-
tate(1), pamscale(1), ppmlabel(1), pbm(1)
AUTHOR
Copyright (C) 2002 by James McCann
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/pbmtextps.html
netpbm documentation 17 February 2023 Pbmtextps User Manual(1)
Generated by dwww version 1.16 on Tue Dec 16 04:53:57 CET 2025.