<?xml version="1.0"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
<document>
  <header>
    <title>The Apache Forrest xdocs document-v2.0 DTD</title>
    <notice>The content of this document doesn't make any sense at all.</notice>
    <abstract>
      This is a demonstration document using all possible elements in the
      current Apache Forrest xdocs <code>document-v20.dtd</code>
    </abstract>
  </header>
  <body>
    <note>
      This is a demonstration document using all possible elements in the
      current Apache Forrest xdocs <code>document-v20.dtd</code> (See the
      <a href="#changes">DTD changes</a> section at the bottom.)
    </note>
    <section id="sample">
      <title>Sample Content</title>
      <p>
        <strong>Hint:</strong> See the xml source to see how the various
        elements are used and see the <a href="site:dtd-docs">DTD reference
        documentation</a>.
      </p>
      <section id="block-inline">
        <title>Block and inline elements</title>
        <p>
          This is a simple paragraph. Most documents contain a fair amount of
          paragraphs. Paragraphs are called <code>&lt;p&gt;</code>.
        </p>
        <p xml:space="preserve">
          With the <code>&lt;p xml:space="preserve"&gt;</code> attribute, you can declare
          that whitespace should    be   preserved, without implying it is in any other
          way special.
        </p>
        <p>
          This next paragraph has a class attribute of 'quote'. CSS can be used
          to present this <code>&lt;p class='quote'&gt;</code> in a different
          style than the other paragraphs. The handling of this quoted paragraph
          is defined in the &lt;extra-css&gt; element in the skinconf.xml.
        </p>
        <p class="quote">
          Anyway, like I was sayin', shrimp is the fruit of the sea. You can
          barbecue it, boil it, broil it, bake it, sautee it. Dey's uh,
          shrimp-kabobs, shrimp creole, shrimp gumbo. Pan fried, deep fried,
          stir-fried. There's pineapple shrimp, lemon shrimp, coconut shrimp,
          pepper shrimp, shrimp soup, shrimp stew, shrimp salad, shrimp and
          potatoes, shrimp burger, shrimp sandwich. That- that's about it.
        </p>
        <p>
          A number of in-line elements are available in the DTD, we will show
          them inside an unordered list (<code>&lt;ul&gt;</code>):
        </p>
        <ul>
          <li>Here is a simple list item (<code>&lt;li&gt;</code>).</li>
          <li>Have you seen the use of the <code>&lt;code&gt;</code> element in the
          previous item?</li>
          <li>Also, we have <code>&lt;sub&gt;</code> and <code>&lt;sup&gt;</code>
          elements to show content <sup>above</sup> or <sub>below</sub> the text
          baseline.</li>
          <li>There is a facility to <em>emphasize</em> certain words using the
          <code>&lt;em&gt;</code><strong><code>&lt;strong&gt;</code></strong>
          elements.</li>
          <li>We can use
          <icon height="22" width="26" src="images/icon.png" alt="feather"/><code>&lt;icon&gt;</code>s too.</li>
          <li>Another possibility is the <code>&lt;img&gt;</code> element:
          <img src="images/icon.png" alt="another feather" height="22" width="26"/>,
          which offers the ability to refer to an image map.</li>
          <li>We have elements for hyperlinking: 
          <dl>
              <dt><code>&lt;a href="../index.html"&gt;</code></dt>
              <dd>Use this to
              <a href="../index.html" title="Example of a document via link">link</a>
              to another document. As per normal, this will open the new document
              in the same browser window.</dd>
              <dt><code>&lt;a href="#section"&gt;</code></dt>
              <dd>Use this to
              <a href="#section" title="Example of a document via local anchor">link</a>
              to the named anchor in the current document.
            </dd>
              <dt><code>&lt;a href="../index.html#status"&gt;</code></dt>
              <dd>Use this to
              <a href="../index.html#status" title="Example of a document via link and anchor">link</a>
              to another document and go to the named anchor. This will open
              the new document in the same browser window.
            </dd>
              <dt>Targetted window control with jump and fork.</dt>
              <dd>See demonstration
             <a href="#link-class">using class attribute on links</a>.
            </dd>
            </dl></li>
          <li>Oh, by the way, a definition list <code>&lt;dl&gt;</code> was used inside
          the previous list item. We could put another 
          <ul>
              <li>unordered list</li>
              <li>inside the list item</li>
            </ul>
            <table>
              <caption>A sample nested table</caption>
              <tr>
                <td>Or even tables.. </td>
                <td>
                  <table>
                    <tr>
                      <td>inside tables..</td>
                    </tr>
                  </table>
                </td>
              </tr>
              <tr>
                <td>or inside lists, but I believe this liberty gets quickly quite
                hairy as you see.</td>
              </tr>
            </table></li>
        </ul>
        <p>
          So far for the in-line elements, let's look at some paragraph-level
          elements.
        </p>
        <fixme author="SN">
          The <code>&lt;fixme&gt;</code> element is used for stuff which still
          needs work. Mind the <code>author</code> attribute!
        </fixme>
        <note>
          Use the <code>&lt;note&gt;</code> element to draw attention to
          something, e.g. ...The <code>&lt;code&gt;</code> element is used when
          the author can't express himself clearly using normal sentences ;-)
        </note>
        <warning>
          Sleep deprivation can be the result of being involved in an open
          source project. (a.k.a. the <code>&lt;warning&gt;</code> element).
        </warning>
        <note label="Important">
          If you want your own labels for notes and warnings, specify them using
          the <code>label</code> attribute.
        </note>
        <p>
          Apart from unordered lists, we have ordered lists too, of course.
        </p>
        <ol>
          <li>Item 1</li>
          <li>Item 2</li>
          <li>This should be 3 if my math is still OK.</li>
        </ol>
      </section>
      <section id="presentations">
        <title>Various presentation formats</title>
        <p>
          This sample document, written in document-v20 XML can be presented via
          Forrest in a number of different formats. The links in the following
          list show this document in each of the currently available formats.
        </p>
        <p>
          Each of the formats can be made available as a link near the top of
          the page. Actual placement of those links depends on the skin
          currently in use. Those links are enabled in the skinconf.xml via the
          &#60;disable-XXX-link&#62; elements in the skinconf.xml
        </p>
        <table>
          <tr>
            <th>Presentation Format</th>
            <th>Description</th>
            <th>skinconf.xml Element</th>
          </tr>
          <tr>
            <td><a href="document-v20.html">HTML</a>
            </td>
            <td>This document in HTML format. </td>
            <td>Always generated by default. Cannot be turned off.</td>
          </tr>
          <tr>
            <td><a href="document-v20.xml">XML</a>
            </td>
            <td>This document in its raw XML format.</td>
            <td>&#60;disable-xml-link&#62;. By default, set to true, meaning
            that this link will not be shown.</td>
          </tr>
          <tr>
            <td><a href="document-v20.pdf">PDF</a>
            </td>
            <td>This document as Adobe PDF</td>
            <td>&#60;disable-pdf-link&#62;. By default, set to false, meaning
            that this link will be shown.</td>
          </tr>
          <tr>
            <td><a href="document-v20.txt">Text</a>
            </td>
            <td>
              <p>
                This document as straight text.
              </p>
              <p>
                For additional information see the Forrest text-output plugin.
              </p>
            </td>
            <td>&#60;disable-txt-link&#62;. By default, set to true, meaning
            that this link will not be shown.</td>
          </tr>
          <tr>
            <td><a href="document-v20.pod">POD</a>
            </td>
            <td>
              <p>
                This document as Perl POD (Plain Old Documentation). Text with
                minimal formatting directives. If on a *nix system with perl
                installed, see &#34;man perlpod&#34;.
              </p>
              <p>
                For additional information see the Forrest pod-output plugin.
              </p>
            </td>
            <td>&#60;disable-pod-link&#62;. By default, set to true, meaning
            that this link will not be shown.</td>
          </tr>
        </table>
      </section>
      <section id="section">
        <title>Using sections</title>
        <p>
          You can use sections to put some structure in your document.
        </p>
      </section>
      <section id="sub-section">
        <title>Sections, the sequel</title>
        <p>
          Just some second section.
        </p>
        <section id="sub-sub-section">
          <title>Section 2.1</title>
          <p>
            Which contains a subsection (2.1).
          </p>
        </section>
      </section>
      <section id="source">
        <title>Showing preformatted source code</title>
        <p>
          Enough about these sections. Let's have a look at more interesting
          elements, <code>&lt;source&gt;</code> for instance:
        </p>
        <source>
// This example is from the book _Java in a Nutshell_ by David Flanagan.
// Written by David Flanagan.  Copyright (c) 1996 O'Reilly &amp; Associates.
// You may study, use, modify, and distribute this example for any purpose.
// This example is provided WITHOUT WARRANTY either expressed or implied.

import java.applet.*;    // Don't forget these import statements!
import java.awt.*;

public class FirstApplet extends Applet {
    // This method displays the applet.
    // The Graphics class is how you do all drawing in Java.
    public void paint(Graphics g) {
        g.drawString("Hello World", 25, 50);
    }
}</source>
        <p>
          CDATA sections are used within <code>&lt;source&gt;</code> elements so
          that you can write pointy brackets without needing to escape them with
          messy <code>&amp;lt;</code> entities ...
        </p>
        <source>
<![CDATA[
<pointy>
  easy
</pointy>
]]>
        </source>
        <p>
          Please take care to still use a sensible line-length within your
          source elements.
        </p>
      </section>
      <section id="table">
        <title>Using tables</title>
        <p>
          And now for a table:
        </p>
        <table>
          <caption>Table caption</caption>
          <tr>
            <th>heading cell 1</th>
            <th>heading cell 2</th>
            <th>heading cell 3</th>
          </tr>
          <tr>
            <td>data cell</td>
            <td colspan="2">this data cell spans two columns</td>
          </tr>
          <tr>
            <td>
              Tables can be nested:
            </td>
            <td>
              <table>
                <tr>
                  <th>column 1</th>
                  <th>column 2</th>
                </tr>
                <tr>
                  <td>cell A</td>
                  <td>cell B</td>
                </tr>
              </table>
            </td>
            <td>
              <ul>
                <li>and can include most other elements</li>
                <li>such as lists</li>
              </ul>
            </td>
          </tr>
        </table>
      </section>
      <anchor id="second-figure-anchor"/>
      <section id="figure">
        <title>Using figures</title>
        <p>
          And a <code>&lt;figure&gt;</code> to end all of this. Note that this
          can also be implemented with an <code>&lt;img&gt;</code> element.
        </p>
        <figure src="images/project-logo.png" alt="The fine Forrest logo" width="220" height="65"/>
      </section>
      <section id="link-class">
        <title>Using class attribute on links</title>
        <p>
          The document-v13 had elements &lt;fork&gt; and &lt;jump&gt;. In
          document-v20, those elements no longer exist but the functionality can
          be duplicated by using the @class attribute. Even though the opening
          of separate windows should be under the control of the user, these
          techniques can still be employed.
        </p>
        <table>
          <tr>
            <th>
              <p>
                Document V1.3
              </p>
            </th>
            <th>
              <p>
                Document V2.0
              </p>
            </th>
          </tr>
          <tr>
            <td>
              <p>
                &lt;fork href="../index.html"&gt;
              </p>
            </td>
            <td><a class="fork" href="../index.html">&lt;a class="fork"
            href="../index.html"&gt;</a>
            </td>
          </tr>
          <tr>
            <td>
              <p>
                &lt;jump href="../index.html"&gt;
              </p>
            </td>
            <td>
              <p>
                <a class="jump" href="../index.html">&lt;a class="jump"
                href="../index.html"&gt;</a>
              </p>
            </td>
          </tr>
        </table>
      </section>
    </section>
    <section id="changes">
      <title>DTD changes</title>
      <p>
        See the generated <a href="site:dtd-docs">DTD reference
        documentation</a>.
      </p>
      <section id="changes-20">
        <title>Changes between document-v13 and document-v20</title>
        <ul>
          <li>Renamed <strong>&lt;link&gt;</strong>
             to <strong>&lt;a&gt;</strong></li>
          <li>Removed <strong>&lt;fork&gt;</strong>
             and <strong>&lt;jump&gt;</strong> in favour of the
             <strong>&lt;a&gt;</strong> element. See demonstration
             <a href="#link-class">using class attribute on links</a>.
          </li>
        </ul>
      </section>
      <section id="changes-13">
        <title>Changes between document-v12 and document-v13</title>
        <p>
          All v1.2 docs will work fine as v1.3 DTD. The main change is the
          addition of a @class attribute to every element, which enables the
          "extra-css" section in the skinconf to be put to good use.
        </p>
      </section>
      <section id="changes-12">
        <title>Changes between document-v11 and document-v12</title>
        <p>
          doc-v12 enhances doc-v11 by relaxing various restrictions that were
          found to be unnecessary.
        </p>
        <ul>
          <li>
            Links ((link|jump|fork) and inline elements (br|img|icon|acronym) are
            allowed inside title.
          </li>
          <li>
            Paragraphs (p|source|note|warning|fixme), table and figure|anchor are
            allowed inside li.
          </li>
          <li>
            Paragraphs (p|source|note|warning|fixme), lists (ol|ul|dl), table,
            figure|anchor are allowed inside definition lists (dd) and tables (td
            and dh).
          </li>
          <li>
            Inline content
            (strong|em|code|sub|sup|br|img|icon|acronym|link|jump|fork) is
            allowed in strong and em.
          </li>
        </ul>
      </section>
    </section>
  </body>
  <footer>
    <legal>This is a legal notice, so it is <strong>important</strong>.</legal>
  </footer>
</document>
