The Maven 1 Xdoc plugin introduced a few additions to the Anakia format, they are highlighted in the plugin documentation.
The full documentation is available here.
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="email@example.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>
<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>
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,
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 automatic anchor generation is desired for a particular output format, it should be implemented / overridden by the corresponding low-level Sink.
Doxia is able to validate your xdoc files as described here.
Here is a list of common mistakes to be aware of:
<p> Here's a list: <ul> <li>item 1</li> <li>item 2</li> </ul> of things to do. </p>
<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>.
<section name="Downloads"> <a href="downloads.html">Downloads</a> </section>
<section name="Downloads"> <p> <a href="downloads.html">Downloads</a> </p> </section>
Typical inline elements are <a>, <strong>, <code>, <font>, <br> and <img>.
<p> The following command executes the program: <source>java -jar CoolApp.jar</source> </p>
<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.