diff options
author | Nik Clayton <nik@FreeBSD.org> | 2000-10-29 20:20:25 +0000 |
---|---|---|
committer | Nik Clayton <nik@FreeBSD.org> | 2000-10-29 20:20:25 +0000 |
commit | 4736b10accf6fc5c350120b69838b1a35170793a (patch) | |
tree | f0a6f41e708e301994ccbc03c9acafc011a30605 /en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml | |
parent | 7c4206c1aae962a46f80d2a459c0ec4e06fe65d1 (diff) | |
download | doc-4736b10accf6fc5c350120b69838b1a35170793a.tar.gz doc-4736b10accf6fc5c350120b69838b1a35170793a.zip |
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.
Notes
Notes:
svn path=/head/; revision=8236
Diffstat (limited to 'en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml')
-rw-r--r-- | en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml | 233 |
1 files changed, 232 insertions, 1 deletions
diff --git a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml index d5cfbfc947..39b0feb120 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml +++ b/en_US.ISO_8859-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><mediaobject> + <imageobject> + <imagedata fileref="fig1"> <co id="co-image-ext"> + </imageobject> + + <textobject> + <literallayout class="monospaced">+---------------+ <co id="co-image-literal"> +| A | ++---------------+</literallayout> + </textobject> + + <textobject> + <phrase>A picture</phrase> <co id="co-image-phrase"> + </textobject> +</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>… +IMAGES= fig1.eps fig2.png fig3.png +…</programlisting> + + <para>or</para> + + <programlisting>… +IMAGES= fig1.eps +IMAGES+= fig2.png +IMAGES+= fig3.png +…</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><mediaobject> + <imageobject> + <imagedata fileref="chapter1/fig1"> <co id="co-image-dir"> + </imageobject> + + … + +</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>… +IMAGES= chapter1/fig1.png +…</programlisting> + + <para>Then everything should just work.</para> + </sect3> + </sect2> + + <sect2> <title>Links</title> <note> |