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.3 $
   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 </para>
  27
  28 <verbatim>
  29
  30 &lt;para&gt;
  31   This is an example of a small paragraph.
  32 &lt;/para&gt;
  33 &lt;para&gt;
  34   And here is another paragraph.
  35 &lt;/para&gt;
  36
  37 </verbatim>
  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 </para>
  43
  44 <verbatim>
  45    &lt;quote&gt;
  46    This is an example of a quote.
  47    The text within a quoted paragraph is usually slightly indented on both
  48    the left and the right margin.
  49    &lt;/quote&gt;
  50 </verbatim>
  51
  52 <para>
  53 Which results in:
  54 </para>
  55
  56 <quote>
  57 This is an example of a quote.
  58 The text within a quoted paragraph is usually slightly indented on both
  59 the left and the right margin.
  60 </quote>
  61
  62 <para>
  63 A special kind of paragraph is the <strong>verbatim</strong> environment.
  64 Just as in LaTeX, this is used to include literal text output with spaces,
  65 indentation and line breaks preserved.
  66 The practical use for the <strong>verbatim</strong> element is to
  67 include coding examples, such as:
  68 </para>
  69
  70 <verbatim>
  71    &lt;verbatim&gt;
  72       struct complex
  73       {
  74          double   real;
  75          double   imaginary;
  76       };
  77    &lt;/verbatim&gt;
  78 </verbatim>
  79
  80 <para>
  81 Which comes out like this:
  82 </para>
  83
  84 <verbatim>
  85    struct complex
  86    {
  87       double   real;
  88       double   imaginary;
  89    };
  90 </verbatim>
  91
  92 <para>
  93 A variation on the <strong>verbatim</strong> text is the <strong>example</strong>
  94 text.
  95 The only real difference is that <strong>example</strong> is placed inside
  96 a box to make it stand out a bit more.
  97 In fact, when converted to XHTML, only an attribute <code>class='example'</code>
  98 is added.
  99 It is up to the CSS linked to the XHTML page to add additional layout features.
 100 The default styling will only add a border.
 101 Here is the above example shown in an actual <strong>example</strong> element:
 102 </para>
 103
 104 <example>
 105    &lt;example&gt;
 106       struct complex
 107       {
 108          double   real;
 109          double   imaginary;
 110       };
 111    &lt;/example&gt;
 112 </example>
 113
 114 <para>
 115 Which comes out like this:
 116 </para>
 117
 118 <example>
 119    struct complex
 120    {
 121       double   real;
 122       double   imaginary;
 123    };
 124 </example>
 125
 126 </section>
 127
 128 <section>
 129 <heading><label name='footnote'/>Footnotes</heading>
 130 <para>
 131 Footnotes are created with the <strong>footnote</strong> element:
 132 <footnote>This is an example of a footnote</footnote>
 133 </para>
 134
 135 <verbatim>
 136 &lt;footnote&gt;This is an example of a footnote&lt;/footnote&gt;
 137 </verbatim>
 138
 139 <para>
 140 Within a footnote, you can use <emph>inline</emph> content <footnote>described in the
 141 next chapter</footnote> to format the type
 142 styles of the text in the footnote.
 143 It is not possible to use the block content described in this chapter within
 144 a footnote.
 145 </para>
 146
 147 <para>
 148 Footnotes appear at the bottom of the page, with a small number in the
 149 running text referring to that footnote.
 150 </para>
 151
 152 </section>
 153
 154 <section>
 155 <heading><label name='list'/>Lists</heading>
 156 <para>
 157 Three types of lists are supported:
 158 </para>
 159
 160 <itemize>
 161 <item><code>itemize</code> for bulleted lists such as this one.</item>
 162 <item><code>enumerate</code> for numbered lists.</item>
 163 <item><code>description</code> for tagged lists.</item>
 164 </itemize>
 165
 166 <para>
 167 Each item in such a list must be in an <code>item</code> element.
 168 In fact, an <code>item</code> is the only element allowed in an
 169 <code>itemize</code>, <code>enumerate</code> or <code>description</code> element.
 170 You should not put ordinary text or any other element in a list without
 171 enclosing them in <code>&lt;item&gt;</code> and <code>&lt;/item&gt;</code>.
 172 Here is an example of a numbered list:
 173 </para>
 174
 175 <verbatim>
 176
 177 &lt;enumerate&gt;
 178    &lt;item&gt;First you need an enumerate or itemize tag.&lt;/item&gt;
 179    &lt;item&gt;Second, include one or more item elements.&lt;/item&gt;
 180    &lt;item&gt;Finally, put the content inside the items.&lt;/item&gt;
 181 &lt;/enumerate&gt;
 182
 183 </verbatim>
 184
 185 <para>
 186 And this is what the list turns into:
 187 </para>
 188
 189 <enumerate>
 190    <item>First you need an enumerate, itemize or description tag.</item>
 191    <item>Second, include one or more item elements.</item>
 192    <item>Finally, put the content inside the items.</item>
 193 </enumerate>
 194
 195 <para>
 196 In a description list, you make your own tags for each item instead
 197 of the automatically generated bullts or numbers.
 198 The tags for each item go in the <code>tag</code> attribute of the
 199 <code>item</code> element.
 200 So, repeating the above list as a description list:
 201 </para>
 202
 203 <verbatim>
 204 &lt;description&gt;
 205    &lt;item tag='itemize'&gt; for bulleted lists such as this one.&lt;/item&gt;
 206    &lt;item tag='enumerate'&gt; for numbered lists.&lt;/item&gt;
 207    &lt;item tag='description'&gt; for tagged lists.&lt;/item&gt;
 208 &lt;/description&gt;
 209 </verbatim>
 210
 211 <para>
 212 Which creates the following output:
 213 </para>
 214
 215 <description>
 216 <item tag='itemize'> for bulleted lists.</item>
 217 <item tag='enumerate'> for numbered lists.</item>
 218 <item tag='description'> for tagged lists such as this one.</item>
 219 </description>
 220
 221 <para>
 222 An item can contain inline content as well as block-level content.
 223 </para>
 224 </section>
 225
 226 <section>
 227 <heading><label name='graphics'/>Including graphics</heading>
 228 <para>
 229 The empty element <strong>picture</strong> is used to include
 230 graphics in your document, like this:
 231 </para>
 232
 233 <verbatim>
 234    &lt;picture src='diagram.png' eps='diagram' scale='0.5'/&gt;
 235 </verbatim>
 236
 237 <para>
 238 The two attributes are used in either HTML or LaTeX.
 239 </para>
 240 </section>
 241
 242 <section>
 243 <heading><label name='svg'/>Scalable Vector Graphics</heading>
 244
 245 <para>
 246 Scalable vector graphics can be included in the document or
 247 from an external (SVG) file.
 248 With a <strong>src</strong> attribute, the <strong>svg</strong> element
 249 will load the SVG drawing from an external file:
 250 <example>
 251    &lt;svg src='filter.svg'/&gt;
 252 </example>
 253 <svg src='filter.svg'/>
 254 </para>
 255 <para>
 256 When the <strong>src</strong> attribute is omitted, all available SVG
 257 elements can be used within the XML document, of course with the proper namespace declaration:
 258
 259 <example>
 260    &lt;svg xmlns:svg="http://www.w3.org/2000/svg"&gt;
 261       &lt;svg:clipPath id="a"&gt;
 262          &lt;svg:circle cy="90" cx="100" r="60"/&gt;
 263       &lt;/svg:clipPath&gt;
 264       &lt;svg:circle fill="#AAAAAA" cy="90" cx="190"
 265                  r="60" style="clip-path:url(#a)"/&gt;
 266       &lt;svg:circle stroke="black" fill="none" cy="90" cx="100" r="60"/&gt;
 267       &lt;svg:circle stroke="blue" fill="none" cy="90" cx="190" r="60"/&gt;
 268    &lt;/svg&gt;
 269 </example>
 270 <svg xmlns:svg="http://www.w3.org/2000/svg">
 271    <svg:clipPath id="a">
 272       <svg:circle cy="90" cx="100" r="60"/>
 273    </svg:clipPath>
 274    <svg:circle fill="#AAAAAA" cy="90" cx="190"
 275               r="60" style="clip-path:url(#a)"/>
 276    <svg:circle stroke="black" fill="none" cy="90" cx="100" r="60"/>
 277    <svg:circle stroke="blue" fill="none" cy="90" cx="190" r="60"/>
 278 </svg>
 279
 280 </para>
 281
 282 </section>
 283
 284 <section>
 285 <heading><label name='table'/>Tables</heading>
 286 <para>
 287 Creating tables in XMLDoc is much like creating tables in HTML.
 288 First, there is the <code>table</code> element.
 289 The <code>table</code> element may contain an optional <code>thead</code>
 290 and any number of <code>row</code> elements.
 291 Both the <code>thead</code> and the <code>row</code> elements must contain
 292 one or more <code>col</code> elements.
 293 The <code>col</code> elements hold the actual content of
 294 the table, which must be inline content (see next chapter) or block content.
 295 To use the tables in LaTeX, you must supply a <code>cpos</code>
 296 attribute in the <code>table</code> tag.
 297 </para>
 298
 299 <para>
 300 An example of a table is shown below:
 301 </para>
 302
 303 <verbatim>
 304
 305 &lt;table cpos='lr'&gt;
 306   &lt;thead&gt;&lt;col&gt;Drink   &lt;/col&gt;&lt;col&gt;Price&lt;/col&gt;&lt;/thead&gt;
 307   &lt;row&gt;&lt;col&gt;Beer      &lt;/col&gt;&lt;col&gt; 1.80&lt;/col&gt;&lt;/row&gt;
 308   &lt;row&gt;&lt;col&gt;Wiskey    &lt;/col&gt;&lt;col&gt; 3.50&lt;/col&gt;&lt;/row&gt;
 309   &lt;row&gt;&lt;col&gt;Wine      &lt;/col&gt;&lt;col&gt; 2.20&lt;/col&gt;&lt;/row&gt;
 310 &lt;/table>
 311
 312 </verbatim>
 313
 314 <table cpos='lr'>
 315   <thead><col>Drink   </col><col>Price</col></thead>
 316   <row><col>Beer      </col><col> 1.80</col></row>
 317   <row><col>Wiskey    </col><col> 3.50</col></row>
 318   <row><col>Wine      </col><col> 2.20</col></row>
 319 </table>
 320
 321 </section>
 322
 323 </chapter>
 324