docs/1.6/figures.xml

   1 <?xml version='1.0' encoding='UTF-8'?>\r
   2 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"\r
   3   xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="figures">\r
   4   <title>Figures, Diagrams, Screen Shots, and In-Line Graphics</title>\r
   5   <section>\r
   6     <title>Overview</title>\r
   7     <para>Graphics, such as a diagram or a screen shot of a user interface, make a document more\r
   8       readable. Often, graphics also help clarify abstract concepts.</para>\r
   9     <para>Figures, diagrams, and screen shots contain images stored in external files. They are\r
  10       denoted using one of two elements: <tag class="element">figure</tag> or <tag class="element"\r
  11         >screenshot</tag>. The <tag class="element">figure</tag> element is used to denote a figure\r
  12       or a diagram. The <tag class="element">screenshot</tag> element is used to denote a screen\r
  13       shot.</para>\r
  14   </section>\r
  15   <section>\r
  16     <title>Image Data</title>\r
  17     <para>The preferred data format for images is PNG. However, images can be accepted in the\r
  18       following formats:</para>\r
  19     <itemizedlist>\r
  20       <listitem>\r
  21         <para>JPEG</para>\r
  22       </listitem>\r
  23       <listitem>\r
  24         <para>GIF</para>\r
  25       </listitem>\r
  26     </itemizedlist>\r
  27     <para>Images should be placed in an <filename class="directory">images</filename> folder\r
  28       directly under the folder containing the document source. </para>\r
  29     <para>Image size...</para>\r
  30   </section>\r
  31   <section>\r
  32     <title>Image Size</title>\r
  33     <para>Image files should have a maximum width of 900 pixels.</para>\r
  34     <para>Image scaling should be set to 75%. This is ignored for HTML output and ensures images are\r
  35       optimally sized for PDF files. </para>\r
  36   </section>\r
  37   <section>\r
  38     <title>Figures and Diagrams</title>\r
  39     <para>Figures and diagrams are marked up the same way. They are both placed in a <tag\r
  40         class="element">figure</tag> element. The <tag class="element">figure</tag> element is a\r
  41       container for the caption and data that make up the figure or diagram.</para>\r
  42     <para>The caption is specified by a <tag class="element">title</tag> element. The <tag\r
  43         class="element">title</tag> element is the first child element of the<tag class="element"\r
  44         >figure</tag> element. The contents of the <tag class="element">title</tag> element is the\r
  45       caption used for the figure. It is also the default text used when you cross reference the\r
  46       figure.</para>\r
  47     <para>The image data is specified in a <tag class="element">mediaobject</tag> element. The <tag\r
  48         class="element">mediaobject</tag> element is a wrapper for an <tag class="element"\r
  49         >imageobject</tag> element. The <tag class="element">imageobject</tag> element is also a\r
  50       wrapper element. The <tag class="element">imageobject</tag> element wraps an <tag\r
  51         class="element">imagedata</tag> element that specifies the name of the file containing the\r
  52       image.</para>\r
  53     <para>The <tag class="element">imagedata</tag> element has no content. All of the information is\r
  54       specified using three attributes:</para>\r
  55     <table>\r
  56       <title>Attributes for imagedata Element</title>\r
  57       <tgroup cols="2">\r
  58         <thead>\r
  59           <row>\r
  60             <entry>Attribute</entry>\r
  61             <entry>Description</entry>\r
  62           </row>\r
  63         </thead>\r
  64         <tbody>\r
  65           <row>\r
  66             <entry>\r
  67               <tag class="attribute">align</tag>\r
  68             </entry>\r
  69             <entry>Specifies how the image is aligned on the page. Valid values are <tag\r
  70                 class="attvalue">left</tag>, <tag class="attvalue">right</tag>, and <tag\r
  71                 class="attvalue">center</tag>.</entry>\r
  72           </row>\r
  73           <row>\r
  74             <entry>\r
  75               <tag class="attribute">fileref</tag>\r
  76             </entry>\r
  77             <entry>Specifies the location of the file containing the image.</entry>\r
  78           </row>\r
  79           <row>\r
  80             <entry>\r
  81               <tag class="attribute">format</tag>\r
  82             </entry>\r
  83             <entry>Specifies the type of data used to specify the image. Valid values are <tag\r
  84                 class="attvalue">GIF</tag>, <tag class="attvalue">JPG</tag>, and <tag\r
  85                 class="attvalue">PNG</tag>.</entry>\r
  86           </row>\r
  87         </tbody>\r
  88       </tgroup>\r
  89     </table>\r
  90     <para><xref linkend="figure_example"/> shows the mark-up for a figure.</para>\r
  91     <example xml:id="figure_example">\r
  92       <title>Mark-up for a Figure</title>\r
  93       <programlisting>&lt;figure xml:id=&quot;fig_1&quot;&gt;\r
  94   &lt;title&gt;CeltiXfire WAR Structure&lt;/title&gt;\r
  95   &lt;mediaobject&gt;\r
  96     &lt;imageobject&gt;\r
  97       &lt;imagedata align=&quot;center&quot; \r
  98          fileref=&quot;./images/tomcat_war.gif&quot;\r
  99          format=&quot;GIF&quot; /&gt;\r
 100     &lt;/imageobject&gt;\r
 101   &lt;/mediaobject&gt;\r
 102   ...\r
 103 &lt;/figure&gt;</programlisting>\r
 104     </example>\r
 105   </section>\r
 106   <section>\r
 107     <title>Screen Shots</title>\r
 108     <para>Screen shots are also marked up using a <tag class="element">figure</tag> element.\r
 109       However, a screen shot uses one additional wrapper element. The <tag class="element"\r
 110         >screenshot</tag> element wraps the <tag class="element">mediaobject</tag> element as shown\r
 111       in <xref linkend="screen_example"/>.</para>\r
 112     <example xml:id="screen_example">\r
 113       <title>Mark-up for a Screen Shot</title>\r
 114       <programlisting>&lt;figure xml:id=&quot;screen_1&quot;&gt;\r
 115   &lt;title&gt;SOA Tools Welcome Screen&lt;/title&gt;\r
 116   &lt;screenshot&gt;\r
 117     &lt;mediaobject&gt;\r
 118       &lt;imageobject&gt;\r
 119         &lt;imagedata align=&quot;center&quot; \r
 120             fileref=&quot;./images/welcome.gif&quot;\r
 121             format=&quot;GIF&quot; /&gt;\r
 122       &lt;/imageobject&gt;\r
 123     &lt;/mediaobject&gt;\r
 124   &lt;/screenshot&gt;\r
 125   ...\r
 126 &lt;/figure&gt;</programlisting>\r
 127     </example>\r
 128   </section>\r
 129   <section>\r
 130     <title>In-Line Graphics</title>\r
 131     <para>Graphical elements that need to be placed in-line with the text of a paragraph are marked\r
 132       up using the <tag class="element">inlinemediaobject</tag> element. Like the <tag\r
 133         class="element">mediaobject</tag> element, the <tag class="element">inlinemediaobject</tag>\r
 134       element is a wrapper for an <tag class="element">imageobject</tag> element. <xref\r
 135         linkend="inline_example"/> shows the mark-up for an in-line graphic.</para>\r
 136     <example xml:id="inline_example">\r
 137       <title>Mark-up for an In-Line Graphic</title>\r
 138       <programlisting>&lt;inlinemediaobject&gt;\r
 139   &lt;imageobject&gt;\r
 140     &lt;imagedata align=&quot;center&quot; fileref=&quot;./images/larrow.gif&quot;\r
 141                format=&quot;GIF&quot; /&gt;\r
 142   &lt;/imageobject&gt;\r
 143   ...\r
 144 &lt;/inlinemediaobject&gt;</programlisting>\r
 145     </example>\r
 146   </section>\r
 147   <section>\r
 148     <title>Adding Alternative Text</title>\r
 149     <para>For better accessibility and to comply with federal and local accessibility guidelines,\r
 150       all images in DocBook files should include alternative text.</para>\r
 151     <para>To include alternative text with a graphic, add a <tag class="element">textobject</tag>\r
 152       element after the <tag class="element">imageobject</tag> element. The <tag class="element"\r
 153         >textobject</tag> element has a single <tag class="element">phrase</tag> child element. The\r
 154       value of the <tag class="element">phrase</tag> element is the alternative text used when the\r
 155       documentation is generated to HTML.</para>\r
 156     <example xml:id="alttext_example">\r
 157       <title>Mark-up for Alternative Text</title>\r
 158       <programlisting>&lt;mediaobject&gt;\r
 159   &lt;imageobject&gt;\r
 160     &lt;imagedata align=&quot;center&quot; fileref=&quot;./images/config.gif&quot;\r
 161                format=&quot;GIF&quot; /&gt;\r
 162   &lt;/imageobject&gt;\r
 163   &lt;textobject&gt;\r
 164     &lt;phrase&gt;Configuration Hierarchy&lt;/phrase&gt;\r
 165   &lt;/textobject&gt;\r
 166 &lt;/mediaobject&gt;</programlisting>\r
 167     </example>\r
 168   </section>\r
 169 </chapter>\r