From owner-svn-doc-all@FreeBSD.ORG Mon Jul 8 19:03:31 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 5C32CE89; Mon, 8 Jul 2013 19:03:31 +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 4DA5A12B5; Mon, 8 Jul 2013 19:03:31 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r68J3VB5081300; Mon, 8 Jul 2013 19:03:31 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r68J3VG0081299; Mon, 8 Jul 2013 19:03:31 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201307081903.r68J3VG0081299@svn.freebsd.org> From: Warren Block Date: Mon, 8 Jul 2013 19:03:31 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42194 - 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: Mon, 08 Jul 2013 19:03:31 -0000 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) @@ -1742,8 +1742,8 @@ This is the file called 'foo2' Images - Image support in the documentation is currently - extremely experimental. The mechanisms described here are + Image support in the documentation is somewhat + experimental. The mechanisms described here are unlikely to change, but that is not guaranteed. Installation of the @@ -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 versions of the document to see how the image markup appears @@ -1766,7 +1766,7 @@ This is the file called 'foo2' Image Formats Two image formats are currently supported. Which to - choose will depend on the nature of the image. + use depends on the nature of the image. Images that are primarily vector based, such as network diagrams, time lines, and similar, should be in @@ -1787,8 +1787,8 @@ This is the file called 'foo2' expected that documentation will have a mix of EPS and PNG images. The Makefiles ensure that the correct format - image is chosen depending on the output format that you use - for your documentation. Do not commit the same + image is chosen depending on the output format used. + Do not commit the same image to the repository in two different formats. @@ -1801,11 +1801,46 @@ This is the file called 'foo2' + + Image File Locations + + Image files can be stored in one of several + locations, depending on the document and image: + + + + In the same directory as the document itself, usually + done for articles and small books that keep all their + files in a single directory. + + + + In a subdirectory of the main document. Typically + done when a large book uses separate subdirectories to + organize individual chapters. + + When images are stored in a subdirectory of the + main document directory, the subdirectory name must be + included in their paths in the + Makefile and the + imagedata element. + + + + In a subdirectory of + doc/share/images. + Images that apply to multiple translations are stored in + this upper level of the documentation file tree. + Generally, these are images that do not require + translation for use in non-English documents. + + + + Image Markup - The markup for an image is relatively simple. First, - markup a mediaobject. The + Images are included as part of a mediaobject. The mediaobject can contain other, more specific objects. We are concerned with two, the imageobject and the @@ -1814,7 +1849,7 @@ This is the file called 'foo2' Include one imageobject, and two textobject elements. The imageobject will point to the name of the - image file (without the extension). The + image file without the extension. The textobject elements contain information that will be presented to the user as well as, or instead of, the image itself. @@ -1825,10 +1860,10 @@ This is the file called 'foo2' When the reader is viewing the documentation in - 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 + while the image is loading, or if the mouse + pointer is hovered over the image. @@ -1843,24 +1878,23 @@ This is the file called 'foo2' 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 - with an A inside it. The markup for this would be as - follows. + with an A inside it: - <mediaobject> - <imageobject> - <imagedata fileref="fig1"> - </imageobject> + mediaobject + imageobject + imagedata fileref="fig1" + imageobject - <textobject> - <literallayout class="monospaced">+---------------+ + textobject + literallayout class="monospaced"+---------------+ | A | -+---------------+</literallayout> - </textobject> ++---------------+literallayout + textobject - <textobject> - <phrase>A picture</phrase> - </textobject> -</mediaobject> + textobject + phraseA picturephrase + textobject +mediaobject @@ -1940,7 +1974,7 @@ IMAGES+= fig3.png chapter1/chapter.xml, chapter2/chapter.xml, and chapter3/chapter.xml. If each chapter - has images associated with it, it is suggested to place + has images associated with it, place those images in each chapter's subdirectory (chapter1/, chapter2/, and @@ -1958,14 +1992,14 @@ IMAGES+= fig3.png chapter1/chapter.xml should contain: - <mediaobject> - <imageobject> - <imagedata fileref="chapter1/fig1"> - </imageobject> + mediaobject + imageobject + imagedata fileref="chapter1/fig1" + imageobject … -</mediaobject> +mediaobject @@ -2011,18 +2045,18 @@ IMAGES= chapter1/fig1.png <literal>id</literal> on Chapters and Sections - - Introduction + chapter id="introduction" + titleIntroductiontitle - This is the introduction. It contains a subsection, - which is identified as well. + paraThis is the introduction. It contains a subsection, + which is identified as well.para - - More Details + sect1 id="introduction-moredetails" + titleMore Detailstitle - This is a subsection. - -]]> + paraThis is a subsection.para + sect1 +chapter Use descriptive values for id names. @@ -2043,9 +2077,9 @@ IMAGES= chapter1/fig1.png <sgmltag>anchor</sgmltag> - This paragraph has an embedded - link target in it. It will not - show up in the document.]]> + paraThis paragraph has an embedded + anchor id="para1"link target in it. It will not + show up in the document.para @@ -2066,11 +2100,11 @@ IMAGES= chapter1/fig1.png document that includes the id example shown above: - More information can be found - in . + paraMore information can be found + in xref linkend="introduction".para -More specific information can be found - in .]]> +paraMore specific information can be found + in xref linkend="introduction-moredetails".para The link text will be generated automatically, looking like (emphasized text indicates the @@ -2129,11 +2163,12 @@ IMAGES= chapter1/fig1.png document that includes the id example. - More information can be found in the - sample introduction. + paraMore information can be found in the + link linkend="introduction"sample introductionlink.para -More specific information can be found in the - sample introduction with more details section.]]> +paraMore specific information can be found in the + link linkend="introduction-moredetails"sample introduction with + more detailslink section.para This output will be generated (emphasized text is used to show the @@ -2181,12 +2216,12 @@ IMAGES= chapter1/fig1.png Usage for book links: - Read the SVN - introduction, then pick the nearest mirror from - the list of Subversion - mirror sites.]]> + paraRead the ulink + url="&url.books.handbook;/svn.html#svn-intro"SVN + introductionulink, then pick the nearest mirror from + the list of ulink + url="&url.books.handbook;/subversion-mirrors.html"Subversion + mirror sitesulink.para Appearance: @@ -2199,9 +2234,10 @@ IMAGES= chapter1/fig1.png Usage for article links: - Read this article - about the BSD license, or just the introduction.]]> + paraRead this + ulink url="&url.articles.bsdl-gpl;"article + about the BSD licenseulink, or just the + ulink url="&url.articles.bsdl-gpl;#intro"introductionulink.para Appearance: @@ -2215,9 +2251,8 @@ IMAGES= chapter1/fig1.png Usage: - Of course, you could stop reading this document and - go to the FreeBSD - home page instead.]]> + paraOf course, you could stop reading this document and go to the + ulink url="&url.base;/index.html"FreeBSD home pageulink instead.para Appearance: @@ -2232,10 +2267,10 @@ IMAGES= chapter1/fig1.png Usage: - Wikipedia has an excellent reference on - GUID - Partition Tables.]]> + paraWikipedia has an excellent reference on + ulink + url="http://en.wikipedia.org/wiki/GUID_Partition_Table"GUID + Partition Tablesulink.para Appearance: @@ -2247,9 +2282,9 @@ IMAGES= chapter1/fig1.png The link text can be omitted to show the actual URL: - Wikipedia has an excellent reference on - GUID Partition Tables: .]]> + paraWikipedia has an excellent reference on + GUID Partition Tables: ulink + url="http://en.wikipedia.org/wiki/GUID_Partition_Table"ulink.para Appearance: