@Section
   @Title { Including an illustration }
   @Tag { include }
@Begin
@PP
The @Code "@IncludeGraphic" symbol incorporates into a Lout document an
include.graphic @Index @Code "@IncludeGraphic"
include.illus @Index { including an illustration }
illustration (that is, an encapsulated PostScript or EPS file)
produced by other means.  For the opposite process, using Lout to produce
an illustration for inclusion in some other document, see
Section {@NumberOf illustrations}.
@PP
For example, suppose the encapsulated PostScript file @Code "su_crest.eps"
contains the University of Sydney crest.  Then
@ID @Code "@IncludeGraphic su_crest.eps"
produces
@ID @IncludeGraphic su_crest.eps
In general, the result produced by @Code "@IncludeGraphic" is an object
that may be scaled, rotated, made into a display or placed within a
paragraph, just like any other object.  Accolades for this remarkable
flexibility should go to the PostScript page description language,
whose extraordinary power makes the provision of this feature in Lout
almost trivial.
@PP
The @Code "@IncludeGraphic" command understands that files ending
with any of the suffixes {@Code ".gz"}, {@Code "-gz"}, {@Code ".z"},
{@Code "-z"}, {@Code "_z"}, and {@Code ".Z"} are compressed files,
and it will uncompress such files using the @Code "gunzip" command
before including them.  The uncompressed version is stored in a file
called @Code "lout.eps" in the current directory, and removed after
being copied into the output file.
@PP
If you place an included illustration in a line of text, or anywhere
where you care about its alignment with things on each side,
it will be positioned with its centre at the same height as the
centre of the letter x.  If this is not what you want, use the
@Code "@VShift" symbol from Section {@NumberOf precise}:
vshift. @Index @Code "@VShift"
@ID @Code "... +0.5f @VShift @IncludeGraphic ..."
prints the illustration half of the current font size higher on the
page than would otherwise have been the case, and
@ID @Code "... -0.5f @VShift @IncludeGraphic ..."
prints it half the current font size lower.
@PP
Sometimes you need to include the same EPS file many times, for
example once per page.  If it is a large file it can make the
output file very large to include it over and over again.  Lout
offers a solution to this problem, in the form of the
includegraphicrepeated. @Index @Code "@IncludeGraphicRepeated"
@Code "@IncludeGraphicRepeated" symbol.  You place this at
the start of your document, like this for example:
@ID @Code {
"@Include { doc }"
"@IncludeGraphicRepeated { su_crest.eps }"
}
(note the braces around the following EPS file name).  Adding
@Code "@IncludeGraphicRepeated" like this does not actually print the
graphic anywhere on any page; on the contrary, it is guaranteed to not
change the appearance of your document at all.  What it does do
is give Lout a hint that the EPS file between the braces is likely
to be included many times over in this document.  Lout then
handles this EPS file in a different way that involves copying it
into the PostScript output file just once, no matter how many
times it is included by subsequent @Code "@IncludeGraphic" symbols.
@PP
When your EPS file would otherwise be included many times over, using
@Code "@IncludeGraphicRepeated" definitely makes your PostScript
output file a lot shorter, and it usually makes it print faster as
well.  On the other hand, {@Code "@IncludeGraphicRepeated"} uses
Level 2 PostScript features which some older printers may not have,
and it consumes a lot of memory in the printer.  If memory runs out
your job will not print properly, so use @Code "@IncludeGraphicRepeated"
with caution.
@End @Section