Add more useful info to the README file.
[working/Evergreen.git] / style_guide / tips.xml
index 3e2a411..cab4da6 100644 (file)
@@ -8,16 +8,16 @@
     </info>\r
 \r
 \r
-    <simplesect>\r
-        <title>Table column width</title>\r
+       <simplesect>\r
+               <title>Table column width</title>\r
 \r
-        <para>If column width is not specified in the XML, tables will look different depending on\r
-            the output format. In HTML the columns automatically adjust to fit contents, but in PDF\r
-            the page width is divided evenly by the number of columns. This often wastes space in\r
-            PDF tables so setting relative column widths for all tables is recommended.</para>\r
-        <para>In the example below, the <emphasis>colwidth</emphasis> parameter defines relative\r
-            column width. Columns 1 and 2 are of equal width, each using a quarter of the page.\r
-            Column 3 is twice the size and covers the remaining half of the page.</para>\r
+               <para>If column width is not specified in the XML, tables will look different depending on\r
+                   the output format. In HTML the columns automatically adjust to fit contents, but in PDF\r
+                   the page width is divided evenly by the number of columns. This often wastes space in\r
+                   PDF tables so setting relative column widths for all tables is recommended.</para>\r
+               <para>In the example below, the <emphasis>colwidth</emphasis> parameter defines relative\r
+                   column width. Columns 1 and 2 are of equal width, each using a quarter of the page.\r
+                   Column 3 is twice the size and covers the remaining half of the page.</para>\r
 \r
         <programlisting><![CDATA[ \r
 <table>\r
          <colspec colnum="1" colname="issues" colwidth="1*"/>\r
          <colspec colnum="2" colname="actions" colwidth="1*"/>\r
          <colspec colnum="3" colname="tasks" colwidth="2*"/>]]>\r
-    \r
         </programlisting>\r
 \r
-        <para>For details see <link\r
-                xlink:href="http://www.sagehill.net/docbookxsl/ColumnWidths.html"\r
-                xlink:title="http://www.sagehill.net/docbookxsl/ColumnWidths.html">DocBook XSL: The\r
-                Complete Guide</link>.</para>\r
-\r
+               <para>For details see <link\r
+                       xlink:href="http://www.sagehill.net/docbookxsl/ColumnWidths.html"\r
+                       xlink:title="http://www.sagehill.net/docbookxsl/ColumnWidths.html">DocBook XSL: The\r
+                       Complete Guide</link>.</para>\r
+               <para>To avoid the following error during processing of PDF files,</para> \r
+<screen>\r
+WARNING: table-layout="fixed" and column-width unspecified => falling back to proportional-column-width(1)\r
+</screen>\r
+               <para>it seems necessary to add decimal values in the <code>colwidth</code> parameter &lt;colspec colwidth="1.0*"/ &gt;</para> \r
+               <para>See <link xlink:href="http://osdir.com/ml/fop-users-xmlgraphics.apache.org/2009-04/msg00109.html" \r
+               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
+       </simplesect>\r
+       <simplesect>\r
+               <title>Using CDATA for XML Code</title>\r
+               <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
+               wrap the whole thing in <code language="xml">&lt;![CDATA[ .... ]]&gt;</code> and the XML parser will skip it. For example:</para>\r
+<programlisting language="xml">\r
+<![CDATA[\r
+<programlisting language="xml">\r
+<![CDATA[\r
+<!-- Example of an app-specific setting override -->\r
+<opensrf.persist>\r
+  <app_settings>\r
+  <dbfile>/tmp/persist.db</dbfile>\r
+  </app_settings>\r
+</opensrf.persist>\r
+]]&gt;\r
+</programlisting>\r
+]]>\r
+</programlisting>\r
+               <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
+       </simplesect>\r
+       <simplesect>\r
+               <title>Semantic Oriented Markup</title>\r
+               <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
+               <code language="xml">&lt;emphasis&gt;</code> tag is important for allowing more control over display of the content.</para>\r
+               <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
+               <itemizedlist>\r
+                       <listitem><code language="xml">&lt;command&gt;</code> is used for command names \r
+                       (<link xlink:href="http://www.docbook.org/tdg5/en/html/command.html">http://www.docbook.org/tdg5/en/html/command.html</link>)</listitem>\r
+                       <listitem><code language="xml">&lt;filename&gt;</code> is used for file paths and file names \r
+                       (<link xlink:href="http://www.docbook.org/tdg5/en/html/filename.html">http://www.docbook.org/tdg5/en/html/filename.html</link>)</listitem>\r
+                       <listitem><code language="xml">&lt;option&gt;</code> is used for command options \r
+                       (<link xlink:href="http://www.docbook.org/tdg5/en/html/option.html">http://www.docbook.org/tdg5/en/html/option.html</link>) </listitem>\r
+                       <listitem><code language="xml">&lt;systemitem class="username"&gt;</code> is used for user names \r
+                       (<link xlink:href="http://www.docbook.org/tdg5/en/html/systemitem.html">http://www.docbook.org/tdg5/en/html/systemitem.html</link>)</listitem>\r
+               </itemizedlist>\r
     </simplesect>\r
 \r
-   \r
-\r
 </chapter>\r