svn commit: r42198 - head/en_US.ISO8859-1/books/fdp-primer/docbook-markup

[Warren Block]

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 at .

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>