doc/block.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE chapter SYSTEM "../doc.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../html.xsl"?>
   4
   5 <!--
   6       XML documentation system
   7       Original author :  Arjen Baart - arjen@andromeda.nl
   8       Version         : $Revision: 1.2 $
   9 -->
  10
  11 <chapter>
  12 <heading><label name='block'/>Block-level content</heading>
  13 <para>
  14 The actual content of your document is organized in <emph>block-level</emph>
  15 elements, such a paragraphs, lists or tables.
  16 </para>
  17
  18 <section>
  19 <heading>Paragraphs</heading>
  20 <para>
  21 The most basic type of content block is an ordinary paragraph, contained
  22 in a <strong>para</strong> element.
  23 To make several separate paragraphs, you must enclose each paragraph
  24 in a <strong>para</strong> open tag and a <strong>para</strong> close tag.
  25 Here is an example of two small paragraphs:
  26 <verbatim>
  27
  28 &lt;para&gt;
  29   This is an example of a small paragraph.
  30 &lt;/para&gt;
  31 &lt;para&gt;
  32   And here is another paragraph.
  33 &lt;/para&gt;
  34
  35 </verbatim>
  36
  37 </para>
  38
  39 <para>
  40 A second type of paragraph is a <strong>quote</strong>.
  41 You can make a quote by using the <code>quote</code> element:
  42
  43 <verbatim>
  44    &lt;quote&gt;
  45    This is an example of a quote.
  46    The text within a quoted paragraph is usually slightly indented on both
  47    the left and the right margin.
  48    &lt;/quote&gt;
  49 </verbatim>
  50
  51 Which results in:
  52
  53 <quote>
  54 This is an example of a quote.
  55 The text within a quoted paragraph is usually slightly indented on both
  56 the left and the right margin.
  57 </quote>
  58 </para>
  59
  60 <para>
  61 A special kind of paragraph is the <strong>verbatim</strong> environment.
  62 Just as in LaTeX, this is used to include literal text output with spaces,
  63 indentation and line breaks preserved.
  64 The practical use for the <strong>verbatim</strong> element is to
  65 include coding examples, such as:
  66
  67 <verbatim>
  68    &lt;verbatim&gt;
  69       struct complex
  70       {
  71          double   real;
  72          double   imaginary;
  73       };
  74    &lt;/verbatim&gt;
  75 </verbatim>
  76
  77 Which comes out like this:
  78
  79 <verbatim>
  80    struct complex
  81    {
  82       double   real;
  83       double   imaginary;
  84    };
  85 </verbatim>
  86 </para>
  87 </section>
  88
  89 <section>
  90 <heading><label name='footnote'/>Footnotes</heading>
  91 <para>
  92 Footnotes are created with the <strong>footnote</strong> element:
  93 <footnote>This is an example of a footnote</footnote>
  94
  95 <verbatim>
  96 &lt;footnote&gt;This is an example of a footnote&lt;/footnote&gt;
  97 </verbatim>
  98
  99 Within a footnote, you can use <emph>inline</emph> content <footnote>described in the
 100 next chapter</footnote> to format the type
 101 styles of the text in the footnote.
 102 It is not possible to use the block content described in this chapter within
 103 a footnote.
 104 </para>
 105
 106 <para>
 107 Footnotes appear at the bottom of the page, with a small number in the
 108 running text referring to that footnote.
 109 </para>
 110
 111 </section>
 112
 113 <section>
 114 <heading><label name='list'/>Lists</heading>
 115 <para>
 116 Three types of lists are supported:
 117 <itemize>
 118 <item><code>itemize</code> for bulleted lists such as this one.</item>
 119 <item><code>enumerate</code> for numbered lists.</item>
 120 <item><code>description</code> for tagged lists.</item>
 121 </itemize>
 122
 123 Each item in such a list must be in an <code>item</code> element.
 124 In fact, an <code>item</code> is the only element allowed in an
 125 <code>itemize</code>, <code>enumerate</code> or <code>description</code> element.
 126 You should not put ordinary text or any other element in a list without
 127 enclosing them in <code>&lt;item&gt;</code> and <code>&lt;/item&gt;</code>.
 128 Here is an example of a numbered list:
 129
 130 <verbatim>
 131
 132 &lt;enumerate&gt;
 133    &lt;item&gt;First you need an enumerate or itemize tag.&lt;/item&gt;
 134    &lt;item&gt;Second, include one or more item elements.&lt;/item&gt;
 135    &lt;item&gt;Finally, put the content inside the items.&lt;/item&gt;
 136 &lt;/enumerate&gt;
 137
 138 </verbatim>
 139
 140 And this is what the list turns into:
 141
 142 <enumerate>
 143    <item>First you need an enumerate, itemize or description tag.</item>
 144    <item>Second, include one or more item elements.</item>
 145    <item>Finally, put the content inside the items.</item>
 146 </enumerate>
 147
 148 In a description list, you make your own tags for each item instead
 149 of the automatically generated bullts or numbers.
 150 The tags for each item go in the <code>tag</code> attribute of the
 151 <code>item</code> element.
 152 So, repeating the above list as a description list:
 153
 154 <verbatim>
 155 &lt;description&gt;
 156    &lt;item tag='itemize'&gt; for bulleted lists such as this one.&lt;/item&gt;
 157    &lt;item tag='enumerate'&gt; for numbered lists.&lt;/item&gt;
 158    &lt;item tag='description'&gt; for tagged lists.&lt;/item&gt;
 159 &lt;/description&gt;
 160 </verbatim>
 161
 162 Which creates the following output:
 163
 164 <description>
 165 <item tag='itemize'> for bulleted lists.</item>
 166 <item tag='enumerate'> for numbered lists.</item>
 167 <item tag='description'> for tagged lists such as this one.</item>
 168 </description>
 169
 170 An item can contain inline content as well as block-level content.
 171 </para>
 172 </section>
 173
 174 <section>
 175 <heading><label name='graphics'/>Including graphics</heading>
 176 <para>
 177 The empty element <strong>picture</strong> is used to include
 178 graphics in your document, like this:
 179
 180 <verbatim>
 181    &lt;picture src='diagram.png' eps='diagram' scale='0.5'/&gt;
 182 </verbatim>
 183
 184 The two attributes are used in either HTML or LaTeX.
 185 </para>
 186 </section>
 187
 188 <section>
 189 <heading><label name='table'/>Tables</heading>
 190 <para>
 191 Creating tables in XMLDoc is much like creating tables in HTML.
 192 First, there is the <code>table</code> element.
 193 The <code>table</code> element may contain an optional <code>thead</code>
 194 and any number of <code>row</code> elements.
 195 Both the <code>thead</code> and the <code>row</code> elements must contain
 196 one or more <code>col</code> elements.
 197 The <code>col</code> elements hold the actual content of
 198 the table, which must be inline content (see next chapter) or block content.
 199 To use the tables in LaTeX, you must supply a <code>cpos</code>
 200 attribute in the <code>table</code> tag.
 201 </para>
 202
 203 <para>
 204 An example of a table is shown below:
 205
 206 <verbatim>
 207
 208 &lt;table cpos='lr'&gt;
 209   &lt;thead&gt;&lt;col&gt;Drink   &lt;/col&gt;&lt;col&gt;Price&lt;/col&gt;&lt;/thead&gt;
 210   &lt;row&gt;&lt;col&gt;Beer      &lt;/col&gt;&lt;col&gt; 1.80&lt;/col&gt;&lt;/row&gt;
 211   &lt;row&gt;&lt;col&gt;Wiskey    &lt;/col&gt;&lt;col&gt; 3.50&lt;/col&gt;&lt;/row&gt;
 212   &lt;row&gt;&lt;col&gt;Wine      &lt;/col&gt;&lt;col&gt; 2.20&lt;/col&gt;&lt;/row&gt;
 213 &lt;/table>
 214
 215 </verbatim>
 216
 217 <table cpos='lr'>
 218   <thead><col>Drink   </col><col>Price</col></thead>
 219   <row><col>Beer      </col><col> 1.80</col></row>
 220   <row><col>Wiskey    </col><col> 3.50</col></row>
 221   <row><col>Wine      </col><col> 2.20</col></row>
 222 </table>
 223
 224 </para>
 225 </section>
 226
 227 </chapter>
 228