Date: Mon, 8 Jul 2013 18:17:12 -0600 (MDT) From: Warren Block <wblock@wonkity.com> To: Benjamin Kaduk <kaduk@MIT.EDU> Cc: svn-doc-head@freebsd.org, svn-doc-all@freebsd.org, doc-committers@freebsd.org, Warren Block <wblock@freebsd.org> Subject: Re: svn commit: r42194 - head/en_US.ISO8859-1/books/fdp-primer/docbook-markup Message-ID: <alpine.BSF.2.00.1307081813550.37839@wonkity.com> In-Reply-To: <alpine.GSO.1.10.1307081801490.26275@multics.mit.edu> References: <201307081903.r68J3VG0081299@svn.freebsd.org> <alpine.GSO.1.10.1307081801490.26275@multics.mit.edu>
next in thread | previous in thread | raw e-mail | index | archive | help
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.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.BSF.2.00.1307081813550.37839>