The conversion to HTML creates proper XHTML.

[xmldoc.git] / doc / block.xml

diff --git a/doc/block.xml b/doc/block.xml
index b102fed..4c05987 100644 (file)
--- a/doc/block.xml
+++ b/doc/block.xml
@@ -5,7 +5,7 @@
 <!--
       XML documentation system
       Original author :  Arjen Baart - arjen@andromeda.nl
-      Version         : $Revision: 1.2 $
+      Version         : $Revision: 1.3 $
 -->
 
 <chapter>
@@ -23,6 +23,8 @@ in a <strong>para</strong> element.
 To make several separate paragraphs, you must enclose each paragraph
 in a <strong>para</strong> open tag and a <strong>para</strong> close tag.
 Here is an example of two small paragraphs:
+</para>
+
 <verbatim>
 
 &lt;para&gt;
@@ -34,11 +36,10 @@ Here is an example of two small paragraphs:
 
 </verbatim>
 
-</para>
-
 <para>
 A second type of paragraph is a <strong>quote</strong>.
 You can make a quote by using the <code>quote</code> element:
+</para>
 
 <verbatim>
    &lt;quote&gt;
@@ -48,14 +49,15 @@ You can make a quote by using the <code>quote</code> element:
    &lt;/quote&gt;
 </verbatim>
 
+<para>
 Which results in:
+</para>
 
 <quote>
 This is an example of a quote.
 The text within a quoted paragraph is usually slightly indented on both
 the left and the right margin.
 </quote>
-</para>
 
 <para>
 A special kind of paragraph is the <strong>verbatim</strong> environment.
@@ -63,6 +65,7 @@ Just as in LaTeX, this is used to include literal text output with spaces,
 indentation and line breaks preserved.
 The practical use for the <strong>verbatim</strong> element is to
 include coding examples, such as:
+</para>
 
 <verbatim>
    &lt;verbatim&gt;
@@ -74,7 +77,9 @@ include coding examples, such as:
    &lt;/verbatim&gt;
 </verbatim>
 
+<para>
 Which comes out like this:
+</para>
 
 <verbatim>
    struct complex
@@ -83,7 +88,41 @@ Which comes out like this:
       double   imaginary;
    };
 </verbatim>
+
+<para>
+A variation on the <strong>verbatim</strong> text is the <strong>example</strong>
+text.
+The only real difference is that <strong>example</strong> is placed inside
+a box to make it stand out a bit more.
+In fact, when converted to XHTML, only an attribute <code>class='example'</code>
+is added.
+It is up to the CSS linked to the XHTML page to add additional layout features.
+The default styling will only add a border.
+Here is the above example shown in an actual <strong>example</strong> element:
+</para>
+
+<example>
+   &lt;example&gt;
+      struct complex
+      {
+         double   real;
+         double   imaginary;
+      };
+   &lt;/example&gt;
+</example>
+
+<para>
+Which comes out like this:
 </para>
+
+<example>
+   struct complex
+   {
+      double   real;
+      double   imaginary;
+   };
+</example>
+
 </section>
 
 <section>
@@ -91,11 +130,13 @@ Which comes out like this:
 <para>
 Footnotes are created with the <strong>footnote</strong> element:
 <footnote>This is an example of a footnote</footnote>
+</para>
 
 <verbatim>
 &lt;footnote&gt;This is an example of a footnote&lt;/footnote&gt;
 </verbatim>
 
+<para>
 Within a footnote, you can use <emph>inline</emph> content <footnote>described in the
 next chapter</footnote> to format the type
 styles of the text in the footnote. 
@@ -114,18 +155,22 @@ running text referring to that footnote.
 <heading><label name='list'/>Lists</heading>
 <para>
 Three types of lists are supported:
+</para>
+
 <itemize>
 <item><code>itemize</code> for bulleted lists such as this one.</item>
 <item><code>enumerate</code> for numbered lists.</item>
 <item><code>description</code> for tagged lists.</item>
 </itemize>
 
+<para>
 Each item in such a list must be in an <code>item</code> element.
 In fact, an <code>item</code> is the only element allowed in an
 <code>itemize</code>, <code>enumerate</code> or <code>description</code> element.
 You should not put ordinary text or any other element in a list without
 enclosing them in <code>&lt;item&gt;</code> and <code>&lt;/item&gt;</code>.
 Here is an example of a numbered list:
+</para>
 
 <verbatim>
 
@@ -137,7 +182,9 @@ Here is an example of a numbered list:
 
 </verbatim>
 
+<para>
 And this is what the list turns into:
+</para>
 
 <enumerate>
    <item>First you need an enumerate, itemize or description tag.</item>
@@ -145,11 +192,13 @@ And this is what the list turns into:
    <item>Finally, put the content inside the items.</item>
 </enumerate>
 
+<para>
 In a description list, you make your own tags for each item instead
 of the automatically generated bullts or numbers.
 The tags for each item go in the <code>tag</code> attribute of the
 <code>item</code> element.
 So, repeating the above list as a description list:
+</para>
 
 <verbatim>
 &lt;description&gt;
@@ -159,7 +208,9 @@ So, repeating the above list as a description list:
 &lt;/description&gt;
 </verbatim>
 
+<para>
 Which creates the following output:
+</para>
 
 <description>
 <item tag='itemize'> for bulleted lists.</item>
@@ -167,6 +218,7 @@ Which creates the following output:
 <item tag='description'> for tagged lists such as this one.</item>
 </description>
 
+<para>
 An item can contain inline content as well as block-level content.
 </para>
 </section>
@@ -176,11 +228,13 @@ An item can contain inline content as well as block-level content.
 <para>
 The empty element <strong>picture</strong> is used to include
 graphics in your document, like this:
+</para>
 
 <verbatim>
    &lt;picture src='diagram.png' eps='diagram' scale='0.5'/&gt;
 </verbatim>
 
+<para>
 The two attributes are used in either HTML or LaTeX.
 </para>
 </section>
@@ -202,6 +256,7 @@ attribute in the <code>table</code> tag.
 
 <para>
 An example of a table is shown below:
+</para>
 
 <verbatim>
 
@@ -221,7 +276,6 @@ An example of a table is shown below:
   <row><col>Wine      </col><col> 2.20</col></row>
 </table>
 
-</para>
 </section>
 
 </chapter>