Additional sectioning

The xdoc plugin 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

From version 1.10 on, the xdoc plugin allows for an optional id attribute in the section and subsection elements:

<section name="Section" id="Section1">
  <subsection name="SubSection" id="SubSection1">
  </subsection>
</section>

An anchor is constructed from each id attribute, so you can reference sections and subsections from other source documents. Note that each id attribute has to be unique within one source document.

In previous versions of the plugin, an id attribute was constructed from section/subsection names, replacing special characters by underscores. For backwards compatibility reasons, we keep this behaviour, i.e., if no id attribute is present, an anchor is constructed from the name attribute. Note that this 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 long section titles, this leads to rather cumbersome anchor names.

We recommend that you provide an id attribute if you want to reference a section or subsection.

escapeXml Tag

If you need to include the contents of another XML document in your document, you can use the <escapeXml> tag, as demonstrated below. For instance, the code:

<?xml version="1.0"?>
<!DOCTYPE document [
    <!ENTITY escapeXmlExample SYSTEM "file:xdocs/escapeXml.xml">
]>
<escapeXml>&escapeXmlExample;</escapeXml>

would produce the following output (click here to see the content of escapeXml.xml):

<example name="escapeXml">
   <text>This is an example of the escapeXml tag usage.</text>

</example>

Note that it is possible to validate the included xml file with the xdoc:validate goal even if it is not a valid xdoc document (like in the example above). You just have to provide a custom .dtd or .xsd schema file with the same base name in the same directory. Otherwise, you should use the maven.xdoc.validate.exclude property to exclude specific files from validation.

Navigation bar

You can put a navigation bar on bottom of each page by including a <navbar/> element in an xdoc's body. This element takes three optional attributes, prev, home and next:

<navbar prev="first.html" home="../index.html" next="next.html"/>

This element should appear after the last <section/> of the document. Check the bottom of this page for an example.

Custom entities

Due to a bug in Jelly, it is not possible to use custom entities directly in xdoc documents. A workaround has been implemented such that you need to embed your entities in <entity> tags. First you should declare the resource file for your entities:

<?xml version="1.0"?>
<!DOCTYPE document [
  <!ENTITY % my-entities SYSTEM "entities.ent">
  %my-entities;
]>
<document>
...

where the file entities.ent contains, eg:

<!ENTITY version '1.3.2-SNAPSHOT'>

which can then be used in your xdoc like:

<p>
  This information only applies to version <entity>&version;</entity>.
</p>

Note that xdoc files using entities in this way cannot be validated with the xdoc:validate goal (see below).

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.