diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/pbmtextps.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/pbmtextps.1 | 435 |
1 files changed, 435 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/pbmtextps.1 b/upstream/mageia-cauldron/man1/pbmtextps.1 new file mode 100644 index 00000000..109eb6e9 --- /dev/null +++ b/upstream/mageia-cauldron/man1/pbmtextps.1 @@ -0,0 +1,435 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Pbmtextps User Manual" 0 "17 February 2023" "netpbm documentation" + +.SH NAME +pbmtextps - render text into a PBM image using a postscript interpreter + +.UN synopsis +.SH SYNOPSIS + +\fBpbmtextps\fP +[\fB-font\fP \fIfontname\fP] +[\fB-fontsize\fP \fIfloat\fP] +[\fB-resolution\fP \fIn\fP] +[\fB-leftmargin=\fP\fIn\fP] +[\fB-rightmargin=\fP\fIn\fP] +[\fB-topmargin=\fP\fIn\fP] +[\fB-bottommargin=\fP\fIn\fP] +[\fB-ascent=\fP\fIn\fP] +[\fB-descent=\fP\fIn\fP] +[\fB-pad\fP] +[\fB-crop\fP] +[\fB-stroke\fP \fIn\fP] +[\fB-asciihex\fP] +[\fB-ascii85\fP] +[\fB-verbose\fP] +[\fB-dump-ps\fP] +\fItext\fP [\fItext\fP ...] + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBpbmtextps\fP 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. +.PP +See \fBpbmtext\fP for a more sophisticated generator of text, but using +less common font formats. \fBpbmtext\fP can generate multiple lines of text. +.PP +The \fB-plain\fP +.UR index.html#commonoptions +common option +.UE +\& has +no effect before Netpbm 10.42 (March 2008). The output is always raw PBM. + +.UN margins +.SS Margins +.PP +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. +.PP +You can set whatever margin you want with options +\fB-leftmargin\fP, \fB-rightmargin\fP, \fB-topmargin\fP and +\fB-bottommargin\fP. The specified amount of white space gets added to the +far edge of type, e.g. if you specify 10 points for \fB-topmargin\fP, you +will get 10 points of white space above the highest character on the line. +Specify 0 to crop a side. +.PP +\fB-ascent\fP adds white space to the top to reach a specified distance +above the text baseline, and \fB-descent\fP adds white space to to the bottom +to reach a specified distance below the text baseline. +.PP +\fB-ascent\fP and \fB-descent\fP are more useful than \fB-topmargin\fP +and \fB-bottomargin\fP when you render two pieces of text (in separate +invocations of \fBpbmtextps\fP) that you will concatenate horizontally. +With \fB-ascent\fP and \fB-descent\fP, 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 \fB-topmargin\fP and \fB-bottommargin\fP, that may not be the case. +.PP +Example: + +.nf +\f(CW + $ pbmtextps -font=Times-Roman -descent=20 \e + 'The soup is called' > a1.pbm + $ pbmtextps -font=Itallic -descent=20 'Goulash.' > a2.pbm + $ pnmcat -leftright -jbottom a1.pbm a2.pbm > out.pbm +\fP + +.fi +.PP +If you're using \fB-descent\fP to line up the segments of text you are + concatenating horizontally with \fBpnmcat\fP, use the \fB-jbottom\fP + (justify to bottom) option on \fBpnmcat\fP as in the example above. If you + use \fB-ascent\fP, use \fB-jtop\fP instead. +.PP +Similarly, if you render two lines of text (in separate invocations of + \fBpbmtextps\fP) that you will concatenate vertically, \fB-ascent\fP and + \fB-descent\fP with sufficiently large values will ensure your baselines + are uniformly spaced. +.PP +If you have \fB-ascent\fP, there is probably no point in specifying +\fB-topmargin\fP too, but if you do, the effect is cumulative. The same is +true of \fB-descent\fP and \fB-bottommargin\fP. +.PP +\fB-pad\fP 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 \fBpbmtextps\fP) and concatenate them +vertically to create a multiline text image. \fB-pad\fP makes sure the lines +in this image are equally spaced. +.PP +Example: + +.nf +\f(CW + $ pbmtextps 'cat' | pamfile + $ pbmtextps 'Catty' | pamfile +\fP + +.fi +.PP +The commands above, with no \fB-pad\fP, show that the 'Catty' +image is higher because capital C reaches high and 'y' reaches low. + +.nf +\f(CW + $ pbmtextps -pad 'cat' | pamfile + $ pbmtextps -pad 'Catty' | pamfile +\fP + +.fi +.PP +The commands above, with \fB-pad\fP, show that both images are the same +height. +.PP +If you specify \fB-pad\fP with \fB-ascent\fP or \fB-descent\fP, the +larger value is effective. +.PP +\fB-crop\fP makes the program crop all sides to the far edge of the type. +It is the same as \f(CW-leftmargin=0 -rightmargin=0 -topmargin=0 +-bottommargin=0\fP. +.PP +You cannot specify any other margin-affecting options with \fB-crop\fP. +.PP +The default top margin, when you specify neither \fB-ascent\fP, +\fB-topmargin\fP, nor \fB-pad\fP, is as if you specified +\fBtopmargin=0\fP. +.PP +The default bottom margin, when you specify neither \fB-descent\fP, +\fB-bottommargin\fP, nor \fB-pad\fP, is as if you specified +\fB-descent=\fP\fI1.5*fontsize\fP. +.PP +The default left margin, when you do not specify \fB-leftmargin\fP, is +as if you specified \fB-leftmargin=\fP\fI0.5*fontsize\fP. +.PP +The default right margin, when you do not specify \fB-rightmargin\fP, +is as if you specified \fB-rightmargin=0\fP. + + +<h3 id="input_text">Input Text</h2> +.PP +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, + +.nf + \f(CW + $ pbmtextps 'hello world' + \fP + +.fi +.PP +But you can also spread it across multiple arguments. \fBpbmtextps\fP + concatenates them right to left with a single space in between: + +.nf + \f(CW + $ pbmtextps hello world + \fP + +.fi +.PP +With an \fB-asciihex\fP option, you can specify the text in +Postscript's ASCII-HEX code: + +.nf + \f(CW + $ pbmtextps -asciihex 68656c6c6f20776f726c64 + \fP + +.fi +.PP +You can optionally include the ASCII-HEX text delimiters that would appear +around the text in a Postscript program: + +.nf + \f(CW + $ pbmtextps -asciihex '<68656c6c6f20776f726c64>' + \fP + +.fi +.PP +Note that the <> delimiters have special meaning to command shells, so if +you are invoking \fBpbmtextps\fP via a command shell, be sure to quote them, +as is done in this example. + +.PP +With \fB-asciihex\fP, 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: + +.nf + \f(CW + $ pbmtextps -asciihex '<' 68656c6c6f 20 776f726c64 '>' + \fP + +.fi +.PP +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 + \fBpbmtextps\fP. + +.PP +With an \fB-ascii85\fP option, you can specify the text in +Postscript's ASCII-85 code. This is analogous to \fB-asciihex\fP. The +Postscript delimiters for an ASCII-85 text string are <~ ~>. + + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBpbmtextps\fP recognizes the following +command line options: + + +.TP +\fB-font=\fP\fIfontname\fP +.sp +This specifies the font to use. \fIfontname\fP is the name of any valid +Postscript font which is installed on the system. +.sp +The default is \fBTimesRoman\fP. +.sp +Here is a way to get a list of the names of all the available fonts: + +.nf +\f(CW + $ gs -c '(*) {==} 256 string /Font resourceforall' +\fP + +.fi +.sp +\fBWarning:\fP if \fIfontname\fP does not name a valid font, +\fBpbmtextps\fP just uses the default font. It does not tell you it is doing +this. + +.TP +\fB-fontsize=\fP\fIfloat\fP +This is the size of the font in points. See the \fB-resolution\fP option for +information on how to interpret this size. +.sp +The default is 24 points. +.sp +Before Netpbm 10.75 (June 2016), this has to be a whole number. + +.TP +\fB-resolution=\fP\fIn\fP +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. +.sp +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. +.sp +The default is 150 dpi. + +.TP +\fB-leftmargin=\fP\fIn\fP +.TP +\fB-rightmargin=\fP\fIn\fP +.TP +\fB-topmargin=\fP\fIn\fP +.TP +\fB-bottommargin=\fP\fIn\fP +These options control the margins added to the image, measured from the far +edge of the type. See +.UR #margins +Margins +.UE +\& for details. +.sp +All sizes are in points, as a floating point number. +.sp +These options were new in Netpbm 10.75 (June 2016). + +.TP +\fB-ascent=\fP\fIn\fP +.TP +\fB-descent=\fP\fIn\fP +These options control the margins added to the image, measured from +the text baseline. See +.UR #margins +Margins +.UE +\& for details. +.sp +Sizes are in points, as a floating point number. +.sp +These options were new in Netpbm 10.75 (June 2016). + +.TP +\fB-pad\fP +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 +.UR #margins +Margins +.UE +\& for details. +.sp +This option was new in Netpbm 10.75 (June 2016). + +.TP +\fB-crop\fP +This makes the program crop all sides to the far edge of the type. It is the +same as \f(CW-leftmargin=0 -rightmargin=0 -topmargin=0 -bottommargin=0\fP. +See +.UR #margins +Margins +.UE +\& for details. +.sp +This option was new in Netpbm 10.75 (June 2016). + +.TP +\fB-asciihex\fP +This means the text in the arguments is in Postscript ASCII-HEX code. +See +.UR #input_text +Input Text +.UE +\&. +.sp +You cannot specify this together with \fB-ascii85\fP. +.sp +This option was new in Netpbm 11.02 (March 2023) + +.TP +\fB-ascii85\fP +This means the text in the arguments is in Postscript ASCII-85 code. +See +.UR #input_text +Input Text +.UE +\&. +.sp +You cannot specify this together with \fB-asciihex\fP. +.sp +This option was new in Netpbm 11.02 (March 2023) + +.TP +\fB-stroke=\fP\fIn\fP +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. + +.TP +\fB-verbose\fP +This option makes \fBpbmtextps\fP display extra information on Standard Error +about its processing. + +.TP +\fB-dump-ps\fP +This option makes \fBpbmtextps\fP 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. +.sp +This option was new in Netpbm 10.75 (June 2016). + + + +.UN usage +.SH USAGE + +You can generate antialiased text by using a larger resolution than the +default and scaling the image down using \fBpamscale\fP. +.PP +See the manual for the similar \fBpbmtext\fP for more advice on +usage. + +.UN history +.SH HISTORY +.PP +\fBpbmtextps\fP was added to Netpbm in Release 10.0 (June 2002). + + +.UN seealso +.SH SEE ALSO +.BR "pbmtext" (1)\c +\&, +.BR "pamcut" (1)\c +\&, +.BR "pnmcrop" (1)\c +\&, +.BR "pamcomp" (1)\c +\&, +.BR "ppmchange" (1)\c +\&, +.BR "pnmrotate" (1)\c +\&, +.BR "pamscale" (1)\c +\&, +.BR "ppmlabel" (1)\c +\&, +.BR "pbm" (1)\c +\& + +.UN author +.SH AUTHOR + +Copyright (C) 2002 by James McCann +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/pbmtextps.html +.PP
\ No newline at end of file |