@Section
   @Title { Figures and tables }
   @Tag { figures }
@Begin
@PP
Figures are created in a similar way to footnotes:
figures. @Index { figures }
@ID @OneRow @Code {
"@Figure"
"    @Caption { Basser Lout }"
"@Fig {"
"    { @Box Lout }{ @HArrow { 2c @Wide } }{ @Box PostScript }"
"}"
}
The @Code "@Figure" symbol places the figure (which in this example is
figure. @Index @Code "@Figure"
created using the advanced graphics features of Chapter {@NumberOf fig})
at the top of the following column or page,
@Figure
    @Tag { figex }
    @Caption { Basser Lout }
@Fig {
    { @Box Lout }{ @HArrow { 2c @Wide } }{ @Box PostScript }
}
labelled by the @Code "@Caption" option and automatically numbered.  You
captions. @RawIndex { captions }
captions.figures @SubIndex { in @Code "@Figure" and @Code "@Table" }
can see this example at the top of page {@PageOf figex}.  Tables are
table. @Index @Code "@Table"
obtained in the same way using {@Code "@Table"} instead of {@Code "@Figure"}.
@PP
@Code "@Figure" and @Code "@Table" each have an @Code "@InitialLanguage"
option which determines the language of the figure or table.  If this is
omitted, the language of the document as a whole will be used, not the
language where the figure or table occurs.
@PP
If your document contains many figures, large figures, or multi-page
figures, you are likely to encounter cases where Lout's assignment of
figures to pages is not pleasing.  In that case, you can improve things
by moving the figures around within the body text, and by using the
following options.
@PP
The @Code "@Figure" symbol has a @Code "@Location" option which determines
location. @Index @Code "@Location"
where the figure will appear.  Its possible values are
@ID @Tab
    @Fmta { @Col @Code A ! @Col B }
{
@Rowa
    A { PageTop }
    B { The figure will appear at the top of the following page, occupying
the full page width; or, if there is insufficient space there (owing to other
figures already present), at the top of the first subsequent page with
sufficient space. }
@Rowa
    A { PageFoot }
    B { The figure will appear at the foot of the current page, occupying
the full page width; or, if there is insufficient space there, at the top
of the following page and so on as for {@Code PageTop}. }
@Rowa
    A { ColTop }
    B { The figure will appear at the top of the following column,
occupying the column width; or, if there is insufficient space there,
at the top of the first subsequent column with sufficient space.  This
is different from @Code PageTop only in multi-column documents. }
@Rowa
    A { ColFoot }
    B { The figure will appear at the foot of the current column,
occupying the column width; or, if there is insufficient space there, at
the top of the following column and so on as for {@Code ColTop}.  This
is different from @Code PageFoot only in multi-column documents. }
@Rowa
    A { ColEnd }
    B { The figure will appear in a column at the end of the document
(or chapter, appendix etc. in the case of books).  There is no
@Code PageEnd value corresponding to {@Code ColEnd}. }
@Rowa
    A { AfterLine }
    B { The figure will appear as a column-width display immediately after
the line in the final printed document in which it occurs. }
@Rowa
    A { TryAfterLine }
    B { The same as @Code {AfterLine} unless there is insufficient space
in the current column to hold the displayed figure, in which case it
switches to @Code {ColTop} instead. }
@Rowa
    A { Display }
    B { The figure will appear as a display at the point it occurs.  There
is no @Code TryDisplay value corresponding to {@Code Display}. }
@Rowa
    A { Raw }
    B { The figure will appear as an object, with no extra spacing, at
the point it occurs.  This is useful, for example, for getting two figures
side by side in one display:  use a displayed table containing two raw
figures. }
}
The @Code "@Table" symbol also has this option.  The default location is
{@Code "PageTop"}, but this can be changed by changing the
figurelocation. @Index @Code "@FigureLocation"
tablelocation. @Index @Code "@TableLocation"
@Code "@FigureLocation" and @Code "@TableLocation" setup file options.
@PP
The numbers assigned to figures and tables, and their ordering in any list
of figures or tables, is based on where they appear in the final printed
document, not on where they appear in the source files.  This is better for
the reader in the unusual case of a fixed figure being overtaken by a
floating one.
@PP
@Code "@Figure" and @Code "@Table" each have a @Code "@OnePage" option,
whose value may be @Code "Yes" or {@Code No}.  Setting @Code "@OnePage"
to @Code Yes causes the figure or table and its caption to be kept
together on one page or column (enclosing the body of the figure or table
in @Code "@OneRow" would have the same effect except that it would not
incorporate the caption, hence the need for this option).  You need to be
certain that the whole assembly will fit on one page when setting
@Code "@OnePage" to {@Code "Yes"}.
@PP
The @I default value of the @Code "@OnePage" option for each figure or
table depends on the value of its @Code "@Location" option as follows:
@ID @Tab
    @Fmta { @Col @Code A ! @Col ! @Col @Code B }
{
@Rowa
    A { No }
    B { PageTop  ColTop  ColEnd  Raw }
@Rowa
    A { Yes }
    B { PageFoot  ColFoot  Display  AfterLine  TryAfterLine }
}
These choices represent a guess that figures that the user is happy to
see at the page foot or in a display are probably going to be small enough
to keep on one page, but that other figures may not be.  In any case, these
are only default values and you may set @Code "@OnePage" to whatever you
prefer.
@PP
@Code "@Figure" and @Code "@Table" also have a @Code "@FullPage" option,
whose value may again be either @Code Yes or {@Code No}, with default
value {@Code No}.  Setting this option to @Code "Yes" causes the figure
or table to occupy the full page (quite a different thing from being kept
together on one page), by adding white space below the caption.  This is
mainly useful when the figure or table occupies nearly all of one or more
pages, with one or two silly-looking lines of body text at the bottom.  To
be precise, this option does not prevent the figure or table from appearing
on a page which already contains other things; rather, it ensures that
nothing more will be placed on the page after the figure or table is.  The
only way to ensure that a figure or table starts on a fresh page is to make
sure that there are no other figures and tables (other than full-page ones)
closely preceding it in the document.
@PP
By default, the body of the figure will be centred, and this usually looks
best, at least for small figures.  @Code "@Figure" and @Code "@Table" each
have a @Code "@Format" option which controls this format:
@ID @Code {
"@Figure"
"    @Format { @CurveBox @HExpand { @CentredDisplay @Body } }"
}
Within the @Code "@Format" option, the @Code "@Body" symbol stands
for the body of the figure or table.  This example centres the figure
inside a @Code "@CurveBox" which is horizontally expanded (by the
@Code "@HExpand" symbol) to occupy the full width of the page or
column, rather than fitting snugly around the figure.  Actually the
most useful format is probably just
@ID @Code {
"@Figure"
"    @Format { @Body }"
}
which turns off the default centring.  This is the most practical format
for multi-page figures, for example.
@PP
There are setup file options called @Code "@FigureNumbers" and
figurenumbers. @Index @Code "@FigureNumbers"
tablenumbers. @Index @Code "@TableNumbers"
@Code "@TableNumbers" that determine whether figures and tables are
numbered automatically or not.  Your choices for these options are
{@Code "None"}, {@Code "Arabic"}, {@Code "Roman"}, {@Code "UCRoman"},
{@Code "Alpha"}, and {@Code "UCAlpha"}.  Depending on the document
type and where the figure or table occurs, the number might include
a chapter number as well.
@PP
There are also setup file options called @Code "@CaptionFont" and
@Code "@CaptionBreak" which determine the font and paragraph breaking
style used in the captions of figures and tables.  Their default
values are empty, meaning to use the initial font and break styles;
but, for example, you could have
@ID @Code "@CaptionFont { -2p }"
in your setup file to get a smaller font size in your captions.
@PP
There are setup file options called @Code "@FigureCaptionPos" and
figurecaptionpos. @Index @Code "@FigureCaptionPos"
tablecaptionpos. @Index @Code "@TableCaptionPos"
@Code "@TableCaptionPos" which determine whether the captions to
figures and tables appear above or below them.  The default value
is {@Code "Below"} and the alternative is {@Code "Above"}.  Also,
@Code "@Figure" and @Code "@Table" have a @Code "@CaptionPos"
option:
@ID @Code {
"@Figure"
"    @CaptionPos { Above }"
}
which allows this to be set individually for each figure or table.
@PP
You can get a list of figures at the start of your document by setting
the @Code "@MakeFigureContents" setup file option to {@Code Yes}.  There
is also a @Code "@MakeTableContents" setup file option for making a
separate list of tables.  The format of these lists will follow the
format of tables of contents.  These lists are only available in books
(Section {@NumberOf books}).
@PP
Owing to problems behind the scenes, a figure or table on a page
without body text at the end of a chapter may have an inappropriate
running header.  If this happens, the recommended workaround
is either to move the figure to an earlier point in the document, so
that it comes out on a page that also has some body text, or else to
place one or more @Code "@NP" (new page) symbols at the end of
the chapter (or at the end of its last section, subsection, etc.).
@End @Section
