NAME

       wml::des::gfont - Graphical Font Tag

SYNOPSIS

        #use wml::des::gfont

        <gfont [attributes]>One Single Line Of Text</gfont>

DESCRIPTION

       This is a nice interface to the gFONT program which can be found at
       http://www.engelschall.com/sw/gfont/. It provides a "<gfont>" tag which can be used
       similar to the standard HTML tag "<font>". But instead of online rendering by the
       webbrowser the text is rendered offline via gfont into a GIF image.  This has the
       following advantages:

       All TeX-available fonts can be used.
           you can use any TeX-available fonts instead of the commonly known ones the typical
           browsers support. These fonts will actually look like you want, i.e.  Helvetica _is_
           Helvetica with "<gfont>" while it can be Arial or a totally different (substituted)
           font when using the "<font>" tag.

       Fonts with much greater size can be used.
           With "<gfont>" you can increase the "size" attribute up to +9 which is actually 200pt
           in size while the HTML font tag usually stops at +4. So "<gfont>" can be used for big
           headlines.

       You can create banners with colored backgrounds.
           The standard "<font>" tag cannot use a different background color in HTML 3.2,
           "<gfont>" can. Because it directly renders into a GIF image which background has not
           to be transparent.

       When an image is generated, a text file containing the command which has been run is
       created, its name is the image file name with a ".cmd" suffix.  When WML is re-run, this
       file is searched for and gFONT executed only if command line has changed.

ATTRIBUTES

       base=filename
           Usually the created images for a source file page.wml are named page.gfontXXX.gif
           where "XXX" is a number starting with 000. When you use a "base=foo" attribute, then
           the resulting files are named foo.gfontXXX.gif.  Actually you can even use a complete
           filename including a directory prefix, i.e.  when you use "base=../../common/foo"
           attribute, then the GIF images are created as ../../common/foo.gfontXXX.gif. Use this
           feature to direct the images to a particular directory. Additionally using a "base="""
           attribute leads to images which are so-called hidden Unix files or dot-files.

           And for most flexibility when no base is specified and the variable "GFONT_BASE" is
           defined (usually from within a .wmlrc file via "-DGFONT_BASE~path/to/gfont/dir/base")
           it is used.  Use this feature to redirect the created images to a particular
           directory.

           You may also use the variable "IMAGE_BASE" which defines in a single line all base
           names for images generated by WML.

       file=filename
           Use this to explicitly set the output filename for the GIF image.  This is usually not
           used, because you don't need to know the actual filename. But sometimes it can be
           useful to explicitly set it.

       notag
           This forces "<gfont>" to expand to nothing, i.e. no resulting "<img>" tag. The image
           itself is still generated. In combination with the above "file" attribute this can be
           used to generate images to particular files which can be used at other positions, for
           instance inside "<rollover>" (see wml::des::rollover(3)) tags.

       color=#rrggbb
           Sets the font (foreground) color. Default is "#000000" which is black.

       bgcolor=#rrggbb
           Sets the image background color. Default is no color at all, i.e. transparent
           background.

       face=fontname
           Sets the type of the used font where fontname is actually any TeX-available font or a
           name alias from the Fontmap file of gFONT. See gfont(1) for more details. Default is
           "Times".

       size=number
           Sets the relative size of the font, similar to the HTML 3.2 "<font<" tag. Default is
           0. The following correspondence to pt-sizes exists:

            size:  -2 -1  0  1  2  3  4  5   6   7   8   9
              pt:  12 16 20 32 40 50 60 80 100 120 140 160

           This leads to nearly the same font sizes for "<font>" and "<gfont>" tags on typical
           browser setups.

       align=location
           This directly corresponds to the "align" attribute of the "<img>" tag.

       crop
           This indicates that the image should be cropped, i.e. the edges containing only the
           background color should be removed.

       adjust=spec
           This passes through spec to the -r option of gFONT which adjusts the size of the final
           image. Use this to expand the image and/or align it.

       :img:ATTR=STR
           The ``ATTR=STR'' pairs are passed along to the "<img>" HTML tag.

EXAMPLE

        <gfont face="HelveticaBold" size=+6 color="#3333cc">
        A sample Headerline
        </gfont>

AUTHOR

        Ralf S. Engelschall
        rse@engelschall.com
        www.engelschall.com

REQUIRES

        Internal: P1, P2, P3, Image::Size (P5M)
        External: gfont (PATH)

SEE ALSO

       HTML "<font>" tag, gfont(1), http://www.engelschall.com/sw/gfont/