02 October 2002
Contact: danielh@crosslink.net
GIF_TEXT: A Graphical Text Generator for the WWW
GIF_TEXT, ver 1.4a, is an OS/2 utility that will convert text strings into
.GIF images "on the fly". Using one of the several included
"alphabytes" it's easy to make attractive banners, headers,
and other messages for your web site. For example, GIF_TEXT
can dynamically generate the time and date -- you can use GIF_TEXT as a
graphical digital-clock.
GIF_TEXT can be run in three different ways:
i) as an addon for the SREhttp/2 web server -- the most features
ii) as a CGI-BIN script for OS/2 web servers -- many features
iii) as a standalone utility, run from an OS/2 command prompt -- fairly
primitive user inteface (no GUI), but adequate for simple work
Once installed GIF_TEXT is easy to invoke. For example, if run as an
SREhttp/2 addon, just request MKGIFRM.HTM using your favorite
browser -- MKGIFRM.HTM provides a complete front-end to GIF_Text.
Or, you can include an in-line image html element in your HTML document.
For example:
will generate a 300 pixel wide image with the word "HELLO" (not including
the quotes) written using the "enviro" alphabyte.
And, of course, GIF_TEXT is free (though you should read the
acknowledgments section regarding RXGD101.DLL and the various
"alphabytes").
Note: You can get the latest version of GIF_TEXT from
http://srehttp2.srehttp.org/apps/gif_text/
------------------------------------------------------
Table of Contents:
I. Installaton
II. Using GIF_TEXT
IIa. Short descripton of Request Options
II.b Long description of Request Options
IIb.1 Required options
IIb.2 Recommended options
IIb.3 Useful options
IIb.4 Infrequently used options
III. Technical notes
IIIa. Basic File matching algorithim
IIIb. Adding an alphabyte
IIIc. Adding a background
IIId. Adding a complete font
IIIe. Adding a TTF font
IIIf. Caching images
IIIg. On using GIF_TEXT as a "hit counter"
IIIh. Using color slides
IIIi. Switching fonts in mid-message
IIIj. Remapping fonts to a different code page
IV. Sample of a FONT_INDEX
IVa. Multiple variants of a "complete font"
IVb. Example of adding a new alphabyte
V. Acknowledgments
------------------------------------------------------
I. Installation
To install GIF_TEXT:
1) UNZIP GIF_TEXT_xxx to an empty temporary directory.
2a) If you are installing GIF_TEXT as an SREhttp/2 addon:
run the INSTALL.CMD program (located in the
directory created in step 1 above).
2b) Otherwise, to run as a CGI-BIN script (under SREhttp/2, or some other OS/2 web server)
i) Copy GIF_TEXT.CMD and MKGIFTXT.CMD to your CGI-BIN scripts directory.
ii) Copy RXGDUTIL.DLL and RXTTF.DLL to a directory in the
OS/2 LIBPATH (for example, C:\OS2\DLL).
iii) Create an ALPHABYT directory somewhere on your server's machine
Copy ALPHABYT.ZIP to this ALPHABYT directory.
CD to this ALPHABYT directory, and UNZIP ALPHABYT.
UNZIP will create several subdirectories under ALPHABYT, containing sample
"alphabytes", "complete fonts', backgrounds, buttons, and color slides.
iv) With your favorite text editor, edit GIF_TEXT.CMD. You MUST
set the value of the ALPHA_DIR_ROOT variable to
be the above "ALPHABYT" directory
You might also want to change some of the other values.
Notes:
* in addition to being the "root" of the alphabytes, etc.;
GIF_TEXT uses the _CACHE subdirectory of the ALPHA_DIR_ROOT
directory for temporary storage.
* on most systems, the x:\os2\mdos\winos2\system directory contains
several ttf fonts. You might want to copy them to the TTF
directory of the ALPHA_DIR_ROOT directory -- or change the value
of the TTT_DIR_ROOT parameter.
v) To setup the (optional) MkGifTxt "web callable front end":
Copy the several Mk*.CGI files to MK*.HTM to a web accessible directory.
Also copy GIF_TEXT.TXT and GIF_TEXT.GIF to this directory.
There are several parameters in MKGIFTXT.CMD that you
should change. In particular you MUST set the ALPHA_DIR_ROOT
parmeter to be the same as its value in GIF_TEXT.CMD
vi) To setup the (optional) MkBUTTON "front end"
Copy MKButton.HTM to a web accessible directory
Copy ALLBUT1.GIF to the IMGS\ subdirectory under the root
of your web directory.
That's basically it. If you use non-english code pages, you might
want to check section IIIj for hints on remapping messages to
a different code page. YOu might also want to check the HTML_URI
and SCRIPT_URI parameters in MKGIFTXT.CMD.
Reminder:
if you "installed by hand" DON"T FORGET TO DO set
ALPHA_DIR_ROOT in GIF_TEXT.CMD (and in MKGIFTXT.CMD) !
You can point your browser at MKGIFTXT.HTM or MKGIFRM.HTM
and try it out: it's a nice way to quickly create "banners" that
you can use as static images.
Or, you can include  CD (change directory) to the directory that you installed GIF_TEXT
ii) enter GIF_TEXT (at the prompt)
-----------------------------------------------------
II. Using GIF_TEXT
GIF_TEXT is often invoked using an IMG element (in an HTML document)
that contains special )
The request line options in the first example:
text=Welcome+surfers&font=enviro&width=300&as=MESS.GIF
and in the second example:
text="The time is:$T"&font=andy01&time_Fmt=N&as=MESS.GIF
* When using a CGI-BIN capable server:
(the only difference is the inclusion of a /CGI-BIN before the /GIF_TEXT?)
* HINT: the as=MESS.GIF at the end is strictly optional: it is only included
to "force" certain browsers to treat the returned image as a .GIF
file.
* When run from an OS/2 command line, you can either run GIF_TEXT without
an options, or you can specify a set of options. When run without
options, GIF_TEXT will ask a series of questions; such as the which
font to use, the background, color slide, and image size.
When run with options, GIF_TEXT will not prompt you for input, it
will read them from the option list.
The option list should be a space delimited list, with the format:
var=value var=value
For example:
D:\GIFTEXT>gif_text message=helo font=revue back=backs/pap_gry2 as=foo.gif
Note that you MUST include the as=filename option.
----------------
IIa. Short descripton of GIF_TEXT "request line" Options:
Required:
TEXT : The message to be converted into a graphic.
FONT : The alphabyte font to use.
Optional, and recommended:
WIDTH: The width, in pixels, of the image
HEIGHT: The height, in pixels, of the image
Optional:
AS: File to save GIF image to (command line mode only),
CACHE: Return a previously created image
TIME_FMT: The format used to display the time.
DATE_FMT: The format used to display the date.
BACK : A background image for the text
BACK_SCALE: Scale or tile the background image
X_F: Size of frame (left and right)
Y_F: Size of frame (top and bottom)
X_OF: Left/right offset
Y_OF: Up/down offset
X_SCA: A list of "width scales"
Y_SCA: A list of "height scales"
Y_VAL: Type of vertical (character box) alignment
LINE_J: Type of horizontal (line) justification
LINE_SEP: Spacing between lines (in pixels)
SLIDE: Name of a color slide .GIF file
SLIDE_T: Threshold rules (& parameters) for color slides
SLIDE_V: Vertical mapping rule for color slides
SLIDE_H: Horizontal mapping rule for color slides
SLIDE_C: Specify "center coordinates" when using a color slide
FIGDIST_T: Method for computing color slide distances
SLIDE_SI: Size of "user specified color slide" (# pixels and # colors)
SLIDE_RE: Red color parameters for "created slide"
SLIDE_GR: Green color parameters for "created slide"
SLIDE_BL: Blue color parameters for "created slide"
SLIDE_PR: Probability parameters for "using slide value"
Optional, infrequently used:
FONT_NAME: The "name" of the alphabyte font
FONT_INDEX: The "index file" for the alphabyte font
TTF_FONT: The TTF font to use
TTF_FONT_SIZE: The size (in points) of the TTF font
TRANSPARENT: The index of the transparent color
BACKCOLOR: The background RGB colors.
TEXTCOLOR: The default-font RGB colors
LITERAL: Supress $n code interpretation (rarely used)
MANY_C: How to choose from a set of complete fonts (multiple complete)
SEND: Select "send pieces as they become available" mode
Reminder:
As noted above,several of these options will override defaults.
There are two kinds of defaults:
General: Set by variables contained in the user configurable
parameters section of GIF_TEXT.CMD.
Alphabyte specific: Set in the alphabyte's FONT_INDEX file.
----------------
II.b Long description of Options:
IIb.1 ------------ Required
TEXT: The message to be converted into a graphic.
Example: TEXT=This+is+a+message
TEXT should contain an arbitrarily long message. This message
should be properly "URL encoded": spaces should be represented by
+ characters, and certain special characters (such as &, ?, and ")
should be coded using the approprate encoding (i.e.; %26 for &).
In addition to the keyboard characters, you can include special
codes. The most useful special codes are:
$t -- include the current time
$d -- include the current date.
$$ -- the code for the $ character.
$b -- filled box: a "rectangular space" filled with the textcolor
$n -- new line. Use $n special codes to create a multiple
line image. Note that CRLF's (10 and 13 hex) are stripped
from the text -- to signify a new line, you must use
$N.
$F(fontname) -- switch font to the fontname font.
$#nnn; -- an ascii code -- nnn is a number between 000 and 255
$#nnx; -- an ascii code -- nn is a hex number between 00 and ff
Example: This is umlaut u: $#252;
The $#fcx; is umlaut u.
You can try these with the COURIER font (note that the ascii
codes "escaped" by these $#nnn; sequences matcn ##nn entries
in COURIER.IND).
CAUTION: Do NOT forget to end these $#nnn with a semi-colon!
You can also define your own "special codes". For example,
when using the ENVIRO font, a $10 is interpreted as a left quote,
and a $11 as a right quote.
For further details see the "technical notes" section below.
FONT: The "alphabyte" or "complete" font to use.
Example: FONT=revue
Note: either FONT,or TTF_FONT (and TTF_FONT_SIZE), should
always be specified
The FONT argument should point to a subdirectory (of the ALPHA_DIR_ROOT
directory) This subdirectory should contain the various .GIF
and .IND files that comprise an alphabyte, or a single .GIF file
that contains a "complete font".
Since most alphabytes do NOT contain .GIF files for all keyboard
characters, GIF_TEXT will perform appropriate substitutions.
In particular:
a) upper case characters will be used if there is
no lower case character available
b) A "complete font" can be used (if one is specified in the
appropriate FONT_INDEX).
c) as a last resort, a default (and rather rudimentary) font will
be used
GIF_TEXT comes packaged with a number of alphabytes, including:
Enviro: a subtly colored set of letters (upper and lower case), numbers,
and some punctation
Revue: a brightly colored set of letters, numbers, and some punctuation
Stich: a brightly colored set of letters, numbers, and some punctuation
Hobo: a blocky-colorful set of letters and numbers)
Mandarin: a multicolored set of letters, numbers, and some punctuation
Logger: a woody set of letters
andy01 a drippy set of letters and numbers, and some punctuation
andy02: a set of typewritter keys (letters only)
andy03: an austere set of letters
TTF_FONT: A TTF (true type) FONT to use
TTF_FONT_SIZE: it's size (in points)
Example:
TTF_FONT='couri'
TTF_FONT_SIZE=30
Note: either FONT, or TTF_FONT (and TTF_FONT_SIZE), should
always be specified
The TTF_FONT should point to a TTF font file relative to the
TTF_FONT_DIR (that you set in step 5 above). For example,
if TTF_FONT_DIR='C:\OS2\FONTS', and TTF_FONT="ARIAL", then
C:\OS2\FONTS\ARIAL.TTF file will be used.
Colors used for TTF_FONTS will be set by the TEXTCOLOR and
BACKCOLOR options. However, by using color slides you can
greatly increase the visual appeal of the your GIF_TEXT images.
For a variety of reasons, messages written with a TTF font
are NOT done a "character at a time". Thus, the "character
scaling" rules will NOT apply to each character in the message.
Notes:
* If both a TTF font, and an "alphabyte or complete" font
are specified, the TTF font will be used.
* If TTF_FONT is specified, but TTF_FONT_SIZE is not (or if
TTF_FONT_SIZE=0), then the TTF font will NOT be used (instead,
the value of FONT will be used)..
II.b.2----------------- Recommended
WIDTH: The width, in pixels, of the image.
Example: Width=480
The image will be scaled to fit into WIDTH pixels. If you do not
specify WIDTH, or if you set WIDTH=0, then GIF_TEXT will use all
the pixels required).
Notes: * this overrides the default WIDTH variable (in GIF_TEXT.CMD)
* width will include X_FRAME (thus, writeable area is
width-2*X_FRAME)
HEIGHT: The height, in pixels, of the image.
Example: height=60
The image will be scaled to fit into WIDTH pixels. If you do not
specify HEIGHT, or if you set WIDTH=0, then GIF_TEXT will use all
the pixels required.
Note: * this overrides the default HEIGHT variable (in GIF_TEXT.CMD)
* height iwll include Y_FRAME (thus, writeable area is
height-2*Y_FRAME)
II.b.3----------------- Often useful
AS: The file to save the GIF image to. This is ONLY used in a parameter
list included in a command-line invocation of GIF_TEXT.
For example:
D:\APPS>gif_text text=hi font=hobo as=hello1.gif
TIME_FMT: The format used to display the time.
Example: time_Fmt='N'
GIF_TEXT understands several "REXX" time formats. They are:
L : Long (for example: 16:54:22.12000)
N : 24 hour (16:54:22)
H : Hour (16)
M : Minutes (1014)
S : Seconds (60682)
C : Civil (4:54pm)
1 : Same as C, with special am and pm characters used
(if available)
Note: this overrides the default TIME_FMT variable (in GIF_TEXT.CMD)
DATE_FMT: The format used to display the date.
Example: time_Fmt='E'
GIF_TEXT understands several "REXX" date formats. They are:
N: Internet standard (for example: 27 Aug 1988)
D: Days (240)
E: European (27/08/88)
M: Month (August)
B: Basedate (725975)
O: Ordered (88/08/27)
S: Sorted (19880827)
U: US (08/27/88)
W: Weekday (Saturday)
Note: this overrides the default DATE_FMT variable (in GIF_TEXT.CMD)
BACK: The name of .GIF file to use as a background for the text
message. It should be a filename relative to the ALPHA_DIR_ROOT
directory.
Example: BACK="BACKS/SATIN.GIF"
Notes:
* By default, no background is used
* BACK=0 means "no background"
* When BACK is set, then BACKCOLOR is ignored.
SPECIAL OPTION: if GIF_Text is being run as an SREhttp/2 addon,
then you can specify a fully-qualified URL
pointing to a .GIF file. GIF_Text will attempt
to retrieve this .GIF file and use it as a
background.
BACK_SCALE: If BACK_SCALE=1, then the background will be scaled to
fit into the message area. Otherwise (by default) the
background image will be "tiled" into the message area.
X_F: The size, in pixels, of the left and right frame.
or This is designed to be used with the WIDTH option.
X_FRAME It is most useful when combined with a background,
especially a "button" background".
Note: the width of the text will be WIDTH-(2*X_F).
Y_F: The size, in pixels, of the top and bottom frame.
or is designed to be used with the HEIGHT option.
Y_FRAME It is most useful when combined with a background,
especially a "button" background".
Note: the height of the text will be HEIGHT-(2*Y_F).
X_OF Move the image this many pixels to the right (or left, if
or X_OF is negative. If large values are used, portions of
X_OFFSET the image will be cutoff (they'll be outside of the frame
of the image).
Y_OF Move the image this many pixels down (or up, if
or X_OF is negative. If large values are used, portions of
Y_OFFSET the image will be cutoff (they'll be outside of the frame
of the image).
Hint: you can use the X and Y offsets to create a "shadow"
of your text image. To do this:
a) create a .GIF image of a text string, with
a small (say, 10) offset; and using a
bland color slide
b) save this image to a file in your ALPHA_DIR_ROOT
directory
c) regenerate the image, using:
i) the image created in b) as background file
ii) 0 offsets
iii) using no, or a different, color slide
Y_VAL: Vertical alignment. By default, characters are aligned at
or the top of the image (after adding a y_frame); pr at
Y_VALIGN the top or bottom of "line's image" (of a multi-lines-of-text
image). You can choose to align at the bottom, or in the middle:
Y_VAL=T -- top of image
Y_VAL=M -- middle of image
Y_VAL=B -- bottom of image
LINE_JUST : Type of line justification. Can be L,C, or R
or (left, right or center); with L the default.
JUSTIFY Only used on multiple line messages (where $n
is used to specify a "new line".
LINE_SEP : Spacing between lines (of a multi-line message),
in pixels. The default value is 2.
The next several options, dealing with scales and slides, are used
to produce fancy transforms of your characters: including in-message
variations in character size, and color transformations.
The color transformations are especially handy when
used with black and white fonts (such as the "complete" fonts one
might derive from a ttf or ps font).
X_SCA: A space delimited list of "width scale factors", used to
or adjust the width of each character of the message.
X_SCALE This list should contain numbers, where 1.0 means
do not adjust width, <1.0 means shrink, and >1.0 means
increase. Width adjustment works by mapping the
nth character of the message to the this list, with
fractional mappings resolved by interpolating between
list components.
Example: X_SCA=1.0+1.2+1.5+1.1 (note use of + to signfiy space)
In this example, the first character will be regular size,
increasing until 2/3 through the message (where the
adjustment is a 50% increase), and then decreasing to a 10%
increase at the last character
Y_SCA: Same as X_SCA, but for character height
or Example: Y_SCA=0.5+1.0+2.0
Y_SCALE Start at 1/2 size and end at double size.
Color slides are used to transform the color of each pixel in the message
image. Basically, if the value of a pixel in the "message image"
exceeds some threshold, then an appropriate color in the "color slide"
is displayed (instead of the color specified in the "message image").
Execution note: Although color slides are a very convenient way of
converting a simple (black and white) "complete font" into a
colorful font, they do require some time to execute -- say,
20 seconds to process a 300x50 image (on a Pentium 100).
SLIDE : The name of slide file. Slide files are simply images
that are used to transform the colors of the message.
In it's simplest use:
If the pixel value of the message image is greater then 1,
Then the color of the corresponding pixel, in the slide,
will be used.
The "corresponding pixel" is a function of pixel position,
both horizontally and vertically -- see the SLIDE_H,
SLIDE_T, and the other SLIDE_ options for details!
Note: When specified in the selector, relative slide files
should be .GIF files located relative to the
ALPHABYT directory. For example,
slide=slides/rainbow.gif (might) be in the
D:\SRE\ALPHABYTE\SLIDES\RAINBOW.GIF directory.
Note: When specified in a font index file, relative SLIDE files
are assumed to be relative to the font's own directory.
example: slide=slides/rainbow2.gif
(note that / is converted to \)
SPECIAL OPTION: if GIF_Text is being run as an SREhttp/2 addon,
then you can specify a fully-qualified URL
pointing to a .GIF file. GIF_Text will attempt
to retrieve this .GIF file and use it as a
color slide.
SLIDE_S : Size of user created color slide. SLIDE_S (and SLIDE_B,
SLIDE_G, and SLIDE_R) are IGNORED if SLIDE is specified
(and the .GIF file that SLIDE points to exists).
SLIDE_H : Horizontal slide type. Two types are recognized:
T = Tile. If the image is wider then the slide, then
repeat the slide (i.e.; horizonatally concatenate it)
F = Fit. If the image is wider then the slide, then
stretch the slide (i.e.; create runs).
If the slide is wider then the image, then pick equidistant
pixels from the slide, with the first (last) pixel in
the slide used for the first (last) pixel of the image
(that is, fit image to slide).
example:slide_h=T
Note: the default value is F
SLIDE_V : Vertical slide type. Three types are recognized:
T = Tile
F = Fit
N = Just use one row (in the middle third of the image)
If the slide is just one row high, then this option is
ignored (the first row is always used).
Example:
slide_v=F
SLIDE_T : Slide threshold. A two component answer: tnnn; where
type is the type, and nnn is an integer between 0 and 255.
Type can be P,B,C.
P : If pixel value is >=nnn, use slide
B : If average of the 3 color values is >= nnn, use slide
C : If any one of the 3 color values is >=nnn, use slide
Examples:
slide_t=P1 (this is the default)
slide_t=C100
Note: for a typical black and white alphabyte,, such as a
"ttf derived" complete font, you should use slide_t=P1
Special usage of SLIDE_T -- you can specify a colon delimited
list of thresholds; the threshold used will be drawn from this list,
with interpolation (i.e.; in the same way that X_SCALE is
interpolated). For example:
SLIDE_T=P1:2:5
means the threshold starts at 1, goes to 2 for the middle width,
and ends at 5.
Note: it is probably NOT wise to use this "pixel specific" threshold
with B/W fonts.
SLIDE_C : Coordinates to use when computing slide position. A space
delimited pair of numbers, each number can be a fraction between
0 and 1 (inclusive).
By default, the "column" (the width pixel value) in the message
image is used when looking up a color slide value. However,
you can use a "pixel distance" from some user defined center.
The effect is to create a 2d color wash, radiating out from
this center.
Note that the SLIDE_C coordinates are defined as a fraction
of width and height; thus 0 0 is the uppe left corner,
1 0 is the upper right corner, and 0 1 is the lower left corner.
Example: SLIDE_C=0.5+0.1 (center is near the top, at the
horizontal center)
FIGDIST_T : Method of computing distances for use with color slides.
Four methods are supported:
1 : Linear distance. dist= sqrt(dx*dx + dy*dy).
2 : Box-steps. dist = abs(dx)+abs(dy)
3 : Modified box-steps.
dist= max(abs(dx),abs(dy)) + min(abs(dx),abs(dy))/2
4 : 1 dimensional: dist=max(abs(dx),abs(dy))
where dx and dy are the "x" and "y" offsets (from a given pixel
to a reference point).
Method 1 tends to yields smoothest results, but can be quite slow
(especially if you do not have REXXLIB.DLL). Method 2 and
method 4 are similar, and are the fastest (about 10 times
faster then method 1). Method 3 is an approximation to
method 1, and is almost as fast as methods 2 and 4.
We recommend method 3. However, you might want to experiment:
in some cases, the results of using different methods can be
quite different (this is most likely to occur when you
specify SLIDE_C).
Example: FIGDIST_T=3
SLIDE_P: Probability of using the color slide's value. This should be
a space delimited list of fractions (between 0.0 and 1.0,
inclusive). A value of 0 means "use the alphabyte's color",
a value of 1 means "use the color slide's color".
Example: SLIDE_P=1+1+0.9+0.2+0+0
First third of image is color slide, last third is
image, middle third is a mixture.
Note that + are used as "space parameters"; when
SLIDE_P is entered in a font index file, use spaces
between the values.
SLIDE_P is meant to provide a simple means of creating a
foreground fade-into effect: between the alphabyte's image and
the color slides's image. Creation and use of in-between colors
might look better, but with a 256 color limit per .GIF file,
it might not.
SLIDE_SI: Size of "user specified color slide" (# pixels and # colors)
Instead of using a color slide contained in a file, you can
"create" your own. SLIDE_SI should equal the size (in colors,
hence in pixels) of this slide.
For example: SLIDE_SI=50 ; a 50 element color slide will be
used (based on SLIDE_RE, SLIDE_GR, and SLIDE_BL)
Setting SLIDE_SI=0 (the default) suppresses this option.
SLIDE_RE: Red color parameters for "created slide". Enter a list of
0 to 1 fractions; with 0 meaning "none of this color", and
1 "max intensity of this color".
For example: SLIDE_RE=0.0+0.2+0.3+0.9+0.1
the red intensity will increase, then suddenly drop off.
Note that SLIDE_GR and SLIDE_BL are specified in the same manner.
SLIDE_GR: Green color parameters for "created slide"
SLIDE_BL: Blue color parameters for "created slide"
Mask files are used to mask the final image (the final image contains the
background, the text characters, and the color slide modifications of the
text characters. Mask files are simply .GIF files that are interpreted
as "mask" -- with "masked" elements set to a pixel value of 0 (i.e.; to the
transparent pixel). This can be used to create some interesting effects.
MASK_FILE: Name of a mask file. This should be a .GIF file in (or relative
to) the ALPHA_DIR_ROOT directory
SPECIAL OPTION: if GIF_Text is being run as an SREhttp/2 addon,
then you can specify a fully-qualified URL
pointing to a .GIF file. GIF_Text will attempt
to retrieve this .GIF file and use it as a
mask file.
Examples: MASK_FILE=circle.gif
MASK_FILE=http://foo.bar.net/shapes/triangle.gif
MASK_THRESHOLD: By default, a value of 0 is used as a threshold. Use
MASK_THRESHOLD (set to a non-zero value) to change this.
Example: MASK_THRESHOLD=3
MASK_REVERSE: By default, pixels in the final image with values less than
of equal to the MASK_THRESHOLD will be transformed to 0
valued pixels. You can use MASK_REVERSE to switch this
(pixels greater then MASK_THRESHOLD will be transformed).
Example: MAXK_SCALE=Y
MASK_SCALE: As with color slides and backgrounds, you can either scale
the mask file to fit the image you've created, or you
can tile the mask file over the image.
Example: MASK_SCALE=Y
II.b.4 --------------- Less frequently used
FONT_NAME: The "name" of the alphabyte font.
or Example: FONT_NAME='ENVIRO'
NAME The FONT_NAME is used when resolving .GIF filenames.
This parameter is NOT required when using the alphabytes
shipped with GIF_TEXT.
See the "technical notes" section for details
on how and when to use FONT_NAME.
FONT_INDEX: The "index file" for the alphabyte font.
or Example: FONT_INDEX='ENVIRO.IND'
INDEX The FONT_INDEX contains alphabyte explicit information, including
character to .GIF file assignations. If not included, GIF_TEXT
will look for a FONT.ind file (in the FONT sub-directory of the
ALPHA_DIR_ROOT directory).
This parameter is NOT required when using the alphabytes
shipped with GIF_TEXT.
See the "technical notes" and "Sample of a FONT_INDEX" sections
of this document for further details on how and when to use a
FONT_INDEX.
CACHE: The name of a file (in the ALPHA_DIR_ROOT directory)
to use to store the created image.
If the "image cache" is enabled (see the technical notes),
then the image cache is first searched for this file.
If it exists (and is still valid), it will be used.
If it does not exist, the image will be saved to this
file "for future use". See the technical notes below for details.
Note: if a $t or $d occurs in the message, CACHE is ignored!
CACHE2: Same as CACHE, but $t and $d do NOT suppress use of the
cache (note that the time and date will NOT be updated)!
BACKC: The background RGB colors.
or Example: BACKC=98AE10
BACKCOLOR A 6-hex-character color code used to define the background color.
This will override the DEF_BACKCOLOR variable (in GIF_TEXT.CMD)
In addition, it will override the BACK= parameter in the FONT_INDEX.
Note that if a BACKground file is used, BACKCOLOR is not used.
TEXTC: The default-font RGB colors
or Example: TEXTCOLOR=FF220
TEXTCOLOR A 6-hex-character color code used to define the default-text color.
This will override the DEF_TEXTCOLOR variable (in GIF_TEXT.CMD)
In addition, it will override the TEXT= parameter in the FONT_INDEX.
TRANS: The index of the transparent color.
Example: TRANSPARENT=0
Should be a value between 0 and 255. A value of -1 means "no
transparent color".
This will override the DEF_TRANSPARENT variable (in GIF_TEXT.CMD)
LITERAL: Set to 1 to supress $n code interpretation in the text.
Example LITERAL=1
SEND: Set to 1 to "send pieces of the image as they become available, 0 to
send entire image when done.
This overrides the SEND_PIECES argument in GIF_TEXT.CMD
Note that "sending pieces" only works with browsers that can
handle multi-part documnets (such as Netscape 1.3, but not
IBM Web Explorer 1.1)
MANY_C : MANY_C has two uses:
1) If equal to CYCLE FIT END or RANDOM:
overrides the MANY_COMPLETE setting in the FONT_INDEX.
2) If equal to a number > 0:
sets the "number of fonts" to use.
This is useful if you only want to use the first
2 (or 1, or 3, or ...) of a many-font set.
See section IV.a for details
Note: when running GIF_TEXT in "stand alone" mode, you will be explicitly
asked to provide values for several of these options. You will also be
given the opportunity to enter "additional options" -- in which case you
should use the syntax specified above (i.e.; as if the options were
part of an http request). Note that stand-alone mode has a bit of
on-line help, and it will save prior answers in a GIF_TEXT.ANS file.
-----------------------------------
III. Technical notes
GIF_TEXT roughly takes the following steps when considering a request. Note
that the values of the parameters may be a generic default (as set in
GIF_TEXT.CMD), may be from the font index file, or may be supplied as one of
the request options.
1) Determine the size of the image
2) Create a background
3) Determine locations of characters
a) Use a character specific .GIF file if avaialable
b) Use a "complete font" file if available
c) If neither a or b are satisified, use the built in font
Section IIIa describes this step in greater detail.
4) IF X_SCALE or Y_SCALE are specified, stretch (or shrink) the image
associated with each character
5) Create a message image using results from step 4
6) If a color slide is specified, transform the appropriate pixels
in the "message image". Section IIIh contains details.
7) Write the message image on top of the background
8) If a mask was specified, use the mask to set foreground pixels
to the background "color"
9) Transfer the results.
IIIa. Basic File Matching Algorithim
When using "alphabyte" fonts, with one font per character,
GIF_TEXT has to determine what the appropriate .GIF file is.
For purposes of illustration, let's assume two examples:
i) 
ii) )
and a ALPHA_DIR_ROOT='D:\SRE\ALPHABYT' (as set in GIF_TEXT.CMD).
Furthermore, assume that you've correctly installed the various .GIF and
.IND files be in the appropriate FONT= directories of the
ALPHA_DIR_ROOT. In our examples, these directories are:
i) D:\SRE\ALPHABYT\HOBO\
ii) D:\SRE\ALPHABYT\NEWFONTS\FONT1\
The following outlines the logic used by GIF_TEXT when matching a .GIF
file to a character.
1) A FONT_INDEX file (in this directory) will be examined for explicit
"character to .GIF file" assignations.
If you did not define a FONT_INDEX, then an "ownname.ind"
file is looked for. In our examples, the following index files
are looked for:
i) D:\SRE\ALPHABYT\HOBO\HOBO.IND
ii) D:\SRE\ALPHABYT\NEWFONTS\FONT1\FONT1.IND
If the desired character is listed in the FONT_INDEX, and the file this
listing refers to exists, then this "refered to file" is used.
For example, an entry in the FONT_INDEX of:
# NUM.GIF
means "use NUM.GIF for the # character".
Or, either
##224 ALPHA.GIF
##E0x ALPHA.GIF
means "use ALPHA.GIF if the characters ascii value is 224" (note that the latter syntax
is the hex value of 224).
Caution: If you are using MKGIFTXT.HTM -- be aware that the "ascii" value
sent by a browser (using #hh syntax) depends on the code page used
by the browser). For "high ascii" characters, you might want to instruct
users to use $#nnn; or $#nnx; sequences.
In addition, the FONT_INDEX can contain information on which (if any)
"complete" font to use as an "alphabyte specific default".
For details on how to structure a FONT_INDEX file, see the
"Sample of a FONT_INDEX" section of this document. For details on
"Complete" fonts, see the Complete Fonts section of this document.
2) If no match in the FONT_INDEX can be found, then look for
the following file names.
a) For lower case characters only
a1) Look for xLC.GIF
a2) Look for FONTNAMExLC.GIF
a3) Look for FONTNAME-xLC.GIF
b) For all characters:
b1) Look for x.GIF
b2) Look for FONTNAMEx.GIF
b3) Look for FONTNAME-x.GIF
b4) Look for xFONTNAME.GIF
.... where x is the desired character, and FONTNAME is the name of the
desired font.
3) If 1 and 2 do not yield a match, then generate a font using either:
a) the "alphabyte specific complete" font, or
b) the the rudimentary font built into GIF_TEXT.
In either case ,the TEXTCOLOR variable can be used as the color of
the message-text.
Note that TEXTCOLOR can come from (in order of precedence):
a) A TEXTCOLOR= option (in the src="...")
b) A TEXT= entry in the FONT_INDEX file
c) The value of the DEF_TEXTCOLOR variable (in GIF_TEXT.CMD).
(see section IIId for details on "alphabyte specific complete" fonts).
Example:
If the "x" character of the HOBO alphabyte is desired, and
there is no match in HOBO.IND, the following will be looked
for (the first successful match is used):
a) D:\SRE\ALPHABYT\HOBO\XLC.GIF
b) D:\SRE\ALPHABYT\HOBO\HOBOXLC.GIF
c) D:\SRE\ALPHABYT\HOBO\HOBO-XLC.GIF
d) D:\SRE\ALPHABYT\HOBO\X.GIF
e) D:\SRE\ALPHABYT\HOBO\HOBOX.GIF
f) D:\SRE\ALPHABYT\HOBO\HOBO-X.GIF
g) D:\SRE\ALPHABYT\HOBO\XHOBO.GIF
Notes:
* for non-english alphabytes (i.e.; alphabytes containing
umlaut, acutes, and other such characters); you might need to specify
$nn or ##nnn entries in the FONT_INDEX file.
* for non lower case characters, steps a,b and c are skipped.
* if you've obtained a font with a prefix that does
not match it's "name", you should include a FONTNAME
option. For example, for
instead of HOBO\HOBOXLC.GIF, GIF_TEXT would look for
HOBO\SLICKXLC.GIF, etc. In addition, if INDEX is not specified,
GIF_TEXT will look for SLICK.IND as an index file.
* Reminder: OS/2 does NOT differentiate between upper and lower case
when searching for a filename.
----------------
IIIb. Adding an alphabyte
To add an alphabyte:
1) Create a new subdirectory under the ALPHA_DIR_ROOT
2) Copy the .GIF files (1 per character) to this subdirectory.
3) You might need to rename the .GIF files to adhere to the
logic discussed in section IIIa. In general, unless you really
need to, it's simpler to NOT specify the FONT_INDEX and FONT_NAME
when invoking GIF_TEXT (just make sure you've approriately named
the alphabyte, etc. files).
4) Create a FONT_INDEX file. The font_index file should always
contain the BACK= (background) and TEXT= (textcolor) arguments.
You can also include:
* Special "character to GIF file" mappings (such as for punctuation
marks, or high-ascii characters).
* Special entries (to match $nn substrings, such as $1 and $2 for the
AM and PM "characters").
* An alphabyte-specific "complete font" to use as a default.
4a) For "complete fonts" that stand by themselves
(such as those derived from ttf or ps fonts), there will
be NO "character specific GIF files", and the FONT_INDEX
file is REQUIRED!
5) If you find renaming files to be tedious, and the names of the
alphabyte .GIF files do not conform to the rules discusssed above,
you can include "character specific filenames" in the FONT_INDEX file.
6) You can specify special characters ($n) in the FONT_INDEX file
(see section IV for details).
----------------
IIIc. Adding a background
Adding a background is as simple as finding a .GIF file (say, a
texture) that you like, and copying it to some directory relative
to the ALPHA_DIR_ROOT directory (say; D:\SRE\ALPHABYT\backs).
You might want to reduce the color table of the background (remember,
a .GIF file can only have 256 colors), but you don't have to.
Reminder:
When specifying the background, be sure to include the subdirectory
(relative to the ALPHA_DIR_ROOT dir).
For example: back=backs/my_back.gif
where backs is a subdirectory of ALPHA_DIR_ROOT
----------------
IIId. Adding a complete font
As an alternative to the use of "one file per character" alphabytes,
GIF_TEXT can also use "complete" fonts. By "complete" fonts, we refer
to a .GIF file that contains a "grid" of fonts arranged in equi-sized
cells.
In addition to allowing one to use "regularly spaced" fonts delivered in
one file, complete fonts can be a convenient way to make use of
postscript and true type fonts.
Note: Various programs (GhostScript for PS fonts, THUMBSPLUS
for TTF fonts, etc.) can display the various characters
that comprise a (PS, TTF, etc.)font. Typically, the
characters will be displayed in a "grid", with each cell of
the "grid" the same size.
With a little bit of work, a .GIF file containing such a "grid" can be
used as a "complete font". That is, instead of looking for a file that
matches a character, GIF_TEXT can extract the image of the character
from a (single) .GIF file that contains a "complete set of fonts".
In order to do this, you must provide some information in a
FONT_INDEX (an .IND) file.
a) The name of the .GIF file that contains the complete font
b) A "black and white" flag
c) the x,y offset (in pixels) to the upper left corner of the first
character
d) the number of characters in a row
e) the width and height of each character (in pixels)
f) the "within grid cell" offset (left, top, right, bottom)
g) a list of the characters, in order of appearance.
h) Optional: text color, transparency, and background color information.
In general, you would create a seperate directory for a
"complete" font that would contain just the .GIF
and the .IND file (the FONT_INDEX).
Perhaps of greater use, you can combine a standard (1 file per
character) alphabyte with a complete font -- the "complete" font will
be used if no matching "alphabyte" file can be found.
To do this, just add the items mentioned above to the alphabyte's
FONT_INDEX (the .IND file); and make sure the "complete font" .GIF
file is in the same directory as the "single character" .GIF files
(of this alphabyte).
Notes:
* For details on what to include in the .IND file, see section
IV below.
* You may find EXT_GIF.CMD, a simple utility included with
GIF_TEXT, useful.
It can be used to extract all the "character" .GIF files from a
complete font. This can be useful for:
** verifying the .IND file (say, in conjunction with PMVIEW's
thumbnail feature)
** if you want to modify each font (say, to create a
1-file-per-character alphabyte).
----------------
IIIe. Adding a TTF font
To add a TTF font, simply copy the TTF font file to the TTF_ROOT_DIR.
No further set up is required. Be sure to copy the TTF font, and
not a ZIPped version of the font!
Alternatively, you can create subdirectories under TTF_ROOT_DIR.
If you adopt this approach, be sure to include the subdirectory
name (in addition to the font file name) when specifying a
TTF_FONT option.
Lastly, when run under SREhttp/2, you can GET a ttf font off of the WWW --
just specify it's URL (make SURE to include the http://).
----------------
IIIf. Caching Images
When using GIF_TEXT to create static in-line images (that do not contain
$t or $d, and that are not created by MKGIFTXT or some other FORM based
front end), it is likely that the same image will be recreated repetitively.
Of course, you can be sensible and create the image once (say, with
MKGIFTXT), save it, and include this saved image explicitily.
But if you are sort of lazy, and have a powerful enough machine,
you can use the GIF_TEXT cache to "save the images for you".
To do this, you have to do two things:
1) In GIF_TEXT.CMD: Set the values of the CACHE_DURATION and CACHE_SIZE
variables.
* CACHE_DURATION sets the lifespan of a "saved image" (in
days). If you might modify the "alphabytes", set this
to be a low value.
Example: CACHE_DURATION=2
* CACHE_SIZE sets the maximum number of "saved images" to retain.
If you are worried that hackers might "save" a lot of
images on your site, set this to a low number. Note
that once the CACHE_SIZE files appear in the
ALPHA_DIR_ROOT directory, caching is suppressed -- there is
no attempt to "intelligently" weed out older or less used
entries.
Example: CACHE_SIZE=150
2) Include a CACHE=filename.GIF option in your 
element.
Alternatively, use a CACHE2=filename.GIF. CACHE2 will "force caching",
even if a $t (time) or $d (date) "special code" appears in the message.
Example: 
* In this example:
If "WELCOME1.GIF" exists, it will be used. Otherwise, GIF_TEXT will
generate the image, send it to the client, and thant save the image to
WELCOME1.GIF for future use.
Notes:
* to supress caching, set CACHE_SIZE=0
* If you do not include a CACHE= option, the cache is ignored.
* filename.GIF should be a UNIQUE filename --
!!! It is YOUR responsibility to NOT use the same
!!! name for different in-line images.
* filename should NOT contain path information -- it will
refer to files in the ALPHA_DIR_ROOT directory.
WARNING: Since use of the cache requires invocation of GIF_TEXT, rather then
mere transferal of a file, we don't generally recommend it --
on a low-powered server, it can be slow.
Furthermore, there is some concern with stability --
on occassion, when RXGDUTIL procedures are rapidly called, (as will
happen if a single document contains requests for several "cached"
images) server errors may occur (such as the infamous SYS3175).
HINT: One good use of the CACHE option is to save an image for
later downloading (a trick used by MKGIFTXT.CMD).
IIIg. Using GIF_TEXT as a counter
Although not the most efficient method of generating a graphical
"hit counter", GIF_TEXT does provide a fairly powerful graphical counter.
However, you will need a server that can generate a textual
"count of hits" as a "server side include".
For example, users of the SREhttp/2 WWW server can use:
i) or
ii)
Example of a "random colors" counter, using the COUNTER.RXX facility:
A more traditional example, using a frameless auto style odometer, and
SREhttp/2's REPLACE COUNT:
III.h) Using color slides.
Color slides are simple and effective means of making drab fonts come alive
with color. The notion is to create a "message image" using your favorite
alphabyte (or complete font), and then use "foreground" colors drawn from
the color slide instead of the colors the font was created with.
This is especially useful when used with black and white fonts, such
as "complete fonts" derived from a ttf or ps font.
At it's simplest, a color slide is a one row .GIF file with some sort
of rainbow or similar color pattern. For each row of the "message
image" (the image formed from writing the appropriate alphabyte
characters), a column-by-column mapping, between the pixel in the
message image and the pixel in the color slide, is performed. If a pixel's
value is above a threshold (i.e.; greater then 0), then
the color from the color slide will be used. Thus, a pixel on the left size
of the image will be displayed with a different color then a pixel (with the
same value) on the right side of the image.
There are two ways of specifying a color slide:
1) By selecting a .GIF file to use as a color slide.
GIF_TEXT comes with a dozen or so examples of color-slide files.
2) By specifying a set of RGB parameters.
The SLIDE_S (and SLIDE_R, SLIDE_G, and SLIDE_B) can be used
to specify a color slide).
Once specified, there are 3 ways the color slide can be used
1) As a single row (column specific) transformer
2) As a "color wash" (or color gradient) centered at a point
defined by the SLIDE_C option.
3) As a 2 dimensional foreground image.
In all cases, it is unlikely that the size (either height or width) will
be the same as the size of the message image. To fit these mismatched sizes,
you can either repeat the color slide, or you can stretch it -- the
SLIDE_V and SLIDE_H control this fit method.
Note that when the color slide is used as "single row", a multi-row GIF file
can still be used, GIF_TEXT will use a row 1/3 of the way down from the top.
Please be aware that to use a multi-row color slide as a single row, you
must set SLIDE_V=N.
Selection of which message image pixels to transform is based on the
pixel's value, on the SLIDE_T option, and on the SLIDE_P option. Selection
is usually based on the pixel's value, which ranges between
0 and 255 (i.e.; in b/w images, background pixels typically have a a value
of 0, and foreground pixels have a value of 1). However, the average color
brightness of the pixel, or it's maximum color brightness can be used.
Furthermore, this threshold can depend on the position in the image of the
pixel.
You can also use the SLIDE_P option to create a fade-into effect, with
the color slide colors being used at the start of an image, the alphabyte
colors used at the end, and a mixture used in between.
III.i) Switching fonts
You can use the $F(fontname) "special code" to tell gif_text to start
using the "fontname" font. This can be used to create fairly complicated
mixed-font messages (it's a more flexibile alternative to the "multiple
variants of a font" option discussed below).
Be aware that the switched-to font may have slightly "wrong" characteristics.
For example, "complete fonts" may be displayed using the color associated
with the message's "original" font.
Also note that the fontname must be a "standard" GIF_TEXT font. That is,
it must point to a font in a subdirectory of your alphabytes directory,
and this subdirectory should contain a fontname.ind file. For example,
if fontname is "HOBO", then the HOBO/ and HOBO/HOBO.IND, will be used.
In other words, the fontname is use for the FONT_NAME, FONT_INDEX,
and FONT_DIR variables.
Alternatively, you can switch to a TTF font. To do this, the "fontname"
should have the following structure:
!nn_ttfname
where
nn = point size
ttfname = name of the ttf file (without the .TTF extension)
For example:
message="Courier and $f(!28_couri) 28 point italic."
III;j) Remapping fonts to a different code page
If you are using GIF_TEXT with non-english code pages, you might
want to remap your message. That is, you might want to convert
a message to different ascii values. In particular, if your TTF fonts
are sorted differently then a screen or ISO font, then you'll need to
remap to ensure the GIF_TEXT message is not misinterpreted.
GIF_TEXT.CMD contains several variables to assist in this remapping:
CHARSET_STANDALONE: Converts message to different code page (standalone mode
CHARSET_WEB: Converts message to different code page (www mode
CHARSET_REF: Used in converting messages (typically this is not changed)
Basically, CHARSET_STANDALONE and CHARSET_WEB should be long strings, with
each character in the string matched to the corresponding character in
CHARSET_REF.
For example, suppose
i) ascii-value 154 yields a smiley face in the reference
code page (that is, your ttf fonts typically display a smiley face for
this character)
ii) ascii value 143 yields a check mark in this reference code page
ii) ascii-value 154 yields a check mark in an ISO encoding used in your
country
iv) CHARSET_REF is a character with ascii value of 154
CHARSET_WEB is a character ith ascii value of 143
Then, a check-mark character in a GIF_text message produced by a
browser using this ISO encoding (that generates a 154 when the "check mark
key" is hit) will be converted to a 143. And when the TTF conversion
occurs, the 143 will appropriately map to a check mark.
-----------------------------------
IV. Sample of a FONT_INDEX
The notion is that GIF_TEXT has defaults (declared in GIF_TEXT.CMD)
that are overridden on a font-specific basis by entries in the font's
"index" file
Note:
You can override these font-specific defaults on a request
specific basis by including the appropriate options in the
request to the server.
In general, most of the "request line options" can be specified in
a FONT_INDEX. Thus, for a complete description of what the parameters
do, either check the descriptions in the "options" above, or look
at the sample below.
Note that several of these parameters expect a space delimited list.
In the description above (as request line options), a + is used as a space --
a requirement of the http method of forming requests. However, when
specified in an index file, you can use a space (that is, use a space
instead of a + character).
The following illustrates and describes FONT_INDEX files. Note that
blank lines are ignored, and that lines starting with ** are comments.
List of FONT_INDEX parameters:
TEXT=aabbcc : Default text color
BACK=aabbcc : Default background color
x filename.gif : Match character "x" to an explicit gif file
##nnn filename.gif : Match character with an ascii value of nnn to an explicit gif file
##nnx filename.gif : Match character with an ascii value of nn (hex) to an explicit gif file
char=n filename.gif : Match a $n (or $nn) substring to an explicit gif file
x_scale=n.n m.m j.j : Space delimited list "character specific width scales"
y_scale=n.n m.m j.j : Space delimited list "character specific height scales"
y_valign=T/M/B : How to vertically align characters
slide=filename.gif : An (optional) color slide file.
slide_h =T/F : Tile or Fit color slide to image (horizontal)
slide_v =T/N/F : Tile, Fit, or one row of color slide to image (vertical)
slide_t =P/C/An:n2:n3 : Threshold: (pixel, one color, or average color)
slide_p =v1 v2 v3 : Probability of using slide parameters
slide_s =n : size of user specified color slide (0=none)
slide_r =v1 v2 v3 : Red parameters for user specified color slide
slide_g =v1 v2 v3 : Green parameters " " " " "
slide_b =v1 v2 v3 : Blue parameters " " " " "
(the following parameters are used to describe a "complete font":
complete=filename.gif : File containing a "complete "font. More then one
complete= may appear.
Note: for downward compatability, you can also use
defaults=filename.gif
def_chars=abcd e : List of characters (must match list of characters in
the complete font file). When specifying a "complete" font,
this is REQUIRED.
def_bw=0/1 : Complete Font is a black & white font (if so,
use TEXT and BACK colors)
def_offset=xoff yoff : Pixel offset to top-left of first character
(in a complete font file)
def_inrow : # characters per row
def_charsize=width height : Character size (width and height)
def_char_offset=l t r b : Additional offset, within character (gets rid of
white space)
-------- Beginning of Sample .IND file -----
** FONT_INDEX files are used to:
** 1) set explicit character-to-file matches,
** 2) set the text-color and other defaults
** 3) to identify special "characters".
** 4) information on the "alphabyte specific complete" font.
** 1a) Text-color-defaults
** Start the line with a TEXT=, and then immediately thereafter put in the
** 6 hex character color code
** i.e. 6200bb (a reddish blue)
TEXT=60f0ff
** 1b) Background color-defaults
** Similar to 1a, but start the line with BACK=
BACK=633332
** 1c) A "transparent" color-index that is used when a background is being used.
transparent=0
** 2) Character-to-file matches
** Each entry should contain the character (case sensitive), followed by the
** file name (relative to the font_dir directory -- do NOT use a fully
** qualified name)
- DASH.GIF
' APOS.GIF
! EXC.GIF
: COLON.GIF
& AMP.GIF
? QUEST.GIF
AM AM.GIF
PM PM.GIF
** characters with an "ascii" value of 225 use BETA.GIF
##225 Beta.gif
** Same as above, but expressed in hex
** Note: using hex, it's easier to match browser mappings, of FORM inputs, to desired characters.
##e1x Beta.gif
** Note special "AM" and "PM" entries -- these are ONLY used by
** the $T "time of day" special character
** Note that for characters not included in this file, the
** default naming conventions will be used (see section III.a for details)
** 3) Identifying special characters
** GIF_TEXT interprets $n substrings (in the message),with n some digit, to mean
** "use special character # n". You can define these "special characters"
** here by using
** CHAR=n file.gif
** For example, if you have a special PM character, you could define
** CHAR=1 pm.gif
** and if the message contains $1, then the PM.GIF "character" will be
** inserted (if PM.GIF is not available, the $1 will be ignored)
** Note: n must be between 0 and 99
CHAR=1 pm.gif
CHAR=2 am.gif
char=10 lquote.gif
char=11 rquote.gif
** Note that 1 (PM.GIF) and 2 (AM.GIF) may (or may not) be different
** then the AM.GIF and PM.GIF "character to file" matches.
** 4) Information on the alphabyte-specific complete font
** Complete fonts are .GIF files that contain all the characters. These characters
** must be arranged in a grid, with each cell of the grid the same size.
** Complete fonts are used whenever there is is no matching "alphabyte" (.GIF)
** file for a character
** (in many cases, you may not have ANY "alphabyte" files, you'll
** only have the "complete" font file).
**
** In order to use a complete font, you must specify several parameters:
** a) The .GIF file (in the same directory as this .IND file) that contains
** the complete font
complete=handwrit.gif
** (note, defaults= is synonymous with complete=)
** b) Is this a black and white font? (0=no, 1=yes).
** If 1, then text= and back= colors are used.
** Use 1 if you have a black and white font (say, as derived from
** a screen dump of a .ttf font).
** If 0, then the palette (in the .GIF file) is used as is.
** Use 0 if you have a multi-colored "complete font"
def_bw=1
** c) the x (column) and y (row) PIXEL offset in the .gif file --
** to the upper left corner of the first character (the first column of
** the first row of the "grid" of characters)
def_offset=0 47
** d) the number of characters in a row (that is, the number of columns in the grid)
def_inrow=16
** e) the width and height of each character, in pixels
def_charsize=46 47
** f) The within-character offset. If a lot of white space is placed around
** each character's "grid cell", you can offset the portion used.
** 4 values are required: a left, top, right, and bottom offset. This
** can be used to tighten up the placement of characters in the message.
def_char_offset=0 0 0 0
** g) The characters, in order of appearance. REQUIRED.
** Spaces should be used for "empty or unneeded" characters
** If this gets out of order, incorrect characters will be written!
** A first space (after the =) is important -- since the row=1 column=1 character
** is often (but not always) a space.
def_chars= !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~
**
** 5) Fancy modifications
** X_SCALE (Y_SCALE) is use to shrink/expand the width (height) of each
** character in your message. A mapping of character position to
** the position in the X_SCALE (Y_SCALE) list, with linear interpolation,
** is used to determine the width (height) scale
x_scale=1 1.3 1.6 1
y_scale=1 1.1 1 0.7
**
** Y_VALIGN is used to vertially align each characters. Y_VALIGN
** can take 3 values: T=Top, M=Middle, and B=Bottom
-------- End of Sample .IND file -----
IV.a) Special note: using multiple variants of a font in one message.
If you have variants of a "complete font" that have
the same dimensions, but may differ in style, color, etc....
you can use them to mix up the letters in a message.
To do this, just specify multiple
complete=xxx.gif
lines. A list of complete fonts will be formed from all the
"complete=..." lines found. For example, if you have:
complete=Redwood.gif
complete=Bluewood.gif
complete=Grewood.gif
then the letters will be displayed using characters from all
three "wood" files.
By default, the multiple "complete fonts" will be cycled through. For example,
if the message is "hello", then
h : drawn from Redwood.gif
e : drawn from Bluewood.gif
l : drawn from Grewood.gif
l : drawn from Redwood.gif
o : drawn from Bluewood.gif
You can also set
many_complete=type
where type can be CYCLE, FIT, or END.
CYCLE is the default,
END will do a 1-to-1 match, with overflow message characters
using the last complete font (i.e.; l,l, and o
would all use Grewood.gif), and
FIT would assign (approximately) equal number of character to each font;
thus h is drawn from Redwood.gif, e and l from Bluewood.gif,
and l and o from Grewood.gif
RANDOM would randomly assign a character to a font (with a
a different assignation on each request)
Notes:
* by "same dimension", we mean the same offset, inrow, charsize, etc.
* The EPILOG2 "complete font", packaged with GIF_TEXT, is a simple
example of a multiple variant font.
* Instead of using these multiple variants, you might find that the
use of $F(fontname) in a message is more flexible.
IVb. An example of adding a new alphabyte.
This is a step by step example of how to add a new alphabyte. For
illustrative purposes, let's assume that your ALPHA_DIR_ROOT directory
is D:\SRE\ALPHABYT (if not, just appropriately substitute the
correct directory in what follows).
1) Find the ZIPJAZ.ZIP file in the temporary directory into which
you unzipped GIF_TEXT.ZIP.
NOTE: The JAZ alphabyte was obtained from Carol's Clipart, which is now
(alas) defunct.
2) Create a JAZ directory under D:\SRE\ALPHABYT, and
copy ZIPJAZ.ZIP to D:\SRE\ALPHABYT\JAZ
3) UNZIP ZIPJAZ.ZIP (in D:\SRE\ALPHABYT\JAZ directory)
4) You are now ready to produce some messages. For example
http://your.server.org/gif_text?text=hello&font=jaz&mess.gif
(the final mess.gif is a hack that some browsers require to
succesfully display the image in-line).
5) Now try
http://your.server.org/gif_text?text=123abc&font=jaz&mess.gif
This won't look so good -- we need to specify some defaults.
6) Create a JAZ.IND file (in the JAZ subdirectory). It should
contain the following lines ( do NOT include stuff in parenthesis):
BACK=b0b0b0 (a bright grey)
TEXT=00b0b0 (a bright cyan)
TRANSPARENT=0
Now try http://your.server.org/gif_text?text=123abc&font=jaz&a.gif,
it's not beautiful, but it's better.
7) Let's get ambitious, and add a "complete" font definition, which
will be used as an alternate to the "generic" default.
7a) Copy D:\SRE\ALPHABYT\BUTTRFLY\BUTTRFLY.GIF to the JAZ directory.
7b) Add the following to JAZ.IND
complete=buttrfly.gif
def_offset=0 47
def_charsize=48 47
def_inrow=16
def_bw=1
def_chars= !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^ `abcdefghijklmnopqrstuvwxyz{|}
Again, try http://your.server.org/gif_text?text=123abc&font=jaz&a.gif,
I'ld argue it's close to acceptable.
-----------------------------------
V. Acknowledgments
This utilty would not have been possible without the RXGD101 library
-- the full package is available from http://www.bearsoft.com/abs/rexxgd.html;
it's a port of the GD library, and is written by Andy Wysocki
(awysocki@absoftware.com).
In addition, the RXTTF.DLL "ttf to bitmap" library was created by
Michal Necasek (MichalN@scitechsoft.com).
...and, it would have been useless without the various and
sundry alphabyte fonts, etc. which were obtained from various
sources, including:
Rosie's Alphabytes
http://www.rozies.com/Zzzz/AlphaBytes/alpha.html
Additional fonts can be found at a number of places. A very good
source for mostly free fonts, many of them "complete fonts"
(you'll need to spend a few minutes making an .IND file), can be found
at Daniel Guildkrans site at
http://www.algonet.se/~guld1/freefont.htm
If you want to use GIF_TEXT as a clock or calendar, you will
only need digits and a few special characters (such as
the :, /, -, AM, and PM).
A good source for such limited "digit sets" is
http://www.digitmania.holowww.com.
You can also find links to a few other sites at
http://www.digitmania.holowww.com/alphabet.html.
Do you have questions, or do you have links to some additional alphabytes?
Let me know: Daniel Hellerstein (danielh@crosslink.net)