From owner-svn-doc-all@FreeBSD.ORG Tue Jul 9 00:53:37 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id 41457178; Tue, 9 Jul 2013 00:53:37 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id 32B40199E; Tue, 9 Jul 2013 00:53:37 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r690rbpQ078827; Tue, 9 Jul 2013 00:53:37 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r690rbuX078826; Tue, 9 Jul 2013 00:53:37 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201307090053.r690rbuX078826@svn.freebsd.org> From: Warren Block Date: Tue, 9 Jul 2013 00:53:37 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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:53:37 -0000 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' experimental. The mechanisms described here are unlikely to change, but that is not guaranteed. - Installation of the + To provide conversion between different image formats, the graphics/ImageMagick - port is required. It is used to convert between the different - image formats. This port is not in + port must be installed. This port is not included in the textproc/docproj meta - port, it must be installed separately. + port, and must be installed separately. - The best example of what follows in practice is the + A good example of the use of images is the doc/en_US.ISO8859-1/articles/vm-design/ - 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. + 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. Image Formats - Two image formats are currently supported. Which to - use depends on the nature of the image. + Two image formats are currently supported. The type of + image determines which format to use. 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' extension. These are the only formats in which - images should be committed to the Subversion + images should be committed to the documentation repository. Use the appropriate format for each image. It is to be @@ -1857,30 +1855,16 @@ This is the file called 'foo2' that will be presented to the user as well as, or instead of, the image itself. - There are two circumstances where this can - happen. + Text elements are shown to the reader in several + situations. When the document is viewed in + HTML, 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. - - - When the reader is viewing the documentation in - HTML. 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. - - - - When the reader is viewing the documentation in - plain text. In this case, each image should have an - ASCII art equivalent to show the - user. - - - - - An example will make things easier to understand. Suppose - there is an image called fig1.png that is - to be included in the document. This image is of a rectangle + This example shows how to include an image called + fig1.png in a document. The image is a rectangle with an A inside it: mediaobject @@ -2016,8 +2000,6 @@ IMAGES+= fig3.png … IMAGES= chapter1/fig1.png … - - Then everything will work.