PBMTEXTPS(1)

👑 PBMTEXTPS(1) — Pbmtextps User Manual 💖

okay bestie, sit down, get comfy, because we're about to render text into a PBM image with a Postscript interpreter and it's gonna be so cute. this is pbmtextps, part of the General Commands Manual bless 🫶

---

✨ NAME ✨

pbmtextps — render text into a PBM image using a postscript interpreter 💅

---

🌸 SYNOPSIS 🌸

pbmtextps [-font fontname] [-fontsize float] [-resolution n]
[-leftmargin=n] [-rightmargin=n] [-topmargin=n] [-bottommargin=n]
[-ascent=n] [-descent=n] [-pad] [-crop] [-stroke n] [-asciihex]
[-ascii85] [-verbose] [-dump-ps] text [text ...]

---

🦋 DESCRIPTION 🦋

so this program is one of the Netpbm(1) girlies, she's part of the family 💜

pbmtextps takes a single line of text off the command line and renders it into a PBM image. that's it, that's the vibe. the image is of one single line of text — and here's the thing, newline characters in the input have no effect at all. none. zero. they're just out here existing for no reason 😭

also you should clock pbmtext for a more sophisticated generator of text, but it uses less common font formats. pbmtext can generate multiple lines of text though, which is lowkey iconic of it. ✨

and a lil note for the historians: the -plain common option has no effect before Netpbm 10.42 (March 2008). the output is always raw PBM. periodt.

🎀 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 position relative to the origin. the size of the default left and bottom margins is explained below, don't worry bestie I got you 💖

you can set whatever margin you want with the options -leftmargin, -rightmargin, -topmargin and -bottommargin. the specified amount of white space gets added to the far edge of the type, so like — if you specify 10 points for -topmargin, you will get 10 points of white space above the highest character on the line. cute right? 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 the bottom to reach a specified distance below the text baseline. yes to the bottom. it's giving vertical realness 🫶

-ascent and -descent are more useful than -topmargin and -bottomargin when you render two pieces of text (in separate invocations of pbmtextps) that you will concatenate horizontally. with -ascent and -descent, 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 -bottommargin, 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. and if you use -ascent, use -jtop instead. match your energy to your option bestie 💅

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. consistent spacing? we love to see it. ⭐

if you have -ascent, there is probably no point in specifying -topmargin too, but if you do, the effect is cumulative. same energy for -descent and -bottommargin.

-pad pads the image on the top and bottom to 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. it's the great equaliser honestly 👑

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. the letters are doing the most, as usual 🙈

$ pbmtextps -pad 'cat'   | pamfile
$ pbmtextps -pad 'Catty' | pamfile

the commands above, with -pad, show that both images are the same height. slay. ✨

if you specify -pad with -ascent or -descent, the larger value is effective.

-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 -bottommargin=0. simple as that 💖

⚠️ you cannot specify any other margin-affecting options with -crop. it's an exclusive queen, pick a lane bestie.

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, -bottommargin, 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 appear 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. don't get caught out 💀

with -asciihex, you can include white space anywhere in the coded text; it has no effect. and you can spread the argument across multiple arguments 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. tragic, honestly 😭

with an -ascii85 option, you can specify the text in Postscript's ASCII-85 code. this is analogous to -asciihex. the Postscript delimiters for an ASCII-85 text string are <~ ~>. 🎀

---

💅 OPTIONS 💅

in addition to the options common to all programs based on libnetpbm (most notably -quiet, see Common Options), 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's 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. sneaky behaviour fr fr 💀

• -fontsize=float — this is the size of the font in points. see the -resolution option 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 — controls a margin added to the image, measured from the far edge of the type. see Margins for details. all sizes are in points, as a floating point number. this option was new in Netpbm 10.75 (June 2016). ✨
• -rightmargin=n — controls a margin added to the image, measured from the far edge of the type. see Margins for details. all sizes are in points, as a floating point number. this option was new in Netpbm 10.75 (June 2016). ✨
• -topmargin=n — controls a margin added to the image, measured from the far edge of the type. see Margins for details. all sizes are in points, as a floating point number. this option was new in Netpbm 10.75 (June 2016). ✨
• -bottommargin=n — controls a margin added to the image, measured from the far edge of the type. see Margins for details. all sizes are in points, as a floating point number. this option was new in Netpbm 10.75 (June 2016). ✨
• -ascent=n — this controls a margin added to the image, measured from the text baseline. see Margins for details. sizes are in points, as a floating point number. this option was new in Netpbm 10.75 (June 2016). 💜
• -descent=n — this controls a margin added to the image, measured from the text baseline. see Margins for details. sizes are in points, as a floating point number. this option was new in Netpbm 10.75 (June 2016). 💜
• -pad — this pads the image on the top and bottom to where the highest and lowest characters in the font would reach, even if you don't have those characters in your text. see Margins for details. 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 -topmargin=0 -bottommargin=0. see Margins 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 Input Text. 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 Input Text. 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. she's chatty, we love her 🗣️
• -dump-ps — this option makes pbmtextps write to Standard Output the Postscript program it would use to create the image, rather than the image itself. you can use this as input to a Postscript interpreter (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. soft edges? immaculate. 🦋

see the manual for the similar pbmtext for more advice on usage.

---

💜 HISTORY 💜

pbmtextps was added to Netpbm in Release 10.0 (June 2002). a classic, an OG, we stan a legacy icon 👑

---

🌈 SEE ALSO 🌈

pbmtext(1), pamcut(1), pnmcrop(1), pamcomp(1), ppmchange(1), pnmrotate(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

---

and that's the whole thing bestie, no notes, you ate 💅✨ this was netpbm documentation, version dated 17 February 2023, and yes it really is called the Pbmtextps User Manual(1) — go render something gorgeous with it, mwah 🫶💖🌸