1 files changed, 47 insertions, 0 deletions
diff --git a/doc/user/bgr_incl b/doc/user/bgr_incl
new file mode 100644
index 0000000..57ac4a1
--- /dev/null
+++ b/doc/user/bgr_incl
@@ -0,0 +1,47 @@
+@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 either side of it,
+it will be positioned with its centre at the same height as the
+centre of the letter x.  If this is not where you want it, use the
+@Code "@VShift" symbol:
+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.  Any length (Section
+{@NumberOf objects}) is allowed, and the object following @Code "@VShift"
+may in fact be arbitrary as usual.
+@End @Section