This is an automated email from the ASF dual-hosted git repository. kwin pushed a commit to branch feature/fml-to-markdown in repository https://gitbox.apache.org/repos/asf/maven-doxia-site.git
commit a2666307a58905928d7813caee2f60c0519233b7 Author: Konrad Windszus <[email protected]> AuthorDate: Tue Mar 10 11:43:10 2026 +0100 Convert FML to Markdown --- content/markdown/faq.md | 240 ++++++++++++++++++++++++------------------------ 1 file changed, 118 insertions(+), 122 deletions(-) diff --git a/content/markdown/faq.md b/content/markdown/faq.md index 35714cb..7fed60a 100644 --- a/content/markdown/faq.md +++ b/content/markdown/faq.md @@ -1,4 +1,6 @@ -<?xml version="1.0" encoding="UTF-8"?> +--- +title: Frequently Asked Questions +--- <!-- Licensed to the Apache Software Foundation (ASF) under one @@ -17,137 +19,131 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - -<faqs xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xmlns="http://maven.apache.org/FML/1.0"; - xsi:schemaLocation="http://maven.apache.org/FML/1.0 http://maven.apache.org/xsd/fml-1.0.xsd"; - title="Frequently Asked Questions"> - <part id="General"> - <faq id="How_to_handle_style_in_the_APT_markup_language"> - <question>How to handle style in the APT markup language?</question> - <answer> - <p> - APT does not support style. If you need more control you should use - <a href="references/xdoc-format.html">xdoc</a> instead. - </p> - </answer> - </faq> - <faq id="How_to_export_in_PDF"> - <question>How to export in PDF?</question> - <answer> - <p> - There are two modules available that can be used to generate pdf output: an - <a href="/doxia/doxia/doxia-modules/doxia-module-itext/">iText module</a> - that uses the - <a href="http://www.lowagie.com/iText/";>iText</a> framework, and a - <a href="/doxia/doxia/doxia-modules/doxia-module-fo/">FO</a> module, - that can be used e.g. in conjunction with - <a href="http://xmlgraphics.apache.org/fop/";>Apache FOP</a> 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. - </p> - <p> - For Maven there is a <a href="/plugins/maven-pdf-plugin/">pdf plugin</a> available. - </p> - </answer> - </faq> - <faq id="Why_XML_based_sinks_don_t_generate_nicely_formatted_documents"> - <question>Why XML based sinks don't generate nicely formatted documents?</question> - <answer> - <p> - 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 <a href="https://issues.apache.org/jira/browse/DOXIA-255";>DOXIA-255</a>). - </p> - </answer> - </faq> - <faq id="doxia-xsd"> - <question>Where are the Maven Doxia XSD schemas files?</question> - <answer> - <p> - The Doxia XSD files are located here: - </p> - - <dl> - <dt>Xdoc XSD 2.0</dt> - <dd><a href="/xsd/xdoc-2.0.xsd">https://maven.apache.org/xsd/xdoc-2.0.xsd</a></dd> - <dt>FML XSD 1.0.1</dt> - <dd><a href="/xsd/fml-1.0.1.xsd">https://maven.apache.org/xsd/fml-1.0.1.xsd</a></dd> - <dt>Book XSD 1.0</dt> - <dd><a href="/xsd/book-1.0.0.xsd">https://maven.apache.org/xsd/book-1.0.0.xsd</a></dd> - <dt>Document XSD 1.0.1</dt> - <dd><a href="/xsd/document-1.0.1.xsd">https://maven.apache.org/xsd/document-1.0.1.xsd</a></dd> - <dt>Decoration XSD 1.0</dt> - <dd><a href="/xsd/decoration-1.0.0.xsd">https://maven.apache.org/xsd/decoration-1.0.0.xsd</a></dd> - </dl> - - <p> - Your favorite IDE probably supports XSD schema's for Xdoc and FML files. You need to - specify the following: - <source><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"> +--><a id="top"></a> +# Frequently Asked Questions + +1. [How to handle style in the APT markup language?](#How_to_handle_style_in_the_APT_markup_language) +1. [How to export in PDF?](#How_to_export_in_PDF) +1. [Why XML based sinks don't generate nicely formatted documents?](#Why_XML_based_sinks_don_t_generate_nicely_formatted_documents) +1. [Where are the Maven Doxia XSD schemas files?](#doxia-xsd) +1. [How to define character entities in Doxia XML files with XSD?](#doxia-character-entities) +<dl> +<a id="How_to_handle_style_in_the_APT_markup_language"></a><dt>How to handle style in the APT markup language?</dt> +<dd> + +APT does not support style. If you need more control you should use <a href="references/xdoc-format.html">xdoc</a> instead. + +<a href="#top">[top]</a> + +*** + +</dd> +<a id="How_to_export_in_PDF"></a><dt>How to export in PDF?</dt> +<dd> + +There are two modules available that can be used to generate pdf output: an <a href="/doxia/doxia/doxia-modules/doxia-module-itext/">iText module</a> that uses the <a href="http://www.lowagie.com/iText/"; class="externalLink">iText</a> framework, and a <a href="/doxia/doxia/doxia-modules/doxia-module-fo/">FO</a> module, that can be used e.g. in conjunction with <a href="http://xmlgraphics.apache.org/fop/"; class="externalLink">Apache FOP</a> to generate a pdf. Unfortunately, the iText team [...] + +For Maven there is a <a href="/plugins/maven-pdf-plugin/">pdf plugin</a> available. + +<a href="#top">[top]</a> + +*** + +</dd> +<a id="Why_XML_based_sinks_don_t_generate_nicely_formatted_documents"></a><dt>Why XML based sinks don't generate nicely formatted documents?</dt> +<dd> + +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 <a href="https://issues.apache.org/jira/browse/DOXIA-255"; class="externalLink">DOXIA-255</a>). + +<a href="#top">[top]</a> + +*** + +</dd> +<a id="doxia-xsd"></a><dt>Where are the Maven Doxia XSD schemas files?</dt> +<dd> + +The Doxia XSD files are located here: + +<dl> + +<dt>Xdoc XSD 2.0</dt> + +<dd><a href="/xsd/xdoc-2.0.xsd">https://maven.apache.org/xsd/xdoc-2.0.xsd</a></dd> + +<dt>FML XSD 1.0.1</dt> + +<dd><a href="/xsd/fml-1.0.1.xsd">https://maven.apache.org/xsd/fml-1.0.1.xsd</a></dd> + +<dt>Book XSD 1.0</dt> + +<dd><a href="/xsd/book-1.0.0.xsd">https://maven.apache.org/xsd/book-1.0.0.xsd</a></dd> + +<dt>Document XSD 1.0.1</dt> + +<dd><a href="/xsd/document-1.0.1.xsd">https://maven.apache.org/xsd/document-1.0.1.xsd</a></dd> + +<dt>Decoration XSD 1.0</dt> + +<dd><a href="/xsd/decoration-1.0.0.xsd">https://maven.apache.org/xsd/decoration-1.0.0.xsd</a></dd> + +</dl> + +Your favorite IDE probably supports XSD schema's for Xdoc and FML files. You need to specify the following: <pre><code><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></source> - <source><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"> +</document></code></pre> <pre><code><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></source> - <source><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";> +</faqs></code></pre> <pre><code><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></source> - <source><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="..."> +</book></code></pre> <pre><code><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></source> - <source><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"> +</document></code></pre> <pre><code><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></source> - </p> - <p> - <b>Note</b>: for performance reasons, all XSDs/DTDs use a cache in ${java.io.tmpdir}. - </p> - </answer> - </faq> - <faq id="doxia-character-entities"> - <question>How to define character entities in Doxia XML files with XSD?</question> - <answer> - <p> - 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. - </p> - <p> - For instance, you could add the following in your Xdoc XML files to be similar to XHTML 1.0 Transitional dtd: - <source><!DOCTYPE document [ +</project></code></pre> + +<b>Note</b>: for performance reasons, all XSDs/DTDs use a cache in ${java.io.tmpdir}. + +<a href="#top">[top]</a> + +*** + +</dd> +<a id="doxia-character-entities"></a><dt>How to define character entities in Doxia XML files with XSD?</dt> +<dd> + +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: <pre><code><!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"> + <!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"> + <!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"> + <!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 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></source> - </p> - <p> - <b>Note</b>: if CDATA is used to specify entity, Doxia will replace & by &amp; (i.e - "<![CDATA[&iexcl;]]>" becomes "&amp;iexcl;"). - </p> - </answer> - </faq> - </part> -</faqs> +</document></code></pre> + +<b>Note</b>: if CDATA is used to specify entity, Doxia will replace & by &amp; (i.e "<![CDATA[&iexcl;]]>" becomes "&amp;iexcl;"). + +<a href="#top">[top]</a> + +</dd> +</dl> \ No newline at end of file
