From owner-svn-doc-all@FreeBSD.ORG Tue Jul 9 00:45:50 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id 6430CEC6; Tue, 9 Jul 2013 00:45:50 +0000 (UTC) (envelope-from wblock@wonkity.com) Received: from wonkity.com (wonkity.com [67.158.26.137]) by mx1.freebsd.org (Postfix) with ESMTP id 0AB88194C; Tue, 9 Jul 2013 00:45:49 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.7/8.14.7) with ESMTP id r690HC9b037930; Mon, 8 Jul 2013 18:17:12 -0600 (MDT) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.7/8.14.7/Submit) with ESMTP id r690HC3u037927; Mon, 8 Jul 2013 18:17:12 -0600 (MDT) (envelope-from wblock@wonkity.com) Date: Mon, 8 Jul 2013 18:17:12 -0600 (MDT) From: Warren Block To: Benjamin Kaduk Subject: Re: svn commit: r42194 - head/en_US.ISO8859-1/books/fdp-primer/docbook-markup In-Reply-To: Message-ID: References: <201307081903.r68J3VG0081299@svn.freebsd.org> User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (wonkity.com [127.0.0.1]); Mon, 08 Jul 2013 18:17:12 -0600 (MDT) Cc: svn-doc-head@freebsd.org, svn-doc-all@freebsd.org, doc-committers@freebsd.org, Warren Block X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 09 Jul 2013 00:45:50 -0000 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 >> 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' >> port is required. It is used to convert between the different >> image formats. This port is not in >> the textproc/docproj meta >> - port, it must be installed by hand. >> + port, it must be installed separately. >> >> The best example of what follows in practice is the >> doc/en_US.ISO8859-1/articles/vm-design/ >> - 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' >> >> >> When the reader is viewing the documentation in > > I think the "When" is superfluous here? > >> - HTML. 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. >> + HTML. 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. >> >> >> > > 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 , whitespace is significant. I'm not sure if there is a good solution.