aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml233
-rw-r--r--en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml233
2 files changed, 464 insertions, 2 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>
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>&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>