Date: Tue, 9 Jul 2013 00:53:37 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42198 - head/en_US.ISO8859-1/books/fdp-primer/docbook-markup Message-ID: <201307090053.r690rbuX078826@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Tue Jul 9 00:53:36 2013 New Revision: 42198 URL: http://svnweb.freebsd.org/changeset/doc/42198 Log: Improve clarity, get the hippo down off the stilts. Some improvements suggested by bjk@. Modified: head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Modified: head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Mon Jul 8 21:52:47 2013 (r42197) +++ head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Tue Jul 9 00:53:36 2013 (r42198) @@ -1746,27 +1746,25 @@ This is the file called 'foo2'</screen> experimental. The mechanisms described here are unlikely to change, but that is not guaranteed.</para> - <para>Installation of the + <para>To provide conversion between different image formats, the <filename role="package">graphics/ImageMagick</filename> - port is required. It is used to convert between the different - image formats. This port is <emphasis>not</emphasis> in + port must be installed. This port is not included in the <filename role="package">textproc/docproj</filename> meta - port, it must be installed separately.</para> + port, and must be installed separately.</para> - <para>The best example of what follows in practice is the + <para>A good example of the use of images is the <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename> - document. If the description that follows is unclear, - look at the files in that directory to see how everything - hangs together. Experiment with creating different formatted - versions of the document to see how the image markup appears - in the formatted output.</para> + document. Examine the files in that directory to see how + these elements are used together. Build different output + formats to see how the format determines what images are shown + in the rendered document.</para> </important> <sect2 id="docbook-markup-image-formats"> <title>Image Formats</title> - <para>Two image formats are currently supported. Which to - use depends on the nature of the image.</para> + <para>Two image formats are currently supported. The type of + image determines which format to use.</para> <para>Images that are primarily vector based, such as network diagrams, time lines, and similar, should be in @@ -1780,7 +1778,7 @@ This is the file called 'foo2'</screen> extension.</para> <para>These are the <emphasis>only</emphasis> formats in which - images should be committed to the Subversion + images should be committed to the documentation repository.</para> <para>Use the appropriate format for each image. It is to be @@ -1857,30 +1855,16 @@ This is the file called 'foo2'</screen> that will be presented to the user as well as, or instead of, the image itself.</para> - <para>There are two circumstances where this can - happen.</para> + <para>Text elements are shown to the reader in several + situations. When the document is viewed in + <acronym>HTML</acronym>, text elements are shown while the + image is loading, or if the mouse pointer is hovered over the + image, or if a text-only browser is being used. In formats + like plain text where graphics are not possible, the text + elements are shown instead of the graphical ones.</para> - <itemizedlist> - <listitem> - <para>When the reader is viewing the documentation in - <acronym>HTML</acronym>. In this case, each image - needs associated alternate text to show the user, typically - while the image is loading, or if the mouse - pointer is hovered 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 - <acronym>ASCII</acronym> art equivalent to show the - user.</para> - - </listitem> - </itemizedlist> - - <para>An example will make things easier to understand. Suppose - there is an image called <filename>fig1.png</filename> that is - to be included in the document. This image is of a rectangle + <para>This example shows how to include an image called + <filename>fig1.png</filename> in a document. The image is a rectangle with an A inside it:</para> <programlisting><sgmltag class="starttag">mediaobject</sgmltag> @@ -2016,8 +2000,6 @@ IMAGES+= fig3.png <programlisting>… IMAGES= chapter1/fig1.png …</programlisting> - - <para>Then everything will work.</para> </sect2> </sect1>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201307090053.r690rbuX078826>