wamblee.org Git - utils/blob

   1 <?xml version="1.0"?>
   2 <!--
   3   Copyright 2002-2004 The Apache Software Foundation or its licensors,
   4   as applicable.
   5
   6   Licensed under the Apache License, Version 2.0 (the "License");
   7   you may not use this file except in compliance with the License.
   8   You may obtain a copy of the License at
   9
  10       http://www.apache.org/licenses/LICENSE-2.0
  11
  12   Unless required by applicable law or agreed to in writing, software
  13   distributed under the License is distributed on an "AS IS" BASIS,
  14   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15   See the License for the specific language governing permissions and
  16   limitations under the License.
  17 -->
  18 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
  19 <document>
  20   <header>
  21     <title>The Apache Forrest xdocs document-v2.0 DTD</title>
  22     <notice>The content of this document doesn't make any sense at all.</notice>
  23     <abstract>This is a demonstration document using all possible elements in
  24       the current Apache Forrest xdocs <code>document-v20.dtd</code>
  25     </abstract>
  26   </header>
  27   <body>
  28     <note>
  29       This is a demonstration document using all possible elements in the
  30       current Apache Forrest xdocs <code>document-v20.dtd</code>
  31       (See the <a href="#changes">DTD changes</a> section at the bottom.)
  32     </note>
  33     <section id="sample">
  34       <title>Sample Content</title>
  35       <p><strong>Hint:</strong> See the xml source to see how the various
  36       elements are used and see the
  37 <!-- FOR-321 workaround
  38       <a href="ext:dtd-docs">DTD reference documentation</a>.
  39 -->
  40       <a href="http://forrest.apache.org/docs/dtd-docs.html">DTD reference documentation</a>.
  41       </p>
  42       <section id="block-inline">
  43         <title>Block and inline elements</title>
  44       <p>This is a simple paragraph. Most documents contain a fair amount of
  45         paragraphs. Paragraphs are called <code>&lt;p&gt;</code>.</p>
  46       <p xml:space="preserve"
  47         >With the <code>&lt;p xml:space="preserve"&gt;</code> attribute, you can declare
  48         that whitespace should    be   preserved, without implying it is in any other
  49         way special.</p>
  50       <p>
  51         This next paragraph has a class attribute of 'quote'.  CSS can
  52         be used to present this <code>&lt;p class='quote'&gt;</code> in
  53         a different style than the other paragraphs.  The handling of
  54         this quoted paragraph is defined in the &lt;extra-css&gt;
  55         element in the skinconf.xml.
  56       </p>
  57       <p class="quote">
  58         Anyway, like I was sayin', shrimp is the fruit of the sea. You can
  59         barbecue it, boil it, broil it, bake it, sautee it. Dey's uh,
  60         shrimp-kabobs, shrimp creole, shrimp gumbo. Pan fried, deep fried,
  61         stir-fried. There's pineapple shrimp, lemon shrimp, coconut shrimp,
  62         pepper shrimp, shrimp soup, shrimp stew, shrimp salad, shrimp and
  63         potatoes, shrimp burger, shrimp sandwich. That- that's about it.
  64       </p>
  65       <p>A number of in-line elements are available in the DTD, we will show them
  66         inside an unordered list (<code>&lt;ul&gt;</code>):</p>
  67       <ul>
  68         <li>Here is a simple list item (<code>&lt;li&gt;</code>).</li>
  69         <li>Have you seen the use of the <code>&lt;code&gt;</code> element in the
  70           previous item?</li>
  71         <li>Also, we have <code>&lt;sub&gt;</code> and <code>&lt;sup&gt;</code>
  72           elements to show content <sup>above</sup> or <sub>below</sub> the text
  73           baseline.</li>
  74         <li>There is a facility to <em>emphasize</em> certain words using the
  75           <code>&lt;em&gt;</code> <strong><code>&lt;strong&gt;</code></strong>
  76           elements.</li>
  77         <li>We can use
  78           <icon height="22" width="26" src="../images/icon.png" alt="feather"/>
  79           <code>&lt;icon&gt;</code>s too.</li>
  80         <li>Another possibility is the <code>&lt;img&gt;</code> element:
  81           <img src="../images/icon.png" alt="another feather" height="22" width="26"/>,
  82           which offers the ability to refer to an image map.</li>
  83         <li>We have elements for hyperlinking:
  84           <dl>
  85             <dt><code>&lt;a href="faq.html"&gt;</code></dt>
  86             <dd>Use this to
  87               <a href="faq.html" title="Example of a document via link">link</a>
  88               to another document. As per normal, this will open the new document
  89               in the same browser window.</dd>
  90
  91             <dt><code>&lt;a href="#section"&gt;</code></dt>
  92             <dd>Use this to
  93               <a href="#section" title="Example of a document via local anchor">link</a>
  94               to the named anchor in the current document.
  95             </dd>
  96
  97             <dt><code>&lt;a href="faq.html#forrest"&gt;</code></dt>
  98             <dd>Use this to
  99               <a href="faq.html#forrest" title="Example of a document via link and anchor">link</a>
 100               to another document and go to the named anchor. This will open
 101               the new document in the same browser window.
 102             </dd>
 103             <dt>Targetted window control with jump and fork.</dt>
 104             <dd>See demonstration
 105              <a href="#link-class">using class attribute on links</a>.
 106             </dd>
 107         </dl></li>
 108
 109         <li>Oh, by the way, a definition list <code>&lt;dl&gt;</code> was used inside
 110           the previous list item. We could put another
 111           <ul>
 112             <li>unordered list</li>
 113             <li>inside the list item</li>
 114           </ul>
 115           <table>
 116             <caption>A sample nested table</caption>
 117             <tr><td>Or even tables.. </td><td>
 118                 <table><tr><td>inside tables..</td></tr></table>
 119             </td></tr>
 120             <tr><td>or inside lists, but I believe this liberty gets quickly quite
 121                 hairy as you see.</td></tr>
 122           </table>
 123         </li>
 124       </ul>
 125       <p>So far for the in-line elements, let's look at some paragraph-level
 126         elements.</p>
 127       <fixme author="SN">The <code>&lt;fixme&gt;</code> element is used for stuff
 128         which still needs work. Mind the <code>author</code> attribute!</fixme>
 129       <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
 130         express himself clearly using normal sentences ;-)</note>
 131       <warning>Sleep deprivation can be the result of being involved in an open
 132         source project. (a.k.a. the <code>&lt;warning&gt;</code> element).
 133       </warning>
 134       <note label="Important">If you want your own labels for notes and
 135         warnings, specify them using the <code>label</code> attribute.
 136       </note>
 137       <p>Apart from unordered lists, we have ordered lists too, of course.</p>
 138       <ol>
 139         <li>Item 1</li>
 140         <li>Item 2</li>
 141         <li>This should be 3 if my math is still OK.</li>
 142       </ol>
 143       </section>
 144
 145       <section id="presentations">
 146         <title>Various presentation formats</title>
 147
 148         <p>This sample document, written in document-v20 XML can be presented
 149         via Forrest in a number of different formats. The links in the
 150         following list show this document in each of the currently available
 151         formats.</p>
 152
 153         <p>Each of the formats can be made available as a link near the top of
 154         the page. Actual placement of those links depends on the skin
 155         currently in use. Those links are enabled in the skinconf.xml via the
 156         &#60;disable-XXX-link&#62; elements in the skinconf.xml</p>
 157
 158         <table>
 159           <tr>
 160             <th>Presentation Format</th>
 161
 162             <th>Description</th>
 163
 164             <th>skinconf.xml Element</th>
 165           </tr>
 166
 167           <tr>
 168             <td><a href="sample.html">HTML</a></td>
 169
 170             <td>This document in HTML format. </td>
 171
 172             <td>Always generated by default. Cannot be turned off.</td>
 173           </tr>
 174
 175           <tr>
 176             <td><a href="sample.xml">XML</a></td>
 177
 178             <td>This document in its raw XML format.</td>
 179
 180             <td>&#60;disable-xml-link&#62;. By default, set to true, meaning
 181             that this link will not be shown.</td>
 182           </tr>
 183
 184           <tr>
 185             <td><a href="sample.pdf">PDF</a></td>
 186
 187             <td>This document as Adobe PDF</td>
 188
 189             <td>&#60;disable-pdf-link&#62;. By default, set to false, meaning
 190             that this link will be shown.</td>
 191           </tr>
 192
 193           <tr>
 194             <td>Text</td>
 195
 196             <td><p>This document as straight text.</p>
 197             <p>For additional information see the Forrest text-output
 198             plugin.</p></td>
 199
 200             <td>&#60;disable-txt-link&#62;. By default, set to true, meaning
 201             that this link will not be shown.</td>
 202           </tr>
 203
 204           <tr>
 205             <td>POD</td>
 206
 207             <td><p>This document as Perl POD (Plain Old Documentation). Text
 208             with minimal formatting directives. If on a *nix system with perl
 209             installed, see &#34;man perlpod&#34;.</p>
 210             <p>For additional information see the Forrest pod-output
 211             plugin.</p></td>
 212
 213             <td>&#60;disable-pod-link&#62;. By default, set to true, meaning
 214             that this link will not be shown.</td>
 215           </tr>
 216         </table>
 217       </section>
 218       <section id="section">
 219         <title>Using sections</title>
 220         <p>You can use sections to put some structure in your document. For some
 221           strange historical reason, the section title is an attribute of the
 222           <code>&lt;section&gt;</code> element.</p>
 223       </section>
 224       <section id="sub-section">
 225         <title>Sections, the sequel</title>
 226         <p>Just some second section.</p>
 227         <section id="sub-sub-section">
 228           <title>Section 2.1</title>
 229           <p>Which contains a subsection (2.1).</p>
 230         </section>
 231       </section>
 232
 233       <section id="source">
 234         <title>Showing preformatted source code</title>
 235         <p>Enough about these sections. Let's have a look at more interesting
 236           elements, <code>&lt;source&gt;</code> for instance:</p>
 237         <source>
 238 // This example is from the book _Java in a Nutshell_ by David Flanagan.
 239 // Written by David Flanagan.  Copyright (c) 1996 O'Reilly &amp; Associates.
 240 // You may study, use, modify, and distribute this example for any purpose.
 241 // This example is provided WITHOUT WARRANTY either expressed or implied.
 242
 243 import java.applet.*;    // Don't forget these import statements!
 244 import java.awt.*;
 245
 246 public class FirstApplet extends Applet {
 247     // This method displays the applet.
 248     // The Graphics class is how you do all drawing in Java.
 249     public void paint(Graphics g) {
 250         g.drawString("Hello World", 25, 50);
 251     }
 252 }</source>
 253         <p>CDATA sections are used within
 254           <code>&lt;source&gt;</code> elements so that you can write pointy
 255            brackets without needing to escape them with messy
 256           <code>&amp;lt;</code> entities ...
 257         </p>
 258         <source><![CDATA[
 259 <pointy>
 260   easy
 261 </pointy>
 262 ]]></source>
 263         <p>Please take care to still use a sensible line-length within your
 264           source elements.</p>
 265       </section>
 266
 267       <section id="table">
 268         <title>Using tables</title>
 269         <p>And now for a table:</p>
 270         <table>
 271           <caption>Table caption</caption>
 272           <tr>
 273             <th>heading cell 1</th>
 274             <th>heading cell 2</th>
 275             <th>heading cell 3</th>
 276           </tr>
 277           <tr>
 278             <td>data cell</td>
 279             <td colspan="2">this data cell spans two columns</td>
 280           </tr>
 281           <tr>
 282             <td>
 283               Tables can be nested:
 284             </td>
 285             <td>
 286               <table>
 287                 <tr>
 288                   <th>column 1</th>
 289                   <th>column 2</th>
 290                 </tr>
 291                 <tr>
 292                   <td>cell A</td>
 293                   <td>cell B</td>
 294                 </tr>
 295               </table>
 296             </td>
 297             <td>
 298               <ul><li>and can include most other elements</li><li>such as lists</li></ul>
 299             </td>
 300           </tr>
 301         </table>
 302       </section>
 303
 304       <anchor id="second-figure-anchor"/>
 305       <section id="figure">
 306         <title>Using figures</title>
 307         <p>And a <code>&lt;figure&gt;</code> to end all of this.
 308           Note that this can also be implemented with an
 309           <code>&lt;img&gt;</code> element.
 310         </p>
 311         <figure src="../images/project.png" alt="The fine Forrest logo" width="220" height="65"/>
 312       </section>
 313       <section id="link-class">
 314         <title>Using class attribute on links</title>
 315
 316         <p>The document-v13 had elements &lt;fork&gt; and &lt;jump&gt;. In
 317         document-v20, those elements no longer exist but the functionality can
 318         be duplicated by using the @class attribute.
 319         Even though the opening of separate windows should be under the
 320         control of the user, these techniques can still be employed.</p>
 321
 322         <table>
 323           <tr>
 324             <th><p>Document V1.3</p></th>
 325
 326             <th><p>Document V2.0</p></th>
 327           </tr>
 328
 329           <tr>
 330             <td><p>&lt;fork href="faq.html"&gt;</p></td>
 331
 332             <td><a class="fork" href="faq.html">&lt;a class="fork"
 333             href="faq.html"&gt;</a></td>
 334           </tr>
 335
 336           <tr>
 337             <td><p>&lt;jump href="faq.html"&gt;</p></td>
 338
 339             <td><p><a class="jump" href="faq.html">&lt;a class="jump"
 340             href="faq.html"&gt;</a></p></td>
 341           </tr>
 342         </table>
 343       </section>
 344     </section>
 345
 346     <section id="changes">
 347       <title>DTD changes</title>
 348       <p>See the generated
 349 <!-- FOR-321 workaround
 350       <a href="ext:dtd-docs">DTD reference documentation</a>.
 351 -->
 352       <a href="http://forrest.apache.org/docs/dtd-docs.html">DTD reference documentation</a>.
 353       </p>
 354       <section id="changes-20">
 355         <title>Changes between document-v13 and document-v20</title>
 356         <ul>
 357           <li>Renamed <strong>&lt;link&gt;</strong>
 358              to <strong>&lt;a&gt;</strong>
 359           </li>
 360           <li>Removed <strong>&lt;fork&gt;</strong>
 361              and <strong>&lt;jump&gt;</strong> in favour of the
 362              <strong>&lt;a&gt;</strong> element. See demonstration
 363              <a href="#link-class">using class attribute on links</a>.
 364           </li>
 365         </ul>
 366       </section>
 367       <section id="changes-13">
 368         <title>Changes between document-v12 and document-v13</title>
 369         <p>
 370           All v1.2 docs will work fine as v1.3 DTD. The main change is the
 371           addition of a @class attribute to every element, which enables the
 372           "extra-css" section in the skinconf to be put to good use.
 373         </p>
 374       </section>
 375       <section id="changes-12">
 376         <title>Changes between document-v11 and document-v12</title>
 377         <p>
 378           doc-v12 enhances doc-v11 by relaxing various restrictions that were
 379           found to be unnecessary.
 380         </p>
 381         <ul>
 382           <li>
 383             Links ((link|jump|fork) and inline elements (br|img|icon|acronym) are
 384             allowed inside title.
 385           </li>
 386           <li>
 387             Paragraphs (p|source|note|warning|fixme), table and figure|anchor are
 388             allowed inside li.
 389           </li>
 390           <li>
 391             Paragraphs (p|source|note|warning|fixme), lists (ol|ul|dl), table,
 392             figure|anchor are allowed inside definition lists (dd) and tables (td
 393             and dh).
 394           </li>
 395           <li>
 396             Inline content
 397             (strong|em|code|sub|sup|br|img|icon|acronym|link|jump|fork) is
 398             allowed in strong and em.
 399           </li>
 400         </ul>
 401       </section>
 402     </section>
 403   </body>
 404   <footer>
 405     <legal>This is a legal notice, so it is <strong>important</strong>.</legal>
 406   </footer>
 407 </document>