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 V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd">
  19 <document>
  20   <header>
  21     <title>The Apache Forrest xdocs document-v1.3 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-v13.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-v13.dtd</code>
  31       (See the <link href="#changes">DTD changes</link> 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       <link href="ext:dtd-docs">DTD reference documentation</link>.
  39 -->
  40       <link href="http://forrest.apache.org/docs/dtd-docs.html">DTD reference documentation</link>.
  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;link href="faq.html"&gt;</code></dt>
  86             <dd>Use this to
  87               <link href="faq.html" title="Example of a document via link">link</link>
  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;link href="#section"&gt;</code></dt>
  92             <dd>Use this to
  93               <link href="#section" title="Example of a document via local anchor">link</link>
  94               to the named anchor in the current document.
  95             </dd>
  96
  97             <dt><code>&lt;link href="faq.html#forrest"&gt;</code></dt>
  98             <dd>Use this to
  99               <link href="faq.html#forrest" title="Example of a document via link and anchor">link</link>
 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
 104             <dt><code>&lt;jump href="faq.html"&gt;</code></dt>
 105             <dd>Use this to
 106               <jump href="faq.html" title="Example of a document via jump">jump</jump>
 107               to another document and optionally go to a named
 108               <jump href="faq.html#forrest" title="Example of a document via jump to anchor">anchor</jump>
 109               within that document. This will open the new document in the same
 110               browser window. So what is the difference between link and jump?
 111               The jump behaves differently, in that it will replace any frames
 112               in the current window.
 113               This is the equivalent of
 114               <code>&lt;a ... target="_top"&gt;</code>
 115             </dd>
 116
 117             <dt><code>&lt;fork href="faq.html"&gt;</code></dt>
 118             <dd>Use this to
 119               <fork href="faq.html" title="Example of a document via fork">fork</fork>
 120               your webbrowser to another document. This will open the document
 121               in a new, unnamed browser window.
 122               This is the equivalent of
 123               <code>&lt;a ... target="_blank"&gt;</code>
 124             </dd>
 125         </dl></li>
 126
 127         <li>Oh, by the way, a definition list <code>&lt;dl&gt;</code> was used inside
 128           the previous list item. We could put another
 129           <ul>
 130             <li>unordered list</li>
 131             <li>inside the list item</li>
 132           </ul>
 133           <table>
 134             <caption>A sample nested table</caption>
 135             <tr><td>Or even tables.. </td><td>
 136                 <table><tr><td>inside tables..</td></tr></table>
 137             </td></tr>
 138             <tr><td>or inside lists, but I believe this liberty gets quickly quite
 139                 hairy as you see.</td></tr>
 140           </table>
 141         </li>
 142       </ul>
 143       <p>So far for the in-line elements, let's look at some paragraph-level
 144         elements.</p>
 145       <fixme author="SN">The <code>&lt;fixme&gt;</code> element is used for stuff
 146         which still needs work. Mind the <code>author</code> attribute!</fixme>
 147       <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
 148         express himself clearly using normal sentences ;-)</note>
 149       <warning>Sleep deprivation can be the result of being involved in an open
 150         source project. (a.k.a. the <code>&lt;warning&gt;</code> element).
 151       </warning>
 152       <note label="Important">If you want your own labels for notes and
 153         warnings, specify them using the <code>label</code> attribute.
 154       </note>
 155       <p>Apart from unordered lists, we have ordered lists too, of course.</p>
 156       <ol>
 157         <li>Item 1</li>
 158         <li>Item 2</li>
 159         <li>This should be 3 if my math is still OK.</li>
 160       </ol>
 161       </section>
 162
 163       <section id="presentations">
 164         <title>Various presentation formats</title>
 165
 166         <p>This sample document, written in document-v13 XML can be presented
 167         via Forrest in a number of different formats. The links in the
 168         following list show this document in each of the currently available
 169         formats.</p>
 170
 171         <p>Each of the formats can be made available as a link near the top of
 172         the page. Actual placement of those links depends on the skin
 173         currently in use. Those links are enabled in the skinconf.xml via the
 174         &#60;disable-XXX-link&#62; elements in the skinconf.xml</p>
 175
 176         <table>
 177           <tr>
 178             <th>Presentation Format</th>
 179
 180             <th>Description</th>
 181
 182             <th>skinconf.xml Element</th>
 183           </tr>
 184
 185           <tr>
 186             <td><link href="document-v13.html">HTML</link></td>
 187
 188             <td>This document in HTML format. </td>
 189
 190             <td>Always generated by default. Cannot be turned off.</td>
 191           </tr>
 192
 193           <tr>
 194             <td><link href="document-v13.xml">XML</link></td>
 195
 196             <td>This document in its raw XML format.</td>
 197
 198             <td>&#60;disable-xml-link&#62;. By default, set to true, meaning
 199             that this link will not be shown.</td>
 200           </tr>
 201
 202           <tr>
 203             <td><link href="document-v13.pdf">PDF</link></td>
 204
 205             <td>This document as Adobe PDF</td>
 206
 207             <td>&#60;disable-pdf-link&#62;. By default, set to false, meaning
 208             that this link will be shown.</td>
 209           </tr>
 210
 211           <tr>
 212             <td>Text</td>
 213
 214             <td><p>This document as straight text.</p>
 215             <p>For additional information see the Forrest text-output
 216             plugin.</p></td>
 217
 218             <td>&#60;disable-txt-link&#62;. By default, set to true, meaning
 219             that this link will not be shown.</td>
 220           </tr>
 221
 222           <tr>
 223             <td>POD</td>
 224
 225             <td><p>This document as Perl POD (Plain Old Documentation). Text
 226             with minimal formatting directives. If on a *nix system with perl
 227             installed, see &#34;man perlpod&#34;.</p>
 228             <p>For additional information see the Forrest pod-output
 229             plugin.</p></td>
 230
 231             <td>&#60;disable-pod-link&#62;. By default, set to true, meaning
 232             that this link will not be shown.</td>
 233           </tr>
 234         </table>
 235       </section>
 236       <section id="section">
 237         <title>Using sections</title>
 238         <p>You can use sections to put some structure in your document. For some
 239           strange historical reason, the section title is an attribute of the
 240           <code>&lt;section&gt;</code> element.</p>
 241       </section>
 242       <section id="sub-section">
 243         <title>Sections, the sequel</title>
 244         <p>Just some second section.</p>
 245         <section id="sub-sub-section">
 246           <title>Section 2.1</title>
 247           <p>Which contains a subsection (2.1).</p>
 248         </section>
 249       </section>
 250
 251       <section id="source">
 252         <title>Showing preformatted source code</title>
 253         <p>Enough about these sections. Let's have a look at more interesting
 254           elements, <code>&lt;source&gt;</code> for instance:</p>
 255         <source>
 256 // This example is from the book _Java in a Nutshell_ by David Flanagan.
 257 // Written by David Flanagan.  Copyright (c) 1996 O'Reilly &amp; Associates.
 258 // You may study, use, modify, and distribute this example for any purpose.
 259 // This example is provided WITHOUT WARRANTY either expressed or implied.
 260
 261 import java.applet.*;    // Don't forget these import statements!
 262 import java.awt.*;
 263
 264 public class FirstApplet extends Applet {
 265     // This method displays the applet.
 266     // The Graphics class is how you do all drawing in Java.
 267     public void paint(Graphics g) {
 268         g.drawString("Hello World", 25, 50);
 269     }
 270 }</source>
 271         <p>CDATA sections are used within
 272           <code>&lt;source&gt;</code> elements so that you can write pointy
 273            brackets without needing to escape them with messy
 274           <code>&amp;lt;</code> entities ...
 275         </p>
 276         <source><![CDATA[
 277 <pointy>
 278   easy
 279 </pointy>
 280 ]]></source>
 281         <p>Please take care to still use a sensible line-length within your
 282           source elements.</p>
 283       </section>
 284
 285       <section id="table">
 286         <title>Using tables</title>
 287         <p>And now for a table:</p>
 288         <table>
 289           <caption>Table caption</caption>
 290           <tr>
 291             <th>heading cell 1</th>
 292             <th>heading cell 2</th>
 293             <th>heading cell 3</th>
 294           </tr>
 295           <tr>
 296             <td>data cell</td>
 297             <td colspan="2">this data cell spans two columns</td>
 298           </tr>
 299           <tr>
 300             <td>
 301               Tables can be nested:
 302             </td>
 303             <td>
 304               <table>
 305                 <tr>
 306                   <th>column 1</th>
 307                   <th>column 2</th>
 308                 </tr>
 309                 <tr>
 310                   <td>cell A</td>
 311                   <td>cell B</td>
 312                 </tr>
 313               </table>
 314             </td>
 315             <td>
 316               <ul><li>and can include most other elements</li><li>such as lists</li></ul>
 317             </td>
 318           </tr>
 319         </table>
 320       </section>
 321
 322       <anchor id="second-figure-anchor"/>
 323       <section id="figure">
 324         <title>Using figures</title>
 325         <p>And a <code>&lt;figure&gt;</code> to end all of this.
 326           Note that this can also be implemented with an
 327           <code>&lt;img&gt;</code> element.
 328         </p>
 329         <figure src="../images/project.png" alt="The fine Forrest logo" width="220" height="65"/>
 330       </section>
 331     </section>
 332
 333     <section id="changes">
 334       <title>DTD changes</title>
 335       <p>See the generated
 336 <!-- FOR-321 workaround
 337       <link href="ext:dtd-docs">DTD reference documentation</link>.
 338 -->
 339       <link href="http://forrest.apache.org/docs/dtd-docs.html">DTD reference documentation</link>.
 340       </p>
 341       <section id="changes-13">
 342         <title>Changes since document-v12</title>
 343         <p>
 344           All v1.2 docs will work fine as v1.3 DTD. The main change is the
 345           addition of a @class attribute to every element, which enables the
 346           "extra-css" section in the skinconf to be put to good use.
 347         </p>
 348       </section>
 349       <section id="changes-12">
 350         <title>Changes since document-v11</title>
 351         <p>
 352           doc-v12 enhances doc-v11 by relaxing various restrictions that were
 353           found to be unnecessary.
 354         </p>
 355         <ul>
 356           <li>
 357             Links ((link|jump|fork) and inline elements (br|img|icon|acronym) are
 358             allowed inside title.
 359           </li>
 360           <li>
 361             Paragraphs (p|source|note|warning|fixme), table and figure|anchor are
 362             allowed inside li.
 363           </li>
 364           <li>
 365             Paragraphs (p|source|note|warning|fixme), lists (ol|ul|dl), table,
 366             figure|anchor are allowed inside definition lists (dd) and tables (td
 367             and dh).
 368           </li>
 369           <li>
 370             Inline content
 371             (strong|em|code|sub|sup|br|img|icon|acronym|link|jump|fork) is
 372             allowed in strong and em.
 373           </li>
 374         </ul>
 375       </section>
 376     </section>
 377   </body>
 378   <footer>
 379     <legal>This is a legal notice, so it is <strong>important</strong>.</legal>
 380   </footer>
 381 </document>