docs/xml/xml_help.txt

   1  <!-- -*- sgml -*- -->
   2 ----------------------------------------------
   3 Docbook Reference Manual (1999):
   4 - http://www.oreilly.com/catalog/docbook/
   5 DocBook XSL: The Complete Guide (2002)
   6 - http://www.sagehill.net/docbookxsl/index.html
   7
   8 DocBook elements (what tags are allowed where)
   9 - http://www.oreilly.com/catalog/docbook/chapter/book/refelem.html
  10
  11 Catalogs:
  12 - http://www.sagehill.net/docbookxsl/WriteCatalog.html
  13
  14
  15 ----------------------------------------------
  16 xml to html markup transformations:
  17
  18 <programlisting> --> <pre class="programlisting">
  19 <screen>         --> <pre class="screen">
  20 <option>         --> <code class="option">
  21 <filename>       --> <code class="filename">
  22 <function>       --> <code class="function">
  23 <literal>        --> <code class="literal">
  24 <varname>        --> <code class="varname">
  25 <computeroutput> --> <code class="computeroutput">
  26 <emphasis>       --> <i>
  27 <command>        --> <b class="command">
  28 <blockquote>     --> <div class="blockquote">
  29                      <blockquote class="blockquote">
  30
  31 Important: inside <screen> and <programlisting> blocks, do NOT
  32 use 'html entities' in your markup, eg. '&lt;' If you *do* use
  33 them, they will be output verbatim, which is not what you want.
  34 Instead, wrap the content with CDATA tags (see below).
  35
  36 ----------------------------------------------
  37
  38 <ulink url="http://..">http://kcachegrind.sourceforge.net</ulink>
  39
  40
  41 ----------------------------------------------
  42 <variablelist>                         --> <dl>
  43  <varlistentry>
  44   <term>TTF</term>                     --> <dt>
  45   <listitem>TrueType fonts.</listitem> --> <dd>
  46  </varlistentry>
  47 </variablelist>                        --> <dl>
  48
  49
  50 ----------------------------------------------
  51 <itemizedlist>          --> <ul>
  52  <listitem>             --> <li>
  53   <para>....</para>
  54   <para>....</para>
  55  </listitem>            --> </li>
  56 </itemizedlist>         --> </ul>
  57
  58
  59 ----------------------------------------------
  60 <orderedlist>           --> <ol>
  61  <listitem>             --> <li>
  62   <para>....</para>
  63   <para>....</para>
  64  </listitem>            --> </li>
  65 </orderedlist>          --> </ol>
  66
  67
  68 ----------------------------------------------
  69 To achieve this:
  70
  71 This is a paragraph of text before a list:
  72
  73   * some text
  74
  75   * some more text
  76
  77 and this is some more text after the list.
  78
  79 Do this:
  80 <para>This is a paragraph of text before a list:</para>
  81 <itemizedlist>
  82  <listitem>
  83   <para>some text</para>
  84  </listitem>
  85  <listitem>
  86   <para>some more text</para>
  87  </listitem>
  88 </itemizedlist>
  89
  90 <para>and this is some more text after the list.</para>
  91
  92
  93 ----------------------------------------------
  94 To achieve this:
  95 For further details, see <a href="clientreq">The Mechanism</a>
  96
  97 Do this:
  98
  99   Given:
 100   <sect1 id="clientreq" xreflabel="The Mechanism">
 101    <title>The Mechanism</title>
 102    <para>...</para>
 103   </sect1>
 104
 105   Then do:
 106   For further details, see <xref linkend="clientreq"/>.
 107
 108
 109 ----------------------------------------------
 110 To achieve this:
 111 <p><b>Warning:</b> Only do this if ...</p>
 112
 113 Do this:
 114 <formalpara>
 115  <title>Warning:</title>
 116  <para>Only do this if ...</para>
 117 </formalpara>
 118
 119 Or this:
 120 <para><command>Warning:</command> Only do this if ... </para>
 121
 122
 123 ----------------------------------------------
 124 To achieve this:
 125 <p>It uses the Eraser algorithm described in:<br/>
 126 <br/>
 127   Eraser: A Dynamic Data Race Detector for Multithreaded Programs<br/>
 128   Stefan Savage, Michael Burrows, Patrick Sobalvarro and Thomas Anderson<br/>
 129   ACM Transactions on Computer Systems, 15(4):391-411<br/>
 130   November 1997.<br/>
 131 </p>
 132
 133 Do this:
 134 <literallayout>
 135 It uses the Eraser algorithm described in:
 136
 137   Eraser: A Dynamic Data Race Detector for Multithreaded Programs
 138   Stefan Savage, Michael Burrows, Patrick Sobalvarro and Thomas Anderson
 139   ACM Transactions on Computer Systems, 15(4):391-411
 140   November 1997.
 141 </literallayout>
 142
 143
 144 ----------------------------------------------
 145 To achieve this:
 146 <pre>
 147 /* Hook to delay things long enough so we can get the pid
 148    and attach GDB in another shell. */
 149 if (0) {
 150   Int p, q;
 151   for ( p = 0; p < 50000; p++ )
 152     for ( q = 0; q < 50000; q++ ) ;
 153 </pre>
 154
 155 Do this:
 156 <programlisting><![CDATA[
 157 /* Hook to delay things long enough so we can get the pid
 158    and attach GDB in another shell. */
 159 if (0) {
 160   Int p, q;
 161   for ( p = 0; p < 50000; p++ )
 162     for ( q = 0; q < 50000; q++ ) ;
 163 }]]></programlisting>
 164
 165
 166 (do the same thing for <screen> tag)
 167
 168
 169 ----------------------------------------------
 170 To achieve this:
 171   where <i><code>TAG</code></i> has the ...
 172
 173 Do this:
 174   where <emphasis><computeroutput>TAG</computeroutput></emphasis> has the ...
 175
 176 Note: you cannot put <emphasis> inside <computeroutput>, unfortunately.
 177
 178 ----------------------------------------------
 179
 180 Any other helpful hints?  Please add to this.