Built by Maven

Content

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

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

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

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