Describe how to go about adding images to the documentation. A little

rushed, but it should be enough to get people using it, and, more
importantly, improving on it.

1 files changed, 232 insertions, 1 deletions

diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
index d5cfbfc947..39b0feb120 100644
--- a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
@@ -27,7 +27,7 @@
      ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
      POSSIBILITY OF SUCH DAMAGE.
 
-     $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml,v 1.14 2000/07/16 16:40:09 nik Exp $
+     $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml,v 1.15 2000/07/17 19:01:58 ben Exp $
 -->
 
 <chapter id="sgml-markup">
@@ -2104,6 +2104,237 @@ This is the file called 'foo2'</screen>
     </sect2>
 
     <sect2>
+      <title>Images</title>
+
+      <important>
+	<para>Image support in the documentation is currently extremely
+	  experimental.  I think the mechanisms described here are unlikely to
+	  change, but that's not guaranteed.</para>
+
+	<para>You will also need to install the
+	  <filename>graphics/ImageMagick</filename> port, which is used to
+	  convert between the different image formats.  This is a big port,
+	  and most of it is not required.  However, while we're working on the
+	  <filename>Makefile</filename>s and other infrastructure it makes
+	  things easier.  This port is <emphasis>not</emphasis> in the
+	  <filename>textproc/docproj</filename> meta port, you must install it
+	  by hand.</para>
+
+	<para>The best example of what follows in practice is the
+	  <filename>en_US.ISO_8859-1/articles/vm-design/</filename> document.
+	  If you're unsure of the description that follows, take a look at the
+	  files in that directory to see how everything hangs togther.
+	  Experiment with creating different formatted versions of the
+	  document to see how the image markup appears in the formatted
+	  output.</para>
+      </important>
+
+      <sect3>
+	<title>Image formats</title>
+
+	<para>We currently support two formats for images.  The format you
+	  should use will depend on the nature of your image.</para>
+
+	<para>For images that are primarily vector based, such as network
+	  diagrams, timelines, and similar, use Encapsulated Postscript, and
+	  make sure that your images have the <filename>.eps</filename>
+	  extension.</para>
+
+	<para>For bitmaps, such as screen captures, use the Portable Network
+	  Graphic format, and make sure that your images have the
+	  <filename>.png</filename> extension.</para>
+
+	<para>These are the <emphasis>only</emphasis> formats in which images
+	  should be committed to the CVS repository.</para>
+
+	<para>Use the right format for the right image.  It is to be expected
+	  that your documentation will have a mix of EPS and PNG images.  The
+	  <filename>Makefile</filename>s ensure that the correct format image
+	  is chosen depending on the output format that you use for your
+	  documentation.  <emphasis>Do not commit the same image to the
+	    repository in two different formats</emphasis>.</para>
+
+	<important>
+	  <para>It is anticipated that the Documentation Project will switch to
+	    using the Scalable Vector Graphic (SVG) format for vector images.
+	    However, the current state of SVG capable editing tools makes this
+	    impractical.</para>
+	</important>
+      </sect3>
+
+      <sect3>
+	<title>Markup</title>
+
+	<para>The markup for an image is relatively simple.  First, markup a
+	  <sgmltag>mediaobject</sgmltag>.  The <sgmltag>mediaobject</sgmltag>
+	  can contain other, more specific objects.  We are concerned with
+	  two, the <sgmltag>imageobject</sgmltag> and the
+	  <sgmltag>textobject</sgmltag>.</para>
+
+	<para>You should include one <sgmltag>imageobject</sgmltag>, and two
+	  <sgmltag>textobject</sgmltag> elements.  The
+	  <sgmltag>imageobject</sgmltag> will point to the name of the image
+	  file that will be used (without the extension).  The
+	  <sgmltag>textobject</sgmltag> elements contain information that will
+	  be presented to the user as well as, or instead of, the
+	  image.</para>
+
+	<para>There are two circumstances where this can happen.</para>
+
+	<itemizedlist>
+	  <listitem>
+	    <para>When the reader is viewing the documentation in HTML.  In
+	      this case, each image will need to have associated alternate
+	      text to show the user, typically whilst the image is loading, or
+	      if they hover the mouse pointer over the image.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>When the reader is viewing the documentation in plain text.
+	      In this case, each image should have an ASCII art equivalent to
+	      show the user.</para>
+	  </listitem>
+	</itemizedlist>
+
+	<para>An example will probably make things easier to understand.
+	  Suppose you have an image, called <filename>fig1</filename>, that
+	  you want to include in the document.  This image is of a rectangle
+	  with an A inside it.  The markup for this would be as
+	  follows.</para>
+
+	<programlisting>&lt;mediaobject>
+  &lt;imageobject>
+    &lt;imagedata fileref="fig1"> <co id="co-image-ext">
+  &lt;/imageobject>
+
+  &lt;textobject>
+    &lt;literallayout class="monospaced">+---------------+ <co id="co-image-literal">
+|       A       |
++---------------+&lt;/literallayout>
+  &lt;/textobject>
+
+  &lt;textobject>
+    &lt;phrase>A picture&lt;/phrase> <co id="co-image-phrase">
+  &lt;/textobject>
+&lt;/mediaobject></programlisting>
+
+	<calloutlist>
+	  <callout arearefs="co-image-ext">
+	    <para>Include an <sgmltag>imagedata</sgmltag> element inside the
+	      <sgmltag>imageobject</sgmltag> element.  The
+	      <literal>fileref</literal> attribute should contain the filename
+	      of the image to include, without the extension.  The stylesheets
+	      will work out which extension should be added to the filename
+	      automatically.</para>
+	  </callout>
+
+	  <callout arearefs="co-image-literal">
+	    <para>The first <sgmltag>textobject</sgmltag> should contain a
+	      <sgmltag>literallayout</sgmltag> element, where the
+	      <literal>class</literal> attribute is set to
+	      <literal>monospaced</literal>.  This is your opportunity to
+	      demonstrate your ASCII art skills.  This content will be used if
+	      the document is converted to plain text.</para>
+
+	    <para>Notice how the first and last lines of the content of the
+	      <sgmltag>literallayout</sgmltag> element butt up next to the
+	      element's tags.  This ensures no extraneous white space is
+	      included.</para>
+	  </callout>
+
+	  <callout arearefs="co-image-phrase">
+	    <para>The second <sgmltag>textobject</sgmltag> should contain a
+	      single <sgmltag>phrase</sgmltag> element.  The contents of this
+	      will become the <literal>alt</literal> attribute for the image
+	      when this document is converted to HTML.</para>
+	  </callout>
+	</calloutlist>
+      </sect3>
+
+      <sect3>
+	<title><filename>Makefile</filename> entries</title>
+
+	<para>Your images must be listed in the
+	  <filename>Makefile</filename> in the <makevar>IMAGES</makevar>
+	  variable.  This variable should contain the name of all your
+	  <emphasis>source</emphasis> images.  For example, if you have
+	  created three figures, <filename>fig1.eps</filename>,
+	  <filename>fig2.png</filename>, <filename>fig3.png</filename>, then
+	  your <filename>Makefile</filename> should have lines like this in
+	  it.</para>
+
+	<programlisting>&hellip;
+IMAGES= fig1.eps fig2.png fig3.png
+&hellip;</programlisting>
+
+	<para>or</para>
+
+	<programlisting>&hellip;
+IMAGES=  fig1.eps
+IMAGES+= fig2.png
+IMAGES+= fig3.png
+&hellip;</programlisting>
+
+	<para>Again, the <filename>Makefile</filename> will work out the
+	  complete list of images it needs to build your source document, you
+	  only need to list the image files <emphasis>you</emphasis>
+	  provided.</para>
+      </sect3>
+
+      <sect3>
+	<title>Images and chapters in subdirectories</title>
+
+	<para>You must be careful when you separate your documentation in to
+	  smaller files (see <xref linkend="sgml-primer-include-using-gen-entities">) in
+	  different directories.</para>
+	  
+	<para>Suppose you have a book with three chapters, and the chapters
+	  are stored in their own directories, called
+	  <filename>chapter1/chapter.sgml</filename>,
+	  <filename>chapter2/chapter.sgml</filename>, and
+	  <filename>chapter3/chapter.sgml</filename>.  If each chapter has
+	  images associated with it, I suggest you place those images in each
+	  chapter's subdirectory (<filename>chapter1/</filename>,
+	  <filename>chapter2/</filename>, and
+	  <filename>chapter3/</filename>).</para>
+
+	<para>However, if you do this you must include the directory names in
+	  the <makevar>IMAGES</makevar> variable in the
+	  <filename>Makefile</filename>, <emphasis>and</emphasis> you must
+	  include the directory name in the <sgmltag>imagedata</sgmltag>
+	  element in your document.</para>
+
+	<para>For example, if you have <filename>chapter1/fig1.png</filename>,
+	  then <filename>chapter1/chapter.sgml</filename> should
+	  contain</para>
+
+	<programlisting>&lt;mediaobject>
+  &lt;imageobject>
+    &lt;imagedata fileref="chapter1/fig1"> <co id="co-image-dir">
+  &lt;/imageobject>
+
+  &hellip;
+
+&lt;/mediaobject></programlisting>
+	
+	<calloutlist>
+	  <callout arearefs="co-image-dir">
+	    <para>The directory name must be included in the
+	      <literal>fileref</literal> attribute</para>
+	  </callout>
+	</calloutlist>
+
+	<para>The <filename>Makefile</filename> must contain</para>
+
+	<programlisting>&hellip;
+IMAGES=  chapter1/fig1.png
+&hellip;</programlisting>
+
+	<para>Then everything should just work.</para>
+      </sect3>
+    </sect2>
+    
+    <sect2>
       <title>Links</title>
 
       <note>