# NAME

vplottext - A guide to using the Hershey fonts in vplot

# DESCRIPTION

Vplot fonts are mixtures of vectors and filled areas which simulate typeset fonts on graphics devices. Since they are not raster, they can be arbitrarily scaled, stretched, skewed, and rotated, and can be plotted on any device.

There are 17 fonts. Font 0 is just the regular old PEN font we've been using all along. The default font is device and installation dependent, or can be set from the command line (see options below). Here is a complete list of fonts and their number:

Font 0 was designed by Rob Clayton at Stanford. Fonts 1 through 16 are debugged versions of the Hershey' fonts available from mod.sources. In order to have permission to use these fonts, I must now display this message:

  - The Hershey Fonts were originally created by Dr.


    A. V. Hershey while working at the U. S.


    National Bureau of Standards.


# INTERFACE

This section describes the control sequences which are accessible to any user of vplot text, via whatever program.

Vplot text recognizes \e' as a special character used to signal the start of an escape sequence. There are two sorts of escape sequences, those that take an argument and those that do not.

Here is a complete list of escape sequences that do not take an argument:

\e< Back up one interletter space
\e^ Raise one half of a capital letter height
\e_ Lower one half of a capital letter height
\eg Continue processing text, but don't actually print it (ghostify it').

This is useful if you want to leave space to go back and add something by hand. =item \eG Start printing text again \en Newline

\eh Backspace (control-h also works) back up over the last character
\e- Does nothing; used to prevent a group of characters from being formed into a ligature.
\e\e Print a backslash

The following take an integer argument immediately after, with a required space after the integer to delineate the end. This space is not printed.

\es Size change. Change to this percent of the size set in the text vplot call. \es100 restores the default height.
\ef Add this to current fatness. Goes out of effect when text printing is finished.
\eF Switch to this font number. (-1 restores the default font).
\ek Move by this many space widths to the right (in percent; 100 = one space width). Negative numbers are allowed (moves left).
\er Move up this many character heights (in percent; 100 = the height of a standard capital letter, such as A'). Negative numbers are allowed (moves down).
\ev Print this ASCII character number in the current font, stripping it of any special meaning. This and ligatures are the only way that glyphs numbered greater than 255 are available.
\ec Switch to this color. -1 restores the current drawing color. Vplot's current drawing color is not changed by changing the color inside text. \em Save current position in this number register.
\eM Restore position saved in this number register.

# EXAMPLES

Since programs such as graph' do not interpret text themselves, but rely on vplot to do it, the above control sequences may simply be used wherever any graphics text is used. For example, instead of specifying as an option to graph label=beta', you can specify label=\eF9 b' and actually get the Greek letter beta from the Greek Simplex font.

  Here are some more examples:


  To get an integral sign:


  \eF15 \ev168


  Translation: Switch to font 15 (math symbols), print character #168
(integral sign).


  To get X squared plus Y squared':


  X\e^2\e_ + Y\e^2


  Translation: Print X, go up half, print 2, go back down half, print +,
print Y, go up half, print 2.


  As an advanced example, to get A sub b sup beta':


  A\em1 \e_b\eM1 \e^\eF9 b


  Translation: Do A, save this spot, go down half, do b, restore the
saved spot, go up half, switch to font 9 (Greek Simplex) do beta.
(Notice the use of marks to stack characters on top of each other.)


  Warning: \e is a special character in C.  To get a backslash, you
have to use \e\e.


# GENERIC PEN OPTIONS

txsquare=yes

      Xscale and yscale would distort text along with the entire
plot if they were applied completely consistently,
which is usually not desired.
To avoid this, the option
B<txsquare=yes'',>
is defaulted. This causes
xscale and yscale to be forced
equal to the minimum of the two
for the purposes of text.
If B<txsquare=no''>
is set, then text will stretch consistently with everything
else.

txfont=font_number

      The default is device and installation
dependent.  Generally, screen devices will default to the pen'
font since it is by far the fastest to draw, and hardcopy
devices will default to either roman simplex or roman complex
since these are the closest to looking like standard typeset
text.  Out-of-range font numbers (starting at 100) may be used
in a device-dependent fashion to access hardware fonts on
devices that have them. Devices that don't have hardware fonts
will use the font number modulo 100.  Fonts 0-99 are guaranteed
device-independent.

txprec=0

      Txprec specifies the default text precision (a GKS term).
Possible values are character (0), string (1), and stroke (2).
For vector fonts, the text precision parameter is ignored
except that ligatures are only enabled at precision 2.  The
precision parameter may be significant if device-dependent
hardware fonts are used, however.  The default precision is
device and installation dependent.

txovly=0

      Txovly sets the default text overlay mode.
This controls whether or not to clear out an area behind the
text before writing it, and whether or not to put a box
around it.  Overlay modes 1 and 3 draw a box, and
modes 2 and 3 shade the inside of the box with the background
color.  The default text overlay mode is 0 (do nothing).
All text overlay modes may not be supported on all devices.
(Some devices cannot shade to background color, for example.)


      The default font, default precision, and default text overlay
mode may all be reset by the appropriate vplot command.

fontN=file_name

      The binary format vplot font file for font number N is
located in file_name.  If the font number is not one
normally defined on the system, file_name defaults to
fontN, where again N is the font number. If the device
does not have hardware fonts, the font number modulo 100
will be used for all internal purposes (so fonts 201 and 101
must be the same, for example). The N in the above option
will still be the original font number, however. Fonts that
are included at compile time are hardwired
and cannot be changed.


# LIGATURES

Fonts may specify that certain combinations of adjacent glyphs be combined into a single new glyph whenever they occur. For example, ffi' in font 3 (it's a ligature in troff, too). This takes place automatically at precision 2. The only fonts which currently contain ligatures are the Roman Complex, Italic Complex, and Cyrillic Complex fonts. You can prevent a group of letters from being formed into a ligature by breaking them up using the \e-'' special sequence (just like in TeX). (Ligatures may be used in fonts for foreign languages to good effect to automatically de-transliterate English approximations. For example, sh' in the Cyrillic font automatically comes out as a single Shah character. KHrushchev', for example, contains only 6 glyphs: KH-r-u-shch-e-v. The K and H here are both capitalized since they are both part of the first character. The Tests' directory contains the example TEST_Cyrillic which shows how to generate every letter in the Cyrillic alphabet.)

# TEXT JUSTIFICATION

Text justification is set by the appropriate command in vplot, and follows the GKS standard. Since this text routine allows character size and active font to be changed within a single text string, the GKS standard is extended so that TOP' and BOTTOM' alignments align on the highest top and the lowest bottom of the characters used. (Note that this makes the alignment font and size dependent, but not dependent on the actual characters used.) The CAP' and HALF' alignments are determined by those for the default font.

All sizes of all fonts are aligned together by their baselines.

Horizontal alignment is based according to the beginning and ending horizontal positions. You can use marks to make the ending position be anywhere in the string you wish.

A SYMBOL' justification mode has also been added to those defined by GKS. Each glyph has a hot spot' defined, which is where the glyph is to be centered if it is used as a symbol. The last printable character in a string is the character centered on as the symbol. To center on a character in the middle of the string as a symbol, mark the spot with the \em command immediately after that character and then restore that location at the end of the string with the \eM command. That character is now the last character' as far as all centering is concerned. Size changes and horizontal shifts are taken into account in the symbol justification mode, but shifts up and down are not.

Vplot polymarkers are drawn by setting the SYMBOL text justification mode, setting the correct font, creating a special single-character string, and then calling the text routine to draw the symbol.

# DIAGNOSTICS

Nonexistent glyphs are rendered as a special error' glyph. Which glyph is used for this is installation dependent, and is set by defines in gentext.c. As distributed, it is glyph 30 in font 0, which is a ?' inside a diamond. (I stole this idea from the Imagen laser printer.) An error message will be produced the first time that a nonexistent glyph is referenced. (Only the first time so that you don't get overwhelmed with error messages if you're trying to use a font that doesn't exist on that system.) Attempts to use nonexistent fonts produce an error message and font 0 (or whatever other font has been designated as the error font in gentext.c) is used instead.

Various other non-fatal errors can occur and all give self-explanatory error messages.

# FONT FILES

Font files used by the vplot text subroutine gentext' are kept in graphics /vplot/filters/include/vplotfonts/*. There are two forms for each font, an include' form and a binary' form. The include form is compiled in as an #include file into gentext. This is more efficient, but makes the executable code considerably longer and slows down compilation. The binary form is loaded on the fly as needed at runtime. Which method is used for which font is system dependent and is determined by the file .../vplot/include/font_definitions.h.

If for some reason when you run a pen filter it cannot find the runtime-loaded fonts (or if you want to set up your own version of those fonts) you can set your own vplot binary font directory using the environmental variable VPLOTFONTDIR''. (Note the font directory name in the variable will usually end with a slash!)

# ASSOCIATED PROGRAMS

The subroutine gentext.c is the device-independent generic subroutine that vplot uses to draw vector fonts. Gentext.c is constructed in such a way that it could easily be fit into a GKS package. While the standard text command in Vplot thinks in terms of text orientation' and text size', gentext thinks in terms of character up vectors' and character path vectors'. Squashed, slanted, etc, text can be produced by having these two vectors not be perpendicular or not the same length. An alternative text command is provided that uses this more general method of text specification.

The program makefont.c takes a vplot font' and encodes it into the forms required by gentext. The format of a vplot font' is designed such that it can be read into the program plas' and then piped into a vplot filter. IE, the command

plas < cyrilc.vplot_font | ?pen xcenter=0 ycenter=0 scale=50 pause=1

will display each glyph in the cyrillic font, one per second.

Fonts 10 |plas|Tube will display the numbers of all greek letters fonts.

The exact format of a vplot font' file is given in comments at the beginning of makefont.c, and the file pen.vplot_font serves as an example. Since vplot_fonts are just open-format vplot files, it is very easy to create your own special purpose glyphs, markers, or fonts and add these to the system.

The program hertovplot.c converts Hershey' font data as distributed by mod.sources (mod.sources is a UNIX network news' group for distributing useful UNIX software.) into vplot fonts. Its use is described in comments at the beginning of the program. The program hertogrid.c draws all the glyphs in a Hershey glyph file on a grid, labeling each glyph with its number. (The Hershey glyph files have to be organized into reasonable fonts by hand! The organization of my fonts mostly follows those provided by Mr. Hurt, but I have added in a few things he missed and reordered the non-English fonts to make more sense. I have stolen bits of Mr. Hurt's code to write hertovplot.c and hertogrid.c.)

# FONT INSTALLATION

To install all the fonts, you must first obtain the Hershey fonts for yourself as distributed by mod.sources (if you don't know how to get stuff from them, then how did you get this file that you're reading now?). Follow the instructions to create the four .oc' files, and copy these into the .../vplot/Hershey directory. Do not copy the .hmp' files. Follow the instructions you will find in the file .../vplot/Hershey/README to make all the required vplot_font's. (Note that pen.vplot_font is not part of the Hershey font distribution. This font was created by Rob Clayton around 1980, and slightly modified by Joe Dellinger in 1986.) Once you have done this, go into the .../vplot/filters/include/vplotfonts directory, and do make'. This will create the required .include' and .bin' fonts.

# AUTHOR

Joe Dellinger (joe@hanauma.stanford.edu, convex!convexw!hanauma!joe, decvax!hanauma!joe) You may ask me for advice if you wish to help do any of the things in the wish list below.

# BUGS

The letter J' in the Roman Triplex font in the Hershey font distribution has mangled width information. The vplot font for this font has to be edited by hand to correct this mistake.

Gentext.c does not yet support all the required GKS features. However, as all the internal calculations are done in a way consistent with the GKS model modifying the code to support these is a very straightforward job which I leave to someone else.

Somebody should make sure that all the hot spots' defined for characters are reasonable. (The hot spot' is the point that is aligned on when symbol alignment mode is used.) (The ones installed now are the defaults chosen by makefont.c.) Somebody should create a special polymarker' font. Currently several of the more esoteric symbols called by the vplot polymarker command are not very well centered (notably triangles).

Somebody should write an interactive program to create new glyphs with.

Somebody should turn some of the better Hershey vector fonts into filled-area fonts. (Unfortunately, Mr. Hershey didn't see fit to order his vectors in such a way as to make this easy.) The only thing lacking is the font itself, because vplot itself already supports arbitrary mixtures of filled-areas and vectors in fonts. Currently there are just a few glyphs containing filled areas in font 0, as examples showing how to do it.

Dr. Geller (the first tenured American professor at a Japanese university, and a former Stanford Earth Sciences professor) should have his students create a katakana and a hirigana font. Ligatures can be used to pair the appropriate consonant-vowel pairs. There are also quite a few Kanji glyphs available as well, from which a Kanji font could be constructed. A ligature could be constructed to turn each English word into its Kanji equivalent! (The number of glyphs in a font is not limited to 256! That's why I did things that way.)

Somebody should extend the way ligatures are read from vplot font files, so that you can just give the ASCII character itself instead of the glyph number if one exists. Since I only had a few ligatures I didn't want to bother with this.

graphics/vplot