From 01c1c92adb6e355c1d98e189cb5f09f14bf0bc5d Mon Sep 17 00:00:00 2001
From: Robert Soulliere <rsoulliere@libdog.mohawkcollege.ca>
Date: Mon, 25 Oct 2010 15:13:02 -0400
Subject: [PATCH] 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?
---
style_guide/glossary.xml | 12 +-------
style_guide/tips.xml | 73 +++++++++++++++++++++++++++++++++++++-----------
2 files changed, 57 insertions(+), 28 deletions(-)
diff --git a/style_guide/glossary.xml b/style_guide/glossary.xml
index ccd9243981..96ea591e36 100644
--- 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>
</glossterm>
<glossdef>
- <para>Wrapper for date info in any context. Mandatory component of chapter
- <markup linkend="revision">revision</markup> entries. Format is YYYY-MM-DD</para>
+ <para>Wrapper for date info in any context. Format is YYYY-MM-DD</para>
</glossdef></glossentry>
- <glossentry xml:id="authorinitials">
- <glossterm>
- <link xlink:href="http://www.docbook.org/tdg5/en/html/authorinitials.html"
- >authorinitials</link>
- </glossterm>
- <glossdef>
- <para>An author's initials, mandatory componenet of the chapter <markup linkend="revision">revision</markup> element.
- </para>
- </glossdef></glossentry>
<glossentry xml:id="simplesect">
<glossterm><link xlink:href="http://www.docbook.org/tdg5/en/html/simplesect.html"
>simplesect</link></glossterm>
diff --git a/style_guide/tips.xml b/style_guide/tips.xml
index 3e2a4111fd..cab4da6964 100644
--- a/style_guide/tips.xml
+++ b/style_guide/tips.xml
@@ -8,16 +8,16 @@
</info>
- <simplesect>
- <title>Table column width</title>
+ <simplesect>
+ <title>Table column width</title>
- <para>If column width is not specified in the XML, tables will look different depending on
- the output format. In HTML the columns automatically adjust to fit contents, but in PDF
- the page width is divided evenly by the number of columns. This often wastes space in
- PDF tables so setting relative column widths for all tables is recommended.</para>
- <para>In the example below, the <emphasis>colwidth</emphasis> parameter defines relative
- column width. Columns 1 and 2 are of equal width, each using a quarter of the page.
- Column 3 is twice the size and covers the remaining half of the page.</para>
+ <para>If column width is not specified in the XML, tables will look different depending on
+ the output format. In HTML the columns automatically adjust to fit contents, but in PDF
+ the page width is divided evenly by the number of columns. This often wastes space in
+ PDF tables so setting relative column widths for all tables is recommended.</para>
+ <para>In the example below, the <emphasis>colwidth</emphasis> parameter defines relative
+ column width. Columns 1 and 2 are of equal width, each using a quarter of the page.
+ Column 3 is twice the size and covers the remaining half of the page.</para>
<programlisting><![CDATA[
<table>
@@ -26,16 +26,55 @@
<colspec colnum="1" colname="issues" colwidth="1*"/>
<colspec colnum="2" colname="actions" colwidth="1*"/>
<colspec colnum="3" colname="tasks" colwidth="2*"/>]]>
-
</programlisting>
- <para>For details see <link
- xlink:href="http://www.sagehill.net/docbookxsl/ColumnWidths.html"
- xlink:title="http://www.sagehill.net/docbookxsl/ColumnWidths.html">DocBook XSL: The
- Complete Guide</link>.</para>
-
+ <para>For details see <link
+ xlink:href="http://www.sagehill.net/docbookxsl/ColumnWidths.html"
+ xlink:title="http://www.sagehill.net/docbookxsl/ColumnWidths.html">DocBook XSL: The
+ Complete Guide</link>.</para>
+ <para>To avoid the following error during processing of PDF files,</para>
+<screen>
+WARNING: table-layout="fixed" and column-width unspecified => falling back to proportional-column-width(1)
+</screen>
+ <para>it seems necessary to add decimal values in the <code>colwidth</code> parameter <colspec colwidth="1.0*"/ ></para>
+ <para>See <link xlink:href="http://osdir.com/ml/fop-users-xmlgraphics.apache.org/2009-04/msg00109.html"
+ 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>
+ </simplesect>
+ <simplesect>
+ <title>Using CDATA for XML Code</title>
+ <para>if you find yourself with long <code language="xml"><programlisting></code> or <code language="xml"><screen></code> sections that contain a lot of XML code, you can
+ wrap the whole thing in <code language="xml"><![CDATA[ .... ]]></code> and the XML parser will skip it. For example:</para>
+<programlisting language="xml">
+<![CDATA[
+<programlisting language="xml">
+<![CDATA[
+<!-- Example of an app-specific setting override -->
+<opensrf.persist>
+ <app_settings>
+ <dbfile>/tmp/persist.db</dbfile>
+ </app_settings>
+</opensrf.persist>
+]]>
+</programlisting>
+]]>
+</programlisting>
+ <para>It's a lot easier to add the <![CDATA[ .... ]]> wrapper than change the individual occurances of <code language="xml"><</code> and <code language="xml">></code>.</para>
+ </simplesect>
+ <simplesect>
+ <title>Semantic Oriented Markup</title>
+ <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
+ <code language="xml"><emphasis></code> tag is important for allowing more control over display of the content.</para>
+ <para>Here are some examples of existing DocBook tags which should be used in place of <code language="xml"><emphasis></code>:</para>
+ <itemizedlist>
+ <listitem><code language="xml"><command></code> is used for command names
+ (<link xlink:href="http://www.docbook.org/tdg5/en/html/command.html">http://www.docbook.org/tdg5/en/html/command.html</link>)</listitem>
+ <listitem><code language="xml"><filename></code> is used for file paths and file names
+ (<link xlink:href="http://www.docbook.org/tdg5/en/html/filename.html">http://www.docbook.org/tdg5/en/html/filename.html</link>)</listitem>
+ <listitem><code language="xml"><option></code> is used for command options
+ (<link xlink:href="http://www.docbook.org/tdg5/en/html/option.html">http://www.docbook.org/tdg5/en/html/option.html</link>) </listitem>
+ <listitem><code language="xml"><systemitem class="username"></code> is used for user names
+ (<link xlink:href="http://www.docbook.org/tdg5/en/html/systemitem.html">http://www.docbook.org/tdg5/en/html/systemitem.html</link>)</listitem>
+ </itemizedlist>
</simplesect>
-
-
</chapter>
--
2.11.0