Frequently Asked Questions

  1. How to handle style in the APT markup language?
  2. How to export in PDF?
  3. Is it possible to create a book?
  4. Why XML based sinks don't generate nicely formatted documents?
  5. Where are the Maven Doxia XSD schemas files?
  6. How to define character entities in Doxia XML files with XSD?
How to handle style in the APT markup language?

APT does not support style. If you need more control you should use xdoc instead.

[top]


How to export in PDF?

There are two modules available that can be used to generate pdf output: an iText module that uses the iText framework, and a FO module, that can be used e.g. in conjunction with Apache FOP to generate a pdf. Unfortunately, the iText team has discontinued the XML to PDF functionalities, so probably only the fo module is going to be supported in the future.

For Maven there is a pdf plugin available.

[top]


Is it possible to create a book?

Doxia also has a fairly simple tool for writing books. It comes complete with a Maven plugin to produce PDFs, LaTeX documents and Xdoc for direct integration in your Maven site. The Doxia Book code is still limited but fully functional.

See Writing Books in Doxia for more information.

[top]


Why XML based sinks don't generate nicely formatted documents?

We decided to keep pretty printing out of the core modules. So, XML based sinks like Xdoc or XHTML are intentionally unformatted. You could always do this after the document generation or directly by creating a specialized end-user sink (see DOXIA-255).

[top]


Where are the Maven Doxia XSD schemas files?

The Doxia XSD files are located here:

Xdoc XSD 2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd
FML XSD 1.0.1
https://maven.apache.org/xsd/fml-1.0.1.xsd
Book XSD 1.0
https://maven.apache.org/xsd/book-1.0.0.xsd
Document XSD 1.0.1
https://maven.apache.org/xsd/document-1.0.1.xsd
Decoration XSD 1.0
https://maven.apache.org/xsd/decoration-1.0.0.xsd

Your favorite IDE probably supports XSD schema's for Xdoc and FML files. You need to specify the following:

<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">
  ...
</document>
<faqs xmlns="http://maven.apache.org/FML/1.0.1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/FML/1.0.1 http://maven.apache.org/xsd/fml-1.0.1.xsd">
  ...
</faqs>
<book xmlns="http://maven.apache.org/BOOK/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/BOOK/1.0.0 http://maven.apache.org/xsd/book-1.0.0.xsd">
  ...
</book>
<document xmlns="http://maven.apache.org/DOCUMENT/1.0.1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/DOCUMENT/1.0.1 http://maven.apache.org/xsd/document-1.0.1.xsd"
  outputName="...">
  ...
</document>
<project xmlns="http://maven.apache.org/DECORATION/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0 http://maven.apache.org/xsd/decoration-1.0.0.xsd">
  ...
</project>

Note: for preformance reasons, all XSDs/DTDs use a cache in ${java.io.tmpdir}.

[top]


How to define character entities in Doxia XML files with XSD?

Since it is not possible to define character entity references (like &copy;) in XSDs (unlike DTDs), each XML file should have a <!DOCTYPE> to define the character entity set.

For instance, you could add the following in your Xdoc XML files to be similar to XHTML 1.0 Transitional dtd:

<!DOCTYPE document [
  <!-- These are the entity sets for ISO Latin 1 characters for the XHTML -->
  <!ENTITY % HTMLlat1 PUBLIC "-//W3C//ENTITIES Latin 1 for XHTML//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml-lat1.ent">
  %HTMLlat1;
  <!-- These are the entity sets for special characters for the XHTML -->
  <!ENTITY % HTMLsymbol PUBLIC "-//W3C//ENTITIES Symbols for XHTML//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml-symbol.ent">
  %HTMLsymbol;
  <!-- These are the entity sets for symbol characters for the XHTML -->
  <!ENTITY % HTMLspecial PUBLIC "-//W3C//ENTITIES Special for XHTML//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml-special.ent">
  %HTMLspecial;
]>
<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">
...
</document>

Note: if CDATA is used to specify entity, Doxia will replace & by &amp; (i.e "<![CDATA[&iexcl;]]>" becomes "&amp;iexcl;").

[top]