style_guide/tips.xml

   1 <?xml version="1.0" encoding="utf-8"?>\r
   2 <chapter xml:id="style-tips" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
   3     xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
   4 \r
   5     <info>\r
   6 \r
   7         <title>Miscellaneous Tips</title>\r
   8     </info>\r
   9 \r
  10 \r
  11         <simplesect>\r
  12                 <title>Table column width</title>\r
  13 \r
  14                 <para>If column width is not specified in the XML, tables will look different depending on\r
  15                     the output format. In HTML the columns automatically adjust to fit contents, but in PDF\r
  16                     the page width is divided evenly by the number of columns. This often wastes space in\r
  17                     PDF tables so setting relative column widths for all tables is recommended.</para>\r
  18                 <para>In the example below, the <emphasis>colwidth</emphasis> parameter defines relative\r
  19                     column width. Columns 1 and 2 are of equal width, each using a quarter of the page.\r
  20                     Column 3 is twice the size and covers the remaining half of the page.</para>\r
  21 \r
  22         <programlisting><![CDATA[ \r
  23 <table>\r
  24    <title>Title of Table Here</title>\r
  25       <tgroup cols="3" align="left" colsep="1" rowsep="1">\r
  26          <colspec colnum="1" colname="issues" colwidth="1*"/>\r
  27          <colspec colnum="2" colname="actions" colwidth="1*"/>\r
  28          <colspec colnum="3" colname="tasks" colwidth="2*"/>]]>\r
  29         </programlisting>\r
  30 \r
  31                 <para>For details see <link\r
  32                         xlink:href="http://www.sagehill.net/docbookxsl/ColumnWidths.html"\r
  33                         xlink:title="http://www.sagehill.net/docbookxsl/ColumnWidths.html">DocBook XSL: The\r
  34                         Complete Guide</link>.</para>\r
  35                 <para>To avoid the following error during processing of PDF files,</para> \r
  36 <screen>\r
  37 WARNING: table-layout="fixed" and column-width unspecified => falling back to proportional-column-width(1)\r
  38 </screen>\r
  39                 <para>it seems necessary to add decimal values in the <code>colwidth</code> parameter &lt;colspec colwidth="1.0*"/ &gt;</para> \r
  40                 <para>See <link xlink:href="http://osdir.com/ml/fop-users-xmlgraphics.apache.org/2009-04/msg00109.html" \r
  41                 xlink:title="http://osdir.com/ml/fop-users-xmlgraphics.apache.org/2009-04/msg00109.html">http://osdir.com/ml/fop-users-xmlgraphics.apache.org/2009-04/msg00109.html</link></para>\r
  42         </simplesect>\r
  43         <simplesect>\r
  44                 <title>Using CDATA for XML Code</title>\r
  45                 <para>if you find yourself with long <code language="xml">&lt;programlisting&gt;</code> or <code language="xml">&lt;screen&gt;</code> sections that contain a lot of XML code, you can \r
  46                 wrap the whole thing in <code language="xml">&lt;![CDATA[ .... ]]&gt;</code> and the XML parser will skip it. For example:</para>\r
  47 <programlisting language="xml">\r
  48 <![CDATA[\r
  49 <programlisting language="xml">\r
  50 <![CDATA[\r
  51 <!-- Example of an app-specific setting override -->\r
  52 <opensrf.persist>\r
  53   <app_settings>\r
  54   <dbfile>/tmp/persist.db</dbfile>\r
  55   </app_settings>\r
  56 </opensrf.persist>\r
  57 ]]&gt;\r
  58 </programlisting>\r
  59 ]]>\r
  60 </programlisting>\r
  61                 <para>It's a lot easier to add the &lt;![CDATA[ .... ]]&gt; wrapper than change the individual occurances of <code language="xml">&lt;</code> and <code language="xml">&gt;</code>.</para>\r
  62         </simplesect>\r
  63         <simplesect>\r
  64                 <title>Semantic Oriented Markup</title>\r
  65                 <para>Adopting more semantic markup gives us the ability to have more fine-grained control over the stylesheets and resulting output. Finding semantic alternatives to the \r
  66                 <code language="xml">&lt;emphasis&gt;</code> tag is important for allowing more control over display of the content.</para>\r
  67                 <para>Here are some examples of existing DocBook tags which should be used in place of <code language="xml">&lt;emphasis&gt;</code>:</para>  \r
  68                 <itemizedlist>\r
  69                         <listitem><code language="xml">&lt;command&gt;</code> is used for command names \r
  70                         (<link xlink:href="http://www.docbook.org/tdg5/en/html/command.html">http://www.docbook.org/tdg5/en/html/command.html</link>)</listitem>\r
  71                         <listitem><code language="xml">&lt;filename&gt;</code> is used for file paths and file names \r
  72                         (<link xlink:href="http://www.docbook.org/tdg5/en/html/filename.html">http://www.docbook.org/tdg5/en/html/filename.html</link>)</listitem>\r
  73                         <listitem><code language="xml">&lt;option&gt;</code> is used for command options \r
  74                         (<link xlink:href="http://www.docbook.org/tdg5/en/html/option.html">http://www.docbook.org/tdg5/en/html/option.html</link>) </listitem>\r
  75                         <listitem><code language="xml">&lt;systemitem class="username"&gt;</code> is used for user names \r
  76                         (<link xlink:href="http://www.docbook.org/tdg5/en/html/systemitem.html">http://www.docbook.org/tdg5/en/html/systemitem.html</link>)</listitem>\r
  77                 </itemizedlist>\r
  78     </simplesect>\r
  79 \r
  80 </chapter>\r