The XDoc format

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 then moved to Velocity.

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

The XDoc xsd

The full documentation is available in the annotated xdoc-2.0.xsd schema.

XDoc Sample

The following is a sample XDoc document:

<?xml version="1.0" encoding="UTF-8"?>
<document xmlns="http://maven.apache.org/XDOC/2.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">

  <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>

The <source> tag

<source> tags are special. Anything within this tag is rendered within a "verbatim box" as pre-formatted text. If you are embedding other XML/XHTML markup within the source tags, then you need to place a CDATA section within the source section. Example:

<source><![CDATA[ content here <a href="">foo</a>]]></source>

Additional sectioning

Since Doxia 2.0, <section> and <subsection> elements produce <h1> and <h2> headings respectively; before 2.0 they started at <h2>. It is therefore perfectly valid to put some sub-headings (<h3> to <h6>) inside a subsection. For instance,

<h3>A subsubsection</h3>

will produce:

A subsubsection

Referencing sections and subsections

When a document is rendered as part of a Maven site, Doxia creates an anchor for every section and subsection title by itself, deriving the name from the title text and making it unique within the document. A title that is reworded therefore gets a different anchor, which silently breaks links pointing at it.

For a reference that has to survive editing, name the anchor yourself. Either provide an explicit anchor:

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

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

</section>

or use an id attribute for section and subsections (note that id's have to be unique within one xdoc source document):

<section name="Section" id="Section1">

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

</section>

An anchor you write yourself always wins: Doxia only generates one where the title does not already carry it. Two sections sharing a title no longer collide, because generated names are numbered to keep them unique, and Doxia warns when the same anchor name is used more than once in a document.

Validation

Doxia is able to validate your xdoc files as described here.

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>.

Don't 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.