GifText Manual

From OS2World.Com Wiki
Revision as of 18:53, 9 October 2017 by Ak120 (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)  or
ii)  

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 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:

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)