diff options
Diffstat (limited to '')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man1/pbmtext.1 | 538 |
1 files changed, 538 insertions, 0 deletions
diff --git a/upstream/opensuse-tumbleweed/man1/pbmtext.1 b/upstream/opensuse-tumbleweed/man1/pbmtext.1 new file mode 100644 index 00000000..762f5c7c --- /dev/null +++ b/upstream/opensuse-tumbleweed/man1/pbmtext.1 @@ -0,0 +1,538 @@ +\ +.\" 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 "Pbmtext User Manual" 0 "29 May 2020" "netpbm documentation" + +.SH NAME +pbmtext - render text into a PBM image + +.UN synopsis +.SH SYNOPSIS + +\fBpbmtext\fP +[\fB-wchar\fP] +[\fB-font\fP \fIfontfile\fP] +[\fB-builtin\fP \fIfontname\fP] +[\fB-space\fP \fIpixels\fP] +[\fB-lspace\fP \fIpixels\fP] +[\fB-nomargins\fP] +[\fB-width\fP \fIpixels\fP] +[\fB-load-entire-font\fP] +[\fB-verbose\fP] +[\fB-dry-run\fP] +[\fB-text-dump\fP] +[\fItext\fP] +.PP +Minimum unique abbreviation of option is acceptable. You may use double +hyphens instead of single hyphen to denote options. You may use white +space in place of the equals sign to separate an option name from its value. + + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBpbmtext\fP takes the specified text, either a single line from +the command line or multiple lines from standard input, and renders it +into a PBM graphical image. +.PP +The text rendered is all the non-option command line arguments, separated +by spaces, except that if there are no non-option command line arguments, it +is Standard Input. + +.PP +In the image, each line of input is a line of output. Lines are + delimited by newline characters. +.PP +The program renders any character in an input line that is not in the font + as a space. Note that control characters usually aren't in the font, but + some fonts have glyphs for them. The newline characters that delimit lines + in of Standard Input are not in any line. +.PP +Tab characters are rendered as a number of spaces; any entry in the font + for the tab code point is irrelevant. The number of spaces is such as to + create tab stops every 8 characters. Note that this is not useful if the + font is proportional. + +.PP +The image is just wide enough for the longest line of text, plus +margins, and just high enough to contain the lines of text, plus +margins. +.PP +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. You can use the \fB-nomargins\fP option +to eliminate the margins. +.PP +\fBpbmtext\fP renders left to right. It cannot render vertically +or right to left. +.PP +\fBpbmtextps\fP does the same thing as \fBpbmtext\fP, but uses +Ghostscript to generate the characters, which means you can use +Postscript fonts. But it also means you have to have Ghostscript +installed and it isn't as fast. Also, \fBpbmtextps\fP generates only +one line of text, whereas \fBpbmtext\fP can create multiple lines. +.PP +\fBpbmtext\fP is meant for simple text. If you're working with +a \fIdocument\fP, you would be better off using a document formatting +program to "print" to a Postscript file, then feeding that Postscript +to \fBpstopnm\fP. + +.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 +\&), \fBpbmtext\fP recognizes the following +command line options: + + + +.TP +\fB-wchar\fP +.sp +By default, \fBpbmtext\fP takes a single-byte character stream as input. +When you specify \fB-wchar\fP, it treats input text as a multibyte character +stream encoded according to the current locale. Normally, the user would +supply a BDF font file encoded in ISO-10646-1 with a \fB-font\fP option. +.sp +With \fB-wchar\fP, you cannot supply the text on the command line; it must +be fed from standard input. +.sp +This option was new in Netpbm 10.82 (March 2018). + + +.TP +\fB-font\fP +.TP +\fB-builtin\fP +\fB-builtin\fP selects a font among those built into Netpbm. + +\fB-font\fP selects a font that you supply yourself either as an X Window +System BDF (Bitmap Distribution Format) file or as a PBM file in a special +form. +.sp +The default is the built in font "bdf." +.sp +"bdf" is Times-Roman 15 pixels high. (That's about 14 +point type printed at 75 dpi). +.sp +"fixed" is a built in fixed width font. +.sp +For information about other fonts, and how to make one of your own, +see +.UR #fonts +Fonts +.UE +\& below. + + +.TP +\fB-space\fP \fIpixels\fP + Add \fIpixels\fP 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. +.sp +\fIpixels\fP may be fractional, in which case the number of +pixels added varies so as to achieve the specified average. For +example \fB-space=1.5\fP causes half the spaces to be 1 pixel and +half to be 2 pixels. +.sp +\fIpixels\fP 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 +\fB-lspace\fP \fIpixels\fP + Add \fIpixels\fP 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. +.sp +\fIpixels\fP must be a whole number. +.sp +\fIpixels\fP 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. + +.TP +\fB-nomargins\fP +By default, \fBpbmtext\fP adds margins all around the image as +described above. This option causes \fBpbmtext\fP not to add any +margins. +.sp +Note that there may still be space beyond the edges of the type +because a character itself may include space at its edges. To eliminate +all surrounding background, so the type touches all four edges of the +image, use \fBpnmcrop\fP. + +.TP +\fB-width\fP \fIpixels\fP +This specifies how much horizontal space the text is supposed to fit +into. +.sp +If the input is one line, \fBpbmtext\fP breaks it into multiple +lines as needed to fit the specified width. It breaks it between +characters, but does not pay attention to white space; it may break in +the middle of a word and a line may begin or end with white space. +.sp +If the input is multiple lines, \fBpbmtext\fP assumes you already +have line breaks where they make sense, and \fBpbmtext\fP simply +truncates each line as needed to fit the specified width. + +.TP +\fB-load-entire-font\fP + +When you use a BDF font, \fBpbmtext\fP will normally load from the font + only the characters needed for your text, not wasting time loading other + characters. With this option, \fBpbmtext\fP will instead read the entire + font. It won't make any difference in the rendered output, but it lets + you check the integrity of the font file. +.sp +This option was new in Netpbm 10.91 (June 2020). Before that, +\fBpbmtext\fP always reads the entire font. + +.TP +\fB-verbose\fP +This makes \fBpbmtext\fP issue informtional messages about its processing. + +.TP +\fB-dry-run\fP +.sp +With this option, instead of outputting an image of the text, +\fBpbmtext\fP just writes to Standard Output a message telling the dimensions +of the image it would have produced. +.sp +You can specify only one of \fB-dry-run\fP and \fB-text-dump\fP. +.sp +This option was new in Netpbm 10.75 (June 2016). + +.TP +\fB-text-dump\fP +This option causes \fBpbmtext\fP just to write to Standard Output the text in +ASCII that would be rendered. The output reflects any text formatting, +unprintable character substitution, tab expansion, etc. It is for diagnosing +problems. This option was new in Netpbm 10.82 (March 2018). +.sp +When \fB-wchar\fP is in effect, the output text will be in the encoding +specified by the current locale. +.sp +You can specify only one of \fB-dry-run\fP and \fB-text-dump\fP. +.sp +This option was new in Netpbm 10.82 (March 2018). + + + + +.UN usage +.SH USAGE +.PP +Often, you want to place text over another image. One way to do this is +with \fBppmlabel\fP. For more flexible (but complex) drawing of text on an +image, there is \fBppmdraw\fP. These do not give you the font options that +\fBpbmtext\fP does, though. +.PP +Another way is to use \fBpbmtext\fP to create an image containing +the text, then use \fBpamcomp\fP 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 +\fBpamcomp\fP a mask, via its \fB-alpha\fP option. You can just use +the text image itself as the mask, as long as you also specify the +\fB-invert\fP option to \fBpamcomp\fP. +.PP +If you want to overlay colored text instead of black, just use +\fBppmchange\fP 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 transparency mask. +.PP +If you want the text at an angle, use \fBpnmrotate\fP on the text +image (and transparency mask) before overlaying. + +.UN fonts +.SH FONTS +.PP +There are three kinds of fonts you an use with \fBpbmtext\fP: + + +.IP \(bu +built in +.IP \(bu +BDF +.IP \(bu +PBM + + +.SS Built In Fonts +.PP +There are two built in fonts: \fBbdf\fP and \fBfixed\fP. You select +these fonts with a \fB-builtin\fP option. +.PP +\fBbdf\fP is the default when you specify no font information on the +command line. \fIThe naming reflects the fact that it shares many +characteristics of BDF style fonts. When this font was implemented, +\fBpbmtext\fP did not have the ability to read arbitrary BDF fonts +specified by the \fB-font\fP option. There is no external font file +involved.\fP +.PP +\fBbdf\fP is encoded in ISO 8859-1 (Latin 1, 8-bit). In addition to +English it can handle most West European languages (Spanish, French, German, +Swedish ...) This set lacks the Euro currency sign. +.PP +\fBfixed\fP is ASCII (7-bit) only. +.PP +While it is not an error to do so, you should not use the above built-in +fonts with \fB-wchar\fP. + + +.SS BDF Font +.PP +BDF is an ancient font format that at one time was standard for the +X Window System. Now, you don't see it very often, but you can find +some BDF fonts on the +.UR http://cvsweb.xfree86.org/cvsweb/xc/fonts/bdf/ +Xfree86 +.UE +\& +web site. +.PP +You can get the full package of the BDF fonts from XFree86 (see +above) from the +.UR http://netpbm.sourceforge.net/bdffont.tgz +Netpbm web site +.UE +\&. + +.SS PBM Font +.PP +To create a font as a PBM file (to use with the \fB-font\fP +option), you just create a PBM image of the text matrix below. +.PP +The first step is to display text matrix below on the screen, +e.g. in an X11 window. + +.nf + + M ",/^_[`jpqy| M + + / !"#$%&'()*+ / + < ,-./01234567 < + > 89:;<=>?@ABC > + @ DEFGHIJKLMNO @ + _ PQRSTUVWXYZ[ _ + { \e]^_`abcdefg { + } hijklmnopqrs } + ~ tuvwxyz{|}~ ~ + + M ",/^_[`jpqy| M + + +.fi +.PP +Make sure it's a fixed width font -- This should display as a +perfect rectangle. +.PP +Also, try to use a simple display program. Pbmtext divides this +into a matrix of cells, all the same size, each containing one +character, so it is important that whatever you use to display it +display with uniform horizontal and vertical spacing. Fancy word +processing programs sometimes stretch characters in both directions to +fit certain dimensions, and that won't work. Sometimes a display +program scales a font to show a character larger or smaller than its +natural size. That too won't often work because the rounding involved +in such scaling causes non-uniform distances between characters. +.PP +If you display the text matrix improperly, the usual symptom is +that when you try to use the font, \fBpbmtext\fP fails with an error +message telling you that the number of lines in the font isn't +divisible by 11, or it can't find the blank band around the inner +rectangle. Sometimes the symptom is that one of the characters +displays with a piece of the character that is next to it in the +matrix. For example, "l" might display with a little piece +of the "m" attached on its right. +.PP +Do a screen grab or window dump of that text, using for instance +\fBxwd\fP, \fBxgrabsc\fP, or \fBscreendump\fP. Convert the result into a +pbm file. If necessary, use \fBpamcut\fP to remove anything you grabbed in +addition to the text pictured above (or be a wimp and use a graphical editor +such as Gimp). Finally, run it through \fBpnmcrop\fP to make sure the edges +are right up against the text. \fBpbmtext\fP can figure out the sizes and +spacings from that. +.PP +There are some historical computer fonts, such as that used by the original +IBM PC, in the form that you can screen-grab and turn into a PBM font file +available from +.BR "Stewart +C Russell" (1)\c +\&. There are fonts with various duodecimal digit glyphs at +.UR http://treisaran.deviantart.com/gallery/38695571/NetPBM-Fonts + treisara.deviantart.com +.UE +\&. +.PP +PBM fonts cannot be used with \fB-wchar\fP. + + + +.UN multibyte +.SH MULTI-BYTE INPUT +.PP +In the past, English text was encoded in 7-bit ASCII. 8-bit and multibyte +encodings were needed only for non-English languages. This is not the case +today. As of this writing, 90% of all web pages are encoded in UTF-8. While +many of them are actually restricted to 7-bit ASCII, which is a subset of +UTF-8, English text encoded in UTF-8 commonly employs "66 99" style quotation +marks, which do not appear in ASCII. +.PP +If your input text is UTF-8, you should use \fB-wchar\fP. You may have to +tweak the locale setting. \fBpbmtext\fP recognizes code points up to 65535. +This is sufficient for the vast majority of text written in modern languages. +.PP +In the default single-byte (or "narrow") character +mode, \fBpbmtext\fP can handle 7-bit and 8-bit character sets. +Examples are ASCII, ISO 8859 family, koi8-r/u and VISCII. It is up to +the user to supply a BDF file covering the necessary glyphs with the +"-font" option. The font file must be in the right encoding. +.PP +\fBpbmtext\fP does not inspect the encoding of the font file. + + +.UN limitations +.SH LIMITATIONS +.PP +If the text is from Standard Input, no line may be longer than 4999 +characters. If one is, the program aborts with an appropriate error message. +.PP +If the text is from Standard Input and contains a null character, the +results are abnormal. Lines may be truncated, and a single line may be +considered multiple lines. Normal text does not contain null characters, so +this isn't a big problem. + + +.UN tips +.SH TIPS +.PP +If you get garbled output, check the input text encoding and font file +encoding. When using \fB-wchar\fP, also check the current locale. +.PP +To convert the encoding of a text file, use \fBiconv\fP or \fBluit\fP. +.PP +To check the encoding of a BDF file, examine the CHARSET_REGISTRY +line and the next line, which should be CHARSET_ENCODING: + +.nf +\f(CW + $ grep -A1 CHARSET_REGISTRY font-a.bdf + CHARSET_REGISTRY "ISO8859" + CHARSET_ENCODING "1" + + $ grep -A1 CHARSET_REGISTRY font-b.bdf + CHARSET_REGISTRY "ISO10646" + CHARSET_ENCODING "1" +\fP + +.fi +.PP +The latter is Unicode. BDF files coded in ISO 16046-1 usually work for +Western European languages, because ISO 16046-1 expands ISO 8859-1 (also +called "Latin-1") while maintaining the first 256 code points. ISO +8859-1 itself is a superset of ASCII. Run the above command and verify the +necessary glyphs are present. +.PP +\fBIMPORTANT:\fP For input text, a different rule applies. If +you feed ISO 8859-1 text to \fBpbmtext -wchar\fP set up for UTF-8, the output +will be garbled. Unicode provides several encoding schemes and different ones +are in effect for input text and font. \fIThe difference between Unicode +codepoint and the various encodings is a formidable stumbling block; beware of +web pages that get the concept wrong.\fP +.PP +75% of the BDF files in the font collection available from +.UR http://netpbm.sourceforge.net/bdffont.tgz +the Netpbm website +.UE +\& are +in ISO 10646-1. Many have the Euro sign, Greek letters, etc., but they are +placed at code points available to \fBpbmtext\fP only with \fB-wchar\fP. +.PP +Before \fBpbmtext\fP had the \fB-wchar\fP option, one often had to +produce a BDF file in an 8-bit encoding from a master BDF file encoded in ISO +10646-1. +.PP +There are several programs that perform BDF encoding conversion. If you +have the X Window System installed, first look for \fBucs2any\fP. If you +don't, you can download \fBucs2any.pl\fP from +.BR "Unicode fonts and tools +for X11" (1)\c +\&. This website has much useful information on fonts. +.PP +Another converter is \fBtrbdf\fP, included in the "trscripts" +package, available in some GNU/Linux distributions. +.PP +BDF files encoded in ISO 8859-2, ISO 8859-7, koi8-r, etc. are available +from +.BR "ISO 8859 Alphabet +Soup" (1)\c +\& and its sister page +.BR "The Cyrillic Charset +Soup" (1)\c +\&. Though the information is dated, these pages give a good overview +of 8-bit character sets. +.PP +To convert OTF or TTF font files to BDF, use +.UR http://www.math.nmsu.edu/~mleisher/Software/otf2bdf + \fBotf2bdf\fP by Mike Leisher +.UE +\&. + + +.UN seealso +.SH SEE ALSO +.BR "pbmtextps" (1)\c +\&, +.BR "pamcut" (1)\c +\&, +.BR "pnmcrop" (1)\c +\&, +.BR "pamcomp" (1)\c +\&, +.BR "ppmchange" (1)\c +\&, +.BR "pnmrotate" (1)\c +\&, +.BR "ppmlabel" (1)\c +\&, +.BR "ppmdraw" (1)\c +\&, +.BR "pstopnm" (1)\c +\&, +.BR "pbm" (5)\c +\&, +\fB +.UR http://www.pango.org +Pango +.UE +\&\fP, +\fB +.UR http://cairographics.org +Cairo +.UE +\&\fP + +.UN author +.SH AUTHOR + +Copyright (C) 1993 by Jef Poskanzer and George Phillips +.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/pbmtext.html +.PP
\ No newline at end of file |