From e09be88033bbbe215bfa825de4637c6478704de8 Mon Sep 17 00:00:00 2001 From: giraffedata Date: Wed, 15 Jun 2016 01:38:46 +0000 Subject: miscellaneous update git-svn-id: http://svn.code.sf.net/p/netpbm/code/userguide@2787 9d0c8265-081b-0410-96cb-a4ca84ce46f8 --- pbmtextps.html | 180 +++++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 162 insertions(+), 18 deletions(-) (limited to 'pbmtextps.html') diff --git a/pbmtextps.html b/pbmtextps.html index b3b4e064..a93ede8b 100644 --- a/pbmtextps.html +++ b/pbmtextps.html @@ -2,7 +2,7 @@ Pbmtextps User Manual

pbmtextps

-Updated: 21 May 2016 +Updated: 15 June 2016
Table Of Contents

NAME

@@ -12,32 +12,127 @@ pbmtextps - render text into a PBM image using a postscript interpreter pbmtextps [-font fontname] -[-fontsize n] +[-fontsize float] [-resolution n] +[-leftmargin=n +[-rightmargin=n +[-topmargin=n +[-bottommargin=n +[-ascent=n +[-descent=n +[-pad] +[-crop] [-stroke n] [-verbose] +[-dump-ps] text

DESCRIPTION

This program is part of Netpbm. -

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

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

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. You can use pnmcrop to crop it all the -way. +

See pbmtext for a more sophisticated generator of text, but using +less common font formats. pbmtext can generate multiple lines of text. -

See pbmtext for a more sophisticated generator of text, but -using less common font formats. pbmtext can generate multiple -lines of text. +

The -plain common option 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 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, 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
+     $ pnmcat -lr -jb a1.pbm a2.pbm > out.pbm
+
+
+ +

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

The -plain common -option has no effect before Netpbm 10.42 (March 2008). The output -is always raw PBM.

OPTIONS

@@ -53,13 +148,15 @@ postscript font which is installed on the system. pbmtextps just uses the default font. It does not tell you it is doing this. -
-fontsize=n +
-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 @@ -73,16 +170,63 @@ 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 Margins 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 the margins added to the image, measured from +the text baseline. See Margins 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 +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). +

-stroke=n
-This is the width of line to use for stroke font. There is no default stroke -width because the characters are solid by default. +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 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 a +printer) or to understand the program better. + +

This option was new in Netpbm 10.75 (June 2016). +

USAGE

-- cgit 1.4.1