.TH pbmtext 1 "28 January 2001"
.IX pbmtext
.SH NAME
pbmtext - render text into a bitmap
.SH SYNOPSIS
.B pbmtext
.RB [ \-font
.IR fontfile ]
.RB [ \-builtin
.IR fontname ]
.RB [ \-space
.IR pixels ]
.RB [ \-lspace
.IR pixels ]
.RI [ text ]

.SH DESCRIPTION
.PP
Takes the specified text, either a single line from the command line
or multiple lines from standard input, and renders it into a bitmap.

In the bitmap, each line of input is a line of output.  Formatting
characters such as newline have no effect on the formatting; like any
unprintable character, they turn into spaces.

The bitmap is just wide enough for the longest line of text, plus
margins, 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 margins are half of this.

.IX text
.SH OPTIONS
.TP
.BR -font , -builtin
By default, pbmtext uses a built-in font called bdf (about a 10 point
Times-Roman font).  You can use a fixed width font by specifying
.BR "-builtin fixed" .

You can also specify your own font with the
.B -font
flag.
The
.I fontfile
is either a BDF file from the X window system or a PBM file.

If the
.I fontfile
is a PBM file, it is created in a very specific way.  In your window
system of choice, display the following text in the desired
(fixed-width) font:
.nf

    M ",/^_[`jpqy| M

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

    M ",/^_[`jpqy| M

.fi
Do a screen grab or window dump of that text, using for instance
.BR xwd ,
.BR xgrabsc ,
or
.BR screendump .
Convert the result into a pbm file.  If necessary, use
.B pnmcut
to remove everything except the text.  Finally, run it through
.B pnmcrop
.IX pnmcrop
to make sure the edges are right up against the text.
.B pbmtext
can figure out the sizes and spacings from that.

.TP
.B -space \fIpixels
Add 
.I pixels
pixels of space between characters.  This is in addition to whatever 
space surrounding characters is built into the font, which is usually
enough to produce a reasonable string of text.

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

.TP
-B -lspace \fIpixels
Add
.I 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 spacing.

.I pixels
must be a whole number.

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


.SH USAGE

Often, you want to place text over another image.  One way to do this is
with 
.BR ppmlabel .
.B ppmlabel
does not give you the font options that 
.B pbmtext 
does, though.

Another way is to use 
.B pbmtext
to create an image containing the text, then use
.B pnmcomp
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
.B pnmcomp
a mask, via its 
.B -alpha
option.  You can just use the text image itself as the mask, as long as
you also specify the 
.B -invert
option to 
.BR pnmcomp .

If you want to overlay colored text instead of black, just use 
.B ppmchange
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 alpha mask.

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

.SH "SEE ALSO"
.BR pnmcut (1), 
.BR pnmcrop (1),
.BR pnmcomp (1),
.BR ppmchange (1),
.BR pnmrotate (1),
.BR pbmtextps (1),
.BR ppmlabel (1),
.BR pbm (5)

.SH AUTHOR
Copyright (C) 1993 by Jef Poskanzer and George Phillips
.\" Permission to use, copy, modify, and distribute this software and its
.\" documentation for any purpose and without fee is hereby granted, provided
.\" that the above copyright notice appear in all copies and that both that
.\" copyright notice and this permission notice appear in supporting
.\" documentation.  This software is provided "as is" without express or
.\" implied warranty.