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

[Warren Block]

On Mon, 8 Jul 2013, Benjamin Kaduk wrote:

> On Mon, 8 Jul 2013, Warren Block wrote:
>
>> Author: wblock
>> Date: Mon Jul  8 19:03:30 2013
>> New Revision: 42194
>> URL: http://svnweb.freebsd.org/changeset/doc/42194
>> 
>> Log:
>>  Add section on location of images.  Rework examples to use <sgmltag>
>>  instead of CDATA.
>> 
>> 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 18:09:56 2013	(r42193)
>> +++ head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml	Mon 
>> Jul  8 19:03:30 2013	(r42194)
>> @@ -1751,11 +1751,11 @@ This is the file called 'foo2'</screen>
>> 	port is required.  It is used to convert between the different
>> 	image formats.  This port is <emphasis>not</emphasis> in
>> 	the <filename role="package">textproc/docproj</filename> meta
>> -	port, it must be installed by hand.</para>
>> +	port, it must be installed separately.</para>
>>
>>       <para>The best example of what follows in practice is the
>> 	<filename>doc/en_US.ISO8859-1/articles/vm-design/</filename>
>> -	document.  If the description that follows is unclear, take a
>> +	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
>
> "hangs together" seems similarly informal to "take a look"

Agreed.

>> 	versions of the document to see how the image markup appears
>> @@ -1825,10 +1860,10 @@ This is the file called 'foo2'</screen>
>>       <itemizedlist>
>> 	<listitem>
>> 	  <para>When the reader is viewing the documentation in
>
> I think the "When" is superfluous here?
>
>> -	    <acronym>HTML</acronym>.  In this case, each image will
>> -	    need associated alternate text to show the user, typically
>> -	    while the image is loading, or if they hover the mouse
>> -	    pointer over the image.</para>
>> +	    <acronym>HTML</acronym>.  In this case, each image
>> +	    needs associated alternate text to show the user, typically
>
> I hung up a little parsing "each image needs associated alternate text to 
> show the user", but I'm not convinced that it's actually wrong.  I sondered 
> adding "an" before "associated" and "to" after "show".

The more I look at the section, the more it appears to be replaceable 
with a simple paragraph rather than an overly-complicated list.

>> +	    while the image is loading, or if the mouse
>> +	    pointer is hovered over the image.</para>
>> 	</listitem>
>>
>> 	<listitem>
>
> The programlistings (not shown) are a bit hard to read in source form due to 
> long lines.  I guess it's best to review those in rendered form, anyway.

Agreed on that also.  The problem is that inside a <programlisting>, 
whitespace is significant.  I'm not sure if there is a good solution.