Figures in format-independent documents are a problem. You bf(cannot) avoid
contact with the final format (HTML, LaTeX or whatever) if you want to include
figures in a text.

The way Yodl approaches figures, is currently the folloowing.

startit()

    it() Figures can only be included in LaTeX or in HTML documents.

    it() For LaTeX, you must prepare a picture in an external file that is
    included in the document as en em(encapsulated PostScript) file.
    Incidentally, that means that tt(epsf) must be stated as one of the LaTeX
    styles using tt(latexoptions) macro.

    The file in question is stated in Yodl without an extension. Yodl provides a
    default extension, being tt(.ps).

    it() For HTML, you must prepare a picture in an external file that is placed
    in the document using the tt(<img src=...>) stanza. The file must be a GIF
    file. The file is -again- stated without the filename extension; Yodl
    supplies tt(.gif).

    it() All other output formats do not include pictures in the document, but
    typeset something like em(insert figure .. here).

endit()

The macro to include a figure is called, appropriately, tt(figure). It takes
three arguments:

startit()

    it() The first argument is the filename. This name may include directories,
    but may not include the filename extension. The reason for this is, that
    Yodl supplies the correct extension once the output format is known.

    it() The second argument is the figure title, or the caption. Yodl prefixes
    this caption with the text em(Figure xx:), where em(xx) is a number.

    it() The last argument is a label, which Yodl defines as a placeholder for
    the figure number.

endit()

For example, you might draw a picture or scan a photo and put it in a tt(.gif)
file, for usage with HTML documents. The conversion to PostScript could be
automated, e.g., using a Yodl macro:

verb(SYSTEM(xpmtoppm picture.xpm | pnmtops > picture.ps))

See the discussion of the tt(SYSTEM) macro (section ref(system)) for the danger
of live data and how Yodl handles them.

After this, you would be reasonably safe that the picture is available for both
HTML and LaTeX output. The picture would be typeset in a figure using:

verb(\
figure(picture)
      (A photo of me.)
      (photo))

Note how the first argument, the filename, does not contain an extension. The
third argument, which is a label, can be used in, e.g.,

verb(See figure ref(photo) for a photograph.)

Yodl has a few auxiliary macros, which are:

startit()

    it() tt(fig(label)): This macro is a shorthand for tt(getfigurestring()
    ref(label)). It just makes typing shorter, and is used as e.g.: tt(See
    fig(photo) for a photograph.) Note that the string tt(figure) that is
    generated by this macro can be (re)defined, see below.

    it() tt(setfigurestring(name)): This macro is similar to
    tt(setchapterstring) etc.. It defines the string that is used to identify a
    figure, and is (appropriately) tt(figure) by default. The macro
    tt(getfigurestring()) expands to the string in question. See also section
    ref(national) for a discussion of national language support. 
    
    it() tt(sethtmlfigureext(.new)): This macro redefines the filename extension
    for HTML conversions from tt(.gif) to tt(.new). Note that you must include a
    leading dot in the redefinition.

    The new extension is used in the first following tt(figure) statement.

    it() tt(sethtmlfigurealign(align)): This redefines the alignment of figures
    in HTML, which is default tt(bottom). Check your HTML handbook for possible
    options; tt(top) and tt(center) should be fairly standard.

    it() tt(setlatexfigureext(.new)): Redefines the extension from tt(.ps) to
    tt(.new).

endit()

Finally, an example of a picture is shown in figure ref(world). The picture is
also distributed with the Yodl package as tt(Documentation/pictures/world.xpm).

sethtmlfigureext(.png)
setlatexfigureext(.eps)
figure(world)(Sample picture in a figure.)(Documentation/pictures/DOEXPAND(outdir)/world)

