Writing Documentation

As you might guess, The freebXML Registry website is generated by Maven, which uses 'xdoc' as source for documentation (there should be also OASIS docbook support, to be checked).

For the sake of user-friendlyness, our docs are writen in plain HTML and not using xdoc. A maven plugin converts the HTML to xdoc and maven:site converts it back to good looking HTML (could it be simpler!?).

So, if you are writing documentation for OMAR you can simply add/modify HTML files to doc/3.0 folders. In order to get the good looking HTML and no broken links you should observe a few rules though:

Element
Example
File Header <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<!--$Header: /cvsroot/ebxmlrr/omar/doc/3.0/developer/writingDocs.html,v 1.1 2005/08/01 08:02:28 doballve Exp $-->

...
HTML start <html>

  <head>

    <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">

    <title>PAGE_TITLE</title>

  </head>

  <body>

  ...

HTML end   ...

  </body>

</html>
Session (blue bar)     <div class="h2">

    <h2><a name="mySession">My Session Title</a></h2>

    ...

    </div>
Subsession (grey bar)     <div class="h3">

    <h3><a name="mySubsession">My Subsession Title</a></h3>

    ...

    </div>
Sub subsession (no bar)     <div class="h4">

    <h4><a name="mySubSubsession">My SubSubsession Title</a></h4>

    ...

    </div>
Table     <table cellpadding="3" cellspacing="2" border="1">

    <tr class="a">

      <td><center><b>Element</b></center></td>

      <td><center><b>Example</b></center></td>

    </tr>

    <tr class="b">

      <td>File Header</td>

      <td><code>

    </tr>

    <tr class="a">

      ...

    </tr>

    ...

    </table>
Code     <code>...</code>
Ordered Lists     <ol>

     <li>...</li>

     ...

    </ol>
Unordered Lists     <ul>

     <li>...</li>

     ...

    </ul>
Nested Lists     <ul>

     <li>

      <ul>

       <li>...</li>

       ...

      </ul>

     </li>

     ...

    </ul>
Images (w/ caption)     <p><center><a name="figure-6.2">

    <img src="../images/myImage.png" alt="My Image Alt"></a><br>

    <b>Figure 6.2 - User registration wizard</b><center></p>
Links * No spaces in link names!
Text * Use paragraphs (<p>). No <br><br>.