The XDoc format

Overview

An 'xdoc' is an XML document conforming to a small and simple set of tags. Xdoc was the primary documentation format in Maven 1 , Maven 2 largely replaced this by Apt , but xdoc is still supported.

Historically, the xdoc format can be traced back to the Anakia format, as once used by the Apache Jakarta project.

The Maven 1 Xdoc plugin introduced a few additions to the Anakia format, they are highlighted in the plugin documentation.

The XDoc format

The following is a sample XDoc document: 

<document>

  <properties>
    <title>Page Title</title>
    <author email="user@company.com">John Doe</author>
  </properties>

  <!-- Optional HEAD element, which is copied as is into the XHTML <head> element -->
  <head>
    <meta ... />
  </head>

  <body>

    <!-- The body of the document contains a number of sections -->
    <section name="section 1">

      <!-- Within sections, any XHTML can be used -->
      <p>Hi!</p>

      <!-- in addition to XHTML, any number of subsections can be within a section -->
      <subsection name="subsection 1">
        <p>Subsection!</p>
      </subsection>

    </section>

    <section name="other section">

      <!-- You can also include preformatted source blocks in the document -->
      <source>
code line 1
code line 2
      </source>

    </section>

  </body>

</document>

Additional sectioning

Doxia will produce <h2> and <h3> headings for <section> and <subsection> elements, respectively. It is therefore perfectly valid to put some sub-headings (<h4>, <h5>, <h6>) inside a subsection. For instance, 

<h4>A subsubsection</h4>

will produce:

A subsubsection

Referencing sections and subsections

The core doxia modules do not construct anchors from section/subsection names. If you want to reference a section, you have to provide an explicit anchor: 

<a name="Section1"/>
<section name="Section">

  <a name="SubSection1"/>
  <subsection name="SubSection">
  </subsection>

</section>

Note that this differs from previous behavior, where anchors were constructed from section/subsection names, replacing special characters by underscores. This behavior presents two shortcomings:

  • If two sections or subsections have identical names (within one source document), you will get an ambiguity when referencing them. Also the resulting html document will not be valid XHTML. For other output formats (eg pdf), it might even be impossible to generate the target document.
  • For long section titles, this leads to rather cumbersome anchor names.

If automatic anchor generation is desired for a particular output format, it should be implemented / overridden by the corresponding low-level Sink.

Validation

Doxia is currently not able to validate your xdoc files as no schema or DTD exists yet (however this is planned before the 1.0 release). It is therefore necessary to check manually whether your source files are valid xdocs, this should ensure that the generated html files are valid XHTML1-transitional .

Here is a list of common mistakes to be aware of:

Don't nest block level elements

Wrong:

<p>
  Here's a list:
  <ul>
    <li>item 1</li>
    <li>item 2</li>
  </ul>
  of things to do.
</p>

Correct:

<p>
  Here's a list:
</p>
<ul>
  <li>item 1</li>
  <li>item 2</li>
</ul>
<p>
  of things to do.
</p>

Typical block level elements are list elements, <table>, <source>, <div>, <p> and <pre>.

Put inline elements inside block level elements

Wrong:

<section name="Downloads">
  <a href="downloads.html">Downloads</a>
</section>

Correct:

<section name="Downloads">
  <p>
    <a href="downloads.html">Downloads</a>
  </p>
</section>

Typical inline elements are <a>, <strong>, <code>, <font>, <br> and <img>.

Right order of elements in <properties>

The <title> element has to come before <author>.

Dont put <source> inside paragraphs

Wrong:

<p>
  The following command executes the program:
  <source>java -jar CoolApp.jar</source>
</p>

Correct:

<p>
  The following command executes the program:
</p>
<source>java -jar CoolApp.jar</source>

However, you may put <source> elements inside list items or table rows.