Add some tips and remove some revision tag references from element glossary.

Revision history can be tracked by repository so revision tags may  not be
needed by DIG?

diff --git a/style_guide/glossary.xml b/style_guide/glossary.xml
index ccd9243..96ea591 100644 (file)
--- a/style_guide/glossary.xml
+++ b/style_guide/glossary.xml
@@ -517,19 +517,9 @@
                     <link xlink:href="http://www.docbook.org/tdg5/en/html/date.html">date</link>\r
                 </glossterm>\r
                 <glossdef>\r
-                    <para>Wrapper for date info in any context. Mandatory component of chapter\r
-                            <markup linkend="revision">revision</markup> entries.  Format is YYYY-MM-DD</para>\r
+                    <para>Wrapper for date info in any context. Format is YYYY-MM-DD</para>\r
                     \r
                 </glossdef></glossentry>\r
-            <glossentry xml:id="authorinitials">\r
-                <glossterm>\r
-                    <link xlink:href="http://www.docbook.org/tdg5/en/html/authorinitials.html"\r
-                        >authorinitials</link>\r
-                </glossterm>\r
-                <glossdef>\r
-                    <para>An author's initials, mandatory componenet of the chapter <markup linkend="revision">revision</markup> element.\r
-                    </para>\r
-                </glossdef></glossentry>\r
             <glossentry xml:id="simplesect">\r
                 <glossterm><link xlink:href="http://www.docbook.org/tdg5/en/html/simplesect.html"\r
                         >simplesect</link></glossterm>\r

diff --git a/style_guide/tips.xml b/style_guide/tips.xml
index 3e2a411..cab4da6 100644 (file)
--- a/style_guide/tips.xml
+++ b/style_guide/tips.xml
@@ -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
@@ -26,16 +26,55 @@
          <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