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.

You can set whatever margin you want with options -leftmargin, -rightmargin, -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 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. 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 -descent 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 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.

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, -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.

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.

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 <~ ~>.