<!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<!--ArborText, Inc., 1988-1998, v.4002-->
<article><?dbhtml filename="imagelib.html" chunk='no' output-dir="../doc">
<artheader>
<title>Image Library Files</title>
<author><firstname>Norman</firstname><surname>Walsh</surname></author><pubdate>
17 Nov 1998</pubdate>
<abstract>
<para>Additional information about graphics files can be used to improve
the presentation of images. In particular, passing the height and width
of a graphic to a web browser improves layout and alternative text should
always be used. Image library files provide a mechanism for passing this
information to the DocBook DSSSL Stylesheets.</para>
</abstract>
</artheader>
<para>
Image library files can be used to pass additional information 
about images to the stylesheet.  The HTML stylesheet uses this information
in the <sgmltag>IMG</sgmltag> tag; the print stylesheet may someday be
able to use this information to get proper spacing around images, but I
don't quite have that worked out yet.
</para>
<sect1><title>Image Library File Format</title>
<para>
Image library files are <emphasis>XML</emphasis> documents conforming
the image library DTD shown in <xref linkend="fig.ilibdtd">.
</para>
<figure id="fig.ilibdtd"><title>The Image Library DTD</title>
<programlisting>
<inlinegraphic format=linespecific fileref="../dtds/imagelib/imagelib.dtd">
</inlinegraphic>
</programlisting>
</figure>
<para>
The stylesheets use the filename of the graphic file (either the name
entered in the <sgmltag class=attribute>fileref</sgmltag> attribute
or the system identifier of the entity in the 
<sgmltag class=attribute>entityref</sgmltag> attribute) to locate
the appropriate image in the library.
</para>
</sect1>
<sect1><title>Creating Image Library Files</title>
<para>
At present, the files have to be created by hand. It's easy to imagine
a tool that could scan the graphics and build the file (or at least part
of the file) automatically, but none have been written yet.
</para>
</sect1>
<sect1><title>Image Library File Location</title>
<para>
The default location for image library files is 
<filename>imagelib/imagelib.xml</filename>. Using a subdirectory
allows the image library file to be in XML while the documents may be
in SGML.  If you're formatting XML documents, you can move the image
library into the same directory as your documents.
</para>
<sect2><title>The Catalog Trick</title>
<para>
If you're formatting SGML documents, you have to employ a catalog
trick in order to get Jade to properly parse the image library file.
Add a catalog to the <filename>imagelib</filename> directory that
contains the single line:
<screen>
SGMLDECL "<replaceable>path/to/xml.dcl</replaceable>"
</screen>
</para>
<para>
Jade will use that declaration to process all the documents in the
<filename>imagelib</filename> directory.
</para>
</sect2>
</sect1>
<sect1><title>Using the Image Library</title>
<para>
You can use the image library in one of two ways:
<orderedlist>
<listitem><para>Turn on <literal>image-library</literal> in your
stylesheet:
<screen>
(define image-library #t)
</screen>
</para>
</listitem>
<listitem><para>Use the <option>-V image-library</option> option when
you run jade.
</para>
</listitem>
</orderedlist>
</para>
</sect1>
<sect1><title>An Example</title>
<para>
See the examples in the <filename>test</filename> directory.</para>
</sect1>
</article>