GifText Manual

From OS2World.Com Wiki
Revision as of 15:09, 28 January 2014 by Martini (talk | contribs)
Jump to navigation Jump to search

By Daniel Hellerstein 03 November 2000


GIF_TEXT: A Graphical Text Generator for the WWW

GIF_TEXT, ver 1.3c, is a WWW 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.

To use GIF_TEXT you should have access to a web server running under
OS/2.  GIF_TEXT is optimized to work with the free SRE-http Web Server;
but you can use it with any  OS/2 web server that understands CGI-BIN.  

Alternatively, you can run GIF_TEXT from an OS/2 command line.  Although
the user interface is somewhat primitive (it is not GUI), it is quite
adequate for quick creation of simple images.

Once installed GIF_TEXT is easy to invoke.  For example, you can use the 
included MKGIFTXT.HTM html document as a front-end (or MKGIFRM.HTM --
a javascript/frames enabled version of MKGIFTXT.HTM). 

Or, you can include an in-line image html element in your HTML document.  
For example:
  <IMG src="/GIF_TEXT?font=enviro&text=HELLO&width=300">
will generate a 300 pixel wide image with the word "HELLO" (not including
the quotes) written using the "enviro" alphabyte.

For those of you who don't have direct access to a web server (i.e.; depend
on an ISP), but are running OS/2, you can use GIF_TEXT in stand-alone mode.
The user interface is primitive, and there is no direct graphics display, but 
it will produce fine output (which you can then view with a graphics viewer). 
Thus, you could use GIF_TEXT to create your images, and then FTP them
to your home page at your ISP.

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://www.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


Installation of GIF_TEXT requires that you copy a few files to a
few directories, and make a small modification to one of these files.
Alternatively, if you are installing GIF_TEXT as an SRE-http addon,
the INSTALL.CMD installation program will take care of these details
for you.


NOTE TO UPGRADERS FROM EARLIER VERSIONS OF GIF_TEXT:
    Prior to 1.2e, GIF_TEXT used a version of the RXGDUTIL library
    that lacked several special functions.
    If you've already installed an earlier version of GIF_TEXT, 
    you'll might have to reboot your server before copying RXGDUTIL.DLL 
    to the appropriate directory (i.e.; your C:\OS2\DLL directory).

    Furthermore, GIF_text now can read TTF font files -- you no longer have
    to create a "complete font image map" from a TTF font file.  To use
    these feature, you must set the TTF_FONT_DIR parameter in GIF_TEXT.CMD
    (SRE-http users can let INSTALL.CMD do it for you)

To install GIF_TEXT:

1) UNZIP GIF_TEXT.ZIP in an empty temporary directory.

2a) If you are installing GIF_TEXT as an SRE-http addon:
      you can run the INSTALL.CMD program (located in the 
      directory created in step 1 above).
 
2b.1) Otherwise, you can do it by hand...

   SRE-http users:
       Copy GIF_TEXT.CMD and MKGIFTXT.CMD to your "SRE-http
       addon" directory (i.e.; D:\GOSERVE\ADDON).
   For other, CGI-BIN capable servers:
       Copy GIF_TEXT.CMD and MKGIFTXT.CMD to your CGI-BIN scripts directory.

2b.2) Copy RXGDUTIL.DLL and RXTTF.DLL to a directory in the 
      OS/2 LIBPATH (for example, C:\OS2\DLL). 
      Or, if you are running SRE-http, copy it to your 
      "GoServe working directory".

   UPGRADERS -- you might have to reboot your machine if an older
   version of RXGDUTIL.DLL has been "locked into memory" by a prior use.

2b.3) Create an ALPHABYT directory (say, as a subdirectory of your
     GOSERVE directory). 
     Copy ALPHABYT.ZIP  to this ALPHABYT directory.
                 Note: ALPHABYT.ZIP is over 1M bytes.
     Example for SRE-http users: create D:\GOSERVE\ALPHABYT

2b.4) 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.

2b.5) With your favorite text editor, edit GIF_TEXT.CMD.  You MUST
        i) set the value of the GIF_DIR_ROOT variable to 
           be the above "ALPHABYT" directory
       ii) set the value of the TTF_DIR_ROOT to point to a directory
           containing TTF fonts.
      iii)  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 this GIF_DIR_ROOT directory for temporary storage.
      *  on most systems, the x:\os2\mdos\winos2\system directory contains 
         several ttf fonts.

2b.6) To setup the  (optional) MkGifTxt "web callable front end":
    a) Copy MkGifTxt.HTM, MkGifTx2.HTM and MkGifTx3.HTM to a web 
       accessible directory (i.e.; the GoServe data directory).
       Also, copy the "frames enabled version", MKGiFRM.HTM and 
       MkGifTOC.HTM, to this directory.

       Note to SRE-http users: 

    b) Copy SAMPGIF.ZIP to the IMGS\ subdirectory under the root
           of your web directory (for GoServe/SreHttp users: IMGS\ should
           be under the GoServe data directory).
       CD to this IMGS\ subdirectory, and UNZIP SAMPGIF.
    c) If you are using SRE-http, and you want to run MkGifTxt as
        an "addon" (rather then as a cgi-bin script) --
           copy MKGIFTXT.SRE to MKGIFTXT.HTM 
       (MKGIFTXT.HTM is setup to use the CGI-BIN version of GIF_TEXT).
    d) There are several parameters in MKGIFTXT.CMD that you
       should change. For example, to use "style" files, you'll need
       to set the STYLES_DIR parameter in MkGifTxt.CMD. Also,
       to use the "list fonts, etc" options, make sure the MKGIFTXT.CMD
       settings for GIF_DIR_ROOT and TTF_DIR_ROOT match those in
       GIF_TEXT.CMD.

2b.f)To setup the (optional) MkBUTTON "front end"
    a) Copy MKButton.HTM to a web accessible directory 
    b) Copy ALLBUT1.GIF to the IMGS\ subdirectory under the root
           of your web directory.
    c) If you are using SRE-http, and you want to run MKButton as
       an "addon" (rather then as a cgi-bin script) -- you'll need to 
       make a very simple change to MKButton.HTM --- see MKButton.HTM
       for details.

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 STEP 2.b5 !

You can point your browser at MKGIFTXT.HTM or MKGIFRM.HTM
(did you do step 2b.6?) and try it out: it's a nice way to 
quickly create "banners" that you can use as static images. 

Or, you can include <IMG src="/GIF_TEXT?options..> elements
in your HTML  documents -- a process described in the next section.

As mentioned in the introduction, GIF_TEXT can be used in stand-alone mode. 
   From an OS/2 prompt,
     i) CD (change directory) to the directory that you installed GIF_TEXT 
    ii) enter GIF_TEXT (at the prompt)

A Caution to SRE-http users:
     On some machines, the RXGD101.DLL library used by GIF_TEXT will
     occassionally generate a SYS3175 error that can crash GoServe. 
     If this should ocur, you may want to err on the side of caution by running
     GIF_TEXT as a cgi-bin script (since errors that occur whilst executing a 
     cgi-bin script will NOT crash GoServe).  However, do note that when run
     as cgi-bin script, several options (such as the "send in pieces", and
     "get remote .GIF files") will not be available.

A Caution to APACHE users (from Voytex Eymont)
  * with Apache, file names need to be lower case
  *  the cgis must have .CMD extensions


-----------------------------------------------------
II. Using GIF_TEXT

GIF_TEXT is often invoked using an IMG element (in an HTML document)
that contains special "request line options".  Several of these options 
are required (such as the text string), and several are optional 
(such as background color). This section describes all the GIF_TEXT 
"requestable" options.

Please be aware that default values of many of these options can be 
set in GIF_TEXT.CMD, and in "font index file". However, request line 
options take precedence over these defaults.

By way of introduction, the following simple examples may help:

* When using SRE-http:
  <IMG src="/GIF_TEXT?text=Welcome+surfers&font=enviro&width=300&as=MESS.GIF">
  <IMG src="/GIF_TEXT?text="The time is:$T"&font=andy01&time_Fmt=N&as=MESS.GIF">

   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:
  <IMG src="/CGI-BIN/GIF_TEXT?text=Welcome+surfers&font=enviro&width=300&as=MESS.GIF">
  <IMG src="/CGI-BIN/GIF_TEXT?text="The time is:$T"&font=andy01&time_Fmt=N&as=MESS.GIF">

  (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. For example:
               when processing in-line images, IBM's Web Explorer expects
               a .GIF extension and does not pay attention to the
               mime-type response header.


* 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),
   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 GIF_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 GIF_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 SRE-http 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.


               Variant: BACK2 means the same, and will override, BACK.


 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 GIF_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:\GOSERVE\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 SRE-http 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 GIF_DIR_ROOT directory

               SPECIAL OPTION: if GIF_Text is being run as an SRE-http 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
             GIF_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 GIF_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) <IMG src="/GIF_TEXT?font=HOBO&message=Welcome!">
 ii) <IMG src="/GIF_TEXT?font=NEWFONTS\FONT1&message=Welcome+(today)">
and a GIF_DIR_ROOT='D:\GOSERVE\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
GIF_DIR_ROOT. In our examples, these directories are:
  i)  D:\GOSERVE\ALPHABYT\HOBO\
 ii)  D:\GOSERVE\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:\GOSERVE\ALPHABYT\HOBO\HOBO.IND
        ii)  D:\GOSERVE\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:\GOSERVE\ALPHABYT\HOBO\XLC.GIF
      b)  D:\GOSERVE\ALPHABYT\HOBO\HOBOXLC.GIF
      c)  D:\GOSERVE\ALPHABYT\HOBO\HOBO-XLC.GIF
      d)  D:\GOSERVE\ALPHABYT\HOBO\X.GIF
      e)  D:\GOSERVE\ALPHABYT\HOBO\HOBOX.GIF
      f)  D:\GOSERVE\ALPHABYT\HOBO\HOBO-X.GIF
      g)  D:\GOSERVE\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
        <IMG src="/GIF_TEXT?font=HOBO&message=Welcome!"&FONTNAME=SLICK>
    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 GIF_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 GIF_DIR_ROOT directory (say; d:\goserve\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 GIF_DIR_ROOT dir).  
         For example: back=backs/my_back.gif
                        where backs is a subdirectory of GIF_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 SRE-http, 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
           GIF_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 <IMG Src="/GIF_TEXT?..">
       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: <IMG SRC="/GIF_TEXT?font=revue&text=Welcome!&cache=WELCOME1.GIF">
       * 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 GIF_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 SRE-http WWW server can use:
         i) <!-- REPLACE COUNTS --> or
        ii)  <!-- INTERPRET FILE COUNTER.RXX file=somefile.cnt&width=5 -->


   Example of a "random colors" counter, using the COUNTER.RXX facility:

   <img src="/cgi-bin/gif_text?font=bck&back=backs/tan&text=<!-- $ counter.rxx
     file=sample1&width=4-->&height=50&width=100&x_f=2&y_f=2"
     alt="hit counter">

   A more traditional example, using a frameless auto style odometer, and
   SRE-http's REPLACE COUNT:
        <img src="/cgi-bin/gif_text?font=57chevy&text=<!-- replace count -->"
            alt="<!-- 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 GIF_DIR_ROOT directory
  is D:\GOSERVE\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:\GOSERVE\ALPHABYT, and
     copy ZIPJAZ.ZIP  to  D:\GOSERVE\ALPHABYT\JAZ
  3) UNZIP ZIPJAZ.ZIP (in D:\GOSERVE\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:\GOSERVE\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@bearsoft.com).

In addition, the RXTTF.DLL "ttf to bitmap" library was created by
Michal Necasek  (mike@mendelu.cz).

...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.geocities.com/HotSprings/3055/alphabet.html</a>

E-Mom's Rainbow Graphic Designs:
   http://members.xoom.com/e_mom/

Andy's Art Attack:
  http://www.andyart.com

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.com.  You can also find links to a few
other sites at http://www.digitmania.com/alphabet.html.

Note that several "complete-fonts" were created from true type fonts 
obtained from now defunct sources. However, you might want to try
www.customeffects.com.

TTF fonts can be found in many places, that tend to come and go. One
nice site (circa April 1999) is http://fonts.tedesign.net

Do you have questions, or do you have links to some additional alphabytes? 
Let me know:  Daniel Hellerstein (danielh@crosslink.net)