<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//MAKUMBA//DTD Documentation V2.0//EN" "document-v20-makumba.dtd">
<document>
  <header>
    <title>Makumba documentation examples and guidelines</title>
  </header>
  <body>
    
    <p>This document presents the documentation examples and guidelines of the Makumba website with Apache Forrest.</p>
    <section>
      <title>General document structure</title>
      
      <p>The general document structure of a Forrest document is like this:</p>
      <source>
        <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//MAKUMBA//DTD Documentation V2.0//EN" "document-v20-makumba.dtd">
<document>
  <header>
    <title>Page title</title>
  </header>
  <body>
    <p>Some introduction text, if necessary.</p>
    <section>
      <title>Section title</title>
      <p>Section content</p>
      <section>
        <title>Subsection title</title>
        <p>Subsection content</p>
      </section>
    </section>
  </body>
</document>
        ]]>        
      </source>
      <p>
        It is possible to give id's to sections, in order to refer to them via anchor links (<code>myPage.html#mySection</code>).
      </p>
      <p>Forrest will automatically generate a table of contents for the page</p>
    </section>
    
    <section>
      <title>Text styles</title>
      <p>Text can be strong or emphasized:</p>
      <source><![CDATA[<strong>Strong text</strong> ]]></source>
      <p><strong>Strong text</strong></p>
      <source><![CDATA[<em>Emphasized text</em> ]]></source>
      <p><em>Emphasized text</em></p>
      
      
    </section>
    <section>
      <title>Paragraphs, notes, warnings, fixme's, inlined html</title>
    
    <section>
      <title>Normal paragraphs</title>
      <p>Normal paragraphs are easy to do:</p>
      <source>
        <![CDATA[ <p>This is a paragraph with content</p> ]]>
        
      </source>
      <p>It is possible to use a specific class for paragraphs, such as:</p>
      <source><![CDATA[<p class="quote">Quoted text</p>]]></source>
      <p class="quote">Quoted text</p>
      <note>We may add some more paragraph classes later on if needed.</note>
    </section>

<section>
  <title>Notes</title>
  <p>It's possible to make notes easily:</p>
  <source><![CDATA[<note>This is a note</note> ]]></source>
  <note>This is a note</note>
  <p>Notes can have labels:</p>
  <source><![CDATA[<note label="Custom label">This is a note with a label.</note> ]]>
  </source>
  <note label="Custom label">This is a note with a label.</note>
</section>

      <section>
        <title>Warnings</title>
        <p>It's possible to make warnings easily:</p>
        <source><![CDATA[<warning>This is a warning</warning> ]]></source>
        <warning>This is a warning</warning>
        <p>Warnings can have labels:</p>
        <source><![CDATA[<warning label="Custom label">This is a warning with a label.</warning> ]]>
        </source>
        <warning label="Custom label">This is a warning with a label.</warning>
      </section>
      
      
      <section>
        <title>Fixme's</title>
        <p>It's possible to make FIXME elements. Those should be used in order to add FIXME's in the documentation, if needed:</p>
        <source><![CDATA[<fixme author="manu">This is a fixme</fixme> ]]></source>
        <fixme author="manu">This is a fixme</fixme>
        <p>FIXME's must have an author attribute.</p>
      </section>
      
      <section>
        <title>Inlined HTML</title>
        <p>If needed, it is possible to add inlined HTML to a page, e.g. to show examples of what some code renders. Inlined HTML should <strong>NOT</strong> be used to do the normal formatting, in that case, Forrest should be extended.</p>
        <source>
          
          <![CDATA[
          <ihtml>
            <![CDATA[
          <select>
            <option>Choice 1</option>
            <option>Choice 2</option>
          </select>
          \]\]>
          </ihtml> ]]>
          
        </source>
        <ihtml>
          <![CDATA[
          <select>
            <option>Choice 1</option>
            <option>Choice 2</option>
          </select>
          ]]>
        </ihtml>
      </section>
      <note>This is NOT a standard behaviour of Forrest. In order to work correctly, the content of the <code>&lt;ihtml&gt;</code> tag must be surrounded with CDATA. (this does not show correctly in the source above, since it would not rendred correctly otherwise)</note>
      

    </section>
    <section>
      <title>Source code</title>
      <p>Source code can be included using the <code>&lt;code&gt;</code> and the <code>&lt;source&gt;</code> tags:</p>
      <section>
        <title><code>&lt;code&gt;</code> tag</title>
        <source>
          <![CDATA[<code>small code snippet, in the paragraph text</code]]>
        </source>
        <p><code>small code snippet, in the paragraph text</code></p>
        <p>The <code>&lt;code&gt;</code> tag is part of a paragraph and should be used for small code snippets.</p>
      </section>
      <section>
        <title><code>&lt;source&gt;</code> tag</title>
      </section>
      
      <source>
        <![CDATA[
        <source>
        <![CDATA[
        <mak:list from="general.Person p">
          <mak:value from="p.name" />
        </mak:list>
        \]\]>
      </source>]]>
      </source>
      
      <p>will generate:</p>
      
      <source>
        <![CDATA[
        <mak:list from="general.Person p">
          <mak:value from="p.name" />
        </mak:list>
        ]]>
      </source>
      
      <p>The <code>&lt;source&gt;</code> tag is not part of a paragrah, and should be used to show larger examples of source code.</p>
      <note>As for the <code>&lt;ihtml&gt;</code> tag, the content of the source tag should be surrounded by CDATA (this does not show correctly in the source above, since it would not rendred correctly otherwise) . It is not compulsory but a very good practice in order to keep indentation when formatting the XML document with some automatic formatting tool. </note>
     </section>
    <section id="links">
      <title>Links</title>
      <p>It is possible to link to other pages:</p>
      <source>
        <![CDATA[<a href="status.html">Status of the documentation</a> ]]>
      </source>
      <p><a href="status.html">Status of the documentation</a></p>
      <p>or to specific sections, provided they have an <code>id</code> attribute:</p>
      <source>
        <![CDATA[<a href="status.html">Status of the documentation</a> ]]>
      </source>
      <p><a href="example.html#links">This section</a></p>
      <p>If external links are used frequently, it is possible to add them to <a href="site.xml"><code>site.xml</code></a> and use the <code>ext:</code> link:</p>
      <source>
        <![CDATA[<a href="ext:mysql">MySQL</a> ]]>
      </source>
      <p><a href="ext:mysql">MySQL</a></p>
      <p>In much the same way, the nodes in <a href="site.xml"><code>site.xml</code></a> can be referred to using the <code>site:</code> link:</p>
      <source>
        <![CDATA[<a href="site:documentation//overview">Documentation</a>]]>
      </source>
      <p><a href="site:documentation//overview">Documentation</a></p>
      <p>Note that those links use XPATH to determine to which node to link to.</p>
    </section>
    <section>
      <title>Tables</title>
      <p>Forrest also supports standard tables:</p>
      <table>
        <tr><th>Header 1</th><th>Header 2</th></tr>
        <tr><td>Column 1</td><td>Column 2</td></tr>
      </table>
      <source><![CDATA[<table>
        <tr><th>Header 1</th><th>Header 2</th></tr>
        <tr><td>Column 1</td><td>Column 2</td></tr>
      </table>]]>      
      </source>
      <note>Tables in forrest do not have the <code>&lt;thead&gt;</code> and <code>&lt;tbody&gt;</code></note>
    </section>
    
    
  </body>
</document>