man > pbmtextps(1)

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] [-leftmargin=n] [-rightmargin=n]
       [-topmargin=n]  [-bottommargin=n] [-ascent=n] [-descent=n] [-pad] [-crop] [-stroke n] [-asci‐
       ihex] [-ascii85] [-verbose] [-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  al‐
       ways 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 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 -left‐
       margin=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 -left‐
       margin=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 <~ ~>.



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 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 genera‐
              tion 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 highest and lowest charac‐
              ters in the font would reach, even if you don't have those characters  in  your  text.
              See ]8;;#margins\Margins]8;;\  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 ]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 pro‐
              cessing.


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

       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), pnmrotate(1), pamscale(1),  ppm‐
       label(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)