This is an automated email from the ASF dual-hosted git repository. kwin pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/maven-doxia-site.git
commit 72cd5cf20e09925ecddcfcc4694383fc19cd2b32 Author: Konrad Windszus <[email protected]> AuthorDate: Tue Mar 10 11:33:53 2026 +0100 Convert XDoc to Markdown (with doxia-converter) --- content/markdown/overview.md | 204 +++++++------------- content/markdown/references/fml-format.md | 70 +++---- content/markdown/references/index.md | 279 ++++++--------------------- content/markdown/references/xdoc-format.md | 296 +++++++++++------------------ content/markdown/scm.md | 89 +++------ 5 files changed, 285 insertions(+), 653 deletions(-) diff --git a/content/markdown/overview.md b/content/markdown/overview.md index 71c494e..94a6dc9 100644 --- a/content/markdown/overview.md +++ b/content/markdown/overview.md @@ -1,4 +1,9 @@ -<?xml version="1.0" encoding="UTF-8"?> +--- +title: Overview Of The Doxia Framework +author: + - Vincent Siveton +date: 2009-03-02 +--- <!-- Licensed to the Apache Software Foundation (ASF) under one @@ -19,139 +24,64 @@ specific language governing permissions and limitations under the License. --> -<document> - <properties> - <title>Overview Of The Doxia Framework</title> - <author>Vincent Siveton</author> - <date>2009-03-02</date> - </properties> - <body> - <section name="Overview Of The Doxia Framework"> - <p> - The following figure represents the main components of the Doxia Framework. - </p> - <p> - <img src="images/architecture.png" width="574" height="439" border="0" usemap="#Doxia_Framework" alt="Doxia Framework"/> - <map id="Doxia_Framework" name="Doxia_Framework"> - <area shape="rect" coords="87,45,172,99" alt="Sink API" - href="http://maven.apache.org/doxia/doxia/doxia-sink-api/"; /> - <area shape="rect" coords="66,170,193,232" alt="Core" - href="http://maven.apache.org/doxia/doxia/doxia-core/"; /> - <area shape="rect" coords="26,361,69,403" alt="APT Module" - href="http://maven.apache.org/doxia/doxia/doxia-modules/doxia-module-apt/"; /> - <area shape="rect" coords="78,361,119,403" alt="XDoc Module" - href="http://maven.apache.org/doxia/doxia/doxia-modules/doxia-module-xdoc/"; /> - <area shape="rect" coords="130,361,172,404" alt="FML Module" - href="http://maven.apache.org/doxia/doxia/doxia-modules/doxia-module-fml/"; /> - <area shape="rect" coords="14,311,235,428" alt="Modules" - href="http://maven.apache.org/doxia/doxia/doxia-modules/"; /> - <area shape="rect" coords="0,0,260,438" alt="Doxia" - href="http://maven.apache.org/doxia/doxia/"; /> - <area shape="rect" coords="297,157,422,200" alt="Site Renderer" - href="http://maven.apache.org/doxia/doxia-sitetools/doxia-site-renderer/"; /> - <area shape="rect" coords="455,157,557,200" alt="Decoration Model" - href="http://maven.apache.org/doxia/doxia-sitetools/doxia-decoration-model/"; /> - <area shape="rect" coords="298,209,421,251" alt="Doc Renderer" - href="http://maven.apache.org/doxia/doxia-sitetools/doxia-doc-renderer/"; /> - <area shape="rect" coords="286,114,575,262" alt="Site Tools" - href="http://maven.apache.org/doxia/doxia-sitetools/"; /> - <area shape="rect" coords="304,362,403,404" alt="Converter" - href="http://maven.apache.org/doxia/doxia-tools/doxia-converter/"; /> - <area shape="rect" coords="424,362,517,404" alt="Linkcheck" - href="http://maven.apache.org/doxia/doxia-tools/doxia-linkcheck/"; /> - <area shape="rect" coords="285,310,537,426" alt="Tools" - href="http://maven.apache.org/doxia/doxia-tools/"; /> - </map> - </p> - <p> - <b>Note</b>: Just like Maven, Doxia uses - <a class="externalLink" href="https://codehaus-plexus.github.io/";>Plexus</a> extensively. - </p> - - <subsection name="Sink API"> - <p> - The <i>Sink</i> interface is a generic markup language interface. It contains - several methods that encapsulate common text syntax. A start tag is denoted by - <i>xxxx()</i> method and a end of tag by <i>xxxx_()</i> method. - </p> - <p> - For instance, you could do things like: - </p> - <source>sink.paragraph(); -sink.text( "my text" ); -sink.paragraph_(); </source> - <p> - similar to this HTML markup: - </p> - <source><p>my text</p></source> - <p>To find out more about the Sink API, you could read the Javadoc - <a class="externalLink" - href="http://maven.apache.org/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html";>here</a>. - </p> - </subsection> - - <subsection name="Doxia Core"> - <p> - The <i>Core</i> is the API to parse a source and populate it in a <i>Sink</i> - object. The <i>Parser</i> interface contains only one method: - </p> - <source>void parse( Reader source, Sink sink ) - throws ParseException; </source> - <p> - The <i>ParseException</i> class has the responsibility to catch all parsing - exceptions. It provides an helper method, <i>getLineNumber()</i>, which helps to - find where an error occurred. - </p> - <p> - The <i>AbstractParser</i> class is an abstract implementation of the - <i>Parser</i>. It provides a macro mechanism to give dynamic functionalities for - the parsing. For more information on macros, read the <a - href="./macros/index.html">Doxia Macro Guide</a>. - </p> - <p> - Finally, the <i>SiteModule</i> interface is the last part of the puzzle. It - provides main definitions of a given Doxia module and it is used by the - <i>doxia-site-renderer</i> site tools. - </p> - </subsection> - - <subsection name="Doxia Modules"> - <p> - A Doxia module is an implementation of a given markup language like APT or Xdoc. - Each module should implement these interfaces: - </p> - <ul> - <li><i>Parser</i> interface, more specifically the <i>AbstractParser</i> class</li> - <li><i>SiteModule</i> interface</li> - </ul> - <p> - Several modules provide also a <i>Sink</i> implementation to handle a specific - output markup language. - </p> - <p> - For more information on modules, read the <a href="./modules/index.html">Doxia - Module Guide</a>. - </p> - </subsection> - - <subsection name="Doxia Site Tools"> - <p> - The <i>Site Tools</i> are a collection of tools to renderer an output. The main - tool used by Maven, specifically the - <a class="externalLink" href="http://maven.apache.org/plugins/maven-site-plugin/";>Maven Site Plugin</a>, - is the <i>doxia-site-renderer</i> which renders in HTML any - documents written with supported markup syntax. It uses - <a class="externalLink" href="http://velocity.apache.org/";>Velocity templates</a> - to customize the renderer and the <i>site-decoration-model</i> tool to decorate the - renderer. - This component describes the layout of the site defined in the <i>site.xml</i> - file. - </p> - <p> - The <i>doxia-doc-renderer</i> tool is used to renderer any document in another - document. - </p> - </subsection> - </section> - </body> -</document> +# Overview Of The Doxia Framework + +The following figure represents the main components of the Doxia Framework. + + + +**Note**: Just like Maven, Doxia uses [Plexus](https://codehaus-plexus.github.io/) extensively. + +## Sink API + +The _Sink_ interface is a generic markup language interface. It contains several methods that encapsulate common text syntax. A start tag is denoted by _xxxx\(\)_ method and a end of tag by _xxxx\_\(\)_ method. + +For instance, you could do things like: + +```unknown +sink.paragraph(); +sink.text( "my text" ); +sink.paragraph_(); +``` + +similar to this HTML markup: + +```unknown +<p>my text</p> +``` + +To find out more about the Sink API, you could read the Javadoc [here](http://maven.apache.org/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html). + +## Doxia Core + +The _Core_ is the API to parse a source and populate it in a _Sink_ object. The _Parser_ interface contains only one method: + +```unknown +void parse( Reader source, Sink sink ) + throws ParseException; +``` + +The _ParseException_ class has the responsibility to catch all parsing exceptions. It provides an helper method, _getLineNumber\(\)_, which helps to find where an error occurred. + +The _AbstractParser_ class is an abstract implementation of the _Parser_. It provides a macro mechanism to give dynamic functionalities for the parsing. For more information on macros, read the [Doxia Macro Guide](./macros/index.html). + +Finally, the _SiteModule_ interface is the last part of the puzzle. It provides main definitions of a given Doxia module and it is used by the _doxia-site-renderer_ site tools. + +## Doxia Modules + +A Doxia module is an implementation of a given markup language like APT or Xdoc. Each module should implement these interfaces: + +- _Parser_ interface, more specifically the _AbstractParser_ class + +- _SiteModule_ interface + +Several modules provide also a _Sink_ implementation to handle a specific output markup language. + +For more information on modules, read the [Doxia Module Guide](./modules/index.html). + +## Doxia Site Tools + +The _Site Tools_ are a collection of tools to renderer an output. The main tool used by Maven, specifically the [Maven Site Plugin](http://maven.apache.org/plugins/maven-site-plugin/), is the _doxia-site-renderer_ which renders in HTML any documents written with supported markup syntax. It uses [Velocity templates](http://velocity.apache.org/) to customize the renderer and the _site-decoration-model_ tool to decorate the renderer. This component describes the layout of the site defined i [...] + +The _doxia-doc-renderer_ tool is used to renderer any document in another document. + diff --git a/content/markdown/references/fml-format.md b/content/markdown/references/fml-format.md index db737fd..23e75a2 100644 --- a/content/markdown/references/fml-format.md +++ b/content/markdown/references/fml-format.md @@ -1,4 +1,8 @@ -<?xml version="1.0" encoding="UTF-8"?> +--- +title: The FML (FAQ Markup Language) format +author: + - Lukas Theussl +--- <!-- Licensed to the Apache Software Foundation (ASF) under one @@ -19,40 +23,22 @@ specific language governing permissions and limitations under the License. --> -<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>The FML (FAQ Markup Language) format</title> - <author email="ltheussl_AT_apache_DOT_org">Lukas Theussl</author> - </properties> - - <body> - <section name="The FML format"> - <subsection name="Overview"> - <p> - An 'fml' (FAQ Markup Language) is an XML document conforming to a small and simple set of tags. - The format was first used in the <a href="http://maven.apache.org/maven-1.x/";>Maven 1</a>, - version of the <a href="http://maven.apache.org/maven-1.x/plugins/faq/";>FAQ plugin</a>. - </p> - </subsection> - - <subsection name="The FML format"> - <p> - Below the root element <code>faqs</code> there are one or more <code>part</code> elements. - Each <code>part</code> element has a <code>title</code> and contains one or more <code>faq</code> elements. - Each <code>faq</code> element has a <code>question</code> and an <code>answer</code> element. - The contents of <code>title</code>, <code>question</code> and <code>answer</code> are parsed with the <a href="xdoc-format.html">XDoc parser</a>. - The full documentation is available at <a href="../doxia/doxia-modules/doxia-module-fml/xsddoc/index.html">here</a>. - </p> - </subsection> - - <subsection name="FML Sample"> - <p> - The following is a sample FML document: - </p> - <source><, version of the [FAQ plugin](http://maven.apache.org/maven-1.x/plugins/faq/). + +## The FML format + +Below the root element `faqs` there are one or more `part` elements. Each `part` element has a `title` and contains one or more `faq` elements. Each `faq` element has a `question` and an `answer` element. The contents of `title`, `question` and `answer` are parsed with the [XDoc parser](xdoc-format.html). The full documentation is available at [here](../doxia/doxia-modules/doxia-module-fml/xsddoc/index.html). + +## FML Sample + +The following is a sample FML document: + +```unknown +<?xml version="1.0" encoding="UTF-8"?> <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"; @@ -101,17 +87,9 @@ under the License. </part> </faqs> -]]></source> +``` - </subsection> - </section> +# Validation - <section name="Validation"> - <p> - Doxia is able to validate your fml files as described - <a href="../doxia/doxia-modules/doxia-module-fml/using-fml-xsd.html">here</a>. - </p> - </section> +Doxia is able to validate your fml files as described [here](../doxia/doxia-modules/doxia-module-fml/using-fml-xsd.html). - </body> -</document> diff --git a/content/markdown/references/index.md b/content/markdown/references/index.md index 8dd961a..66bd955 100644 --- a/content/markdown/references/index.md +++ b/content/markdown/references/index.md @@ -1,4 +1,9 @@ -<?xml version="1.0" encoding="UTF-8"?> +--- +title: Doxia Markup Languages References +author: + - Lukas Theussl + - Vincent Siveton +--- <!-- Licensed to the Apache Software Foundation (ASF) under one @@ -19,168 +24,35 @@ specific language governing permissions and limitations under the License. --> -<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>Doxia Markup Languages References</title> - <author email="ltheussl_AT_apache_DOT_org">Lukas Theussl</author> - <author email="vsiveton_AT_apache_DOT_org">Vincent Siveton</author> - </properties> - - <body> - - <section name="Doxia Markup Languages References"> - <p> - The following table gives an overview of the markup languages currently - supported by Doxia: - </p> - <ul> - <li>if a <i>Parser</i> is available for a given format, it - means that you can write your documentation in this language and Doxia - can generate output from it,</li> - <li>if a <i>Sink</i> is available, it means you can - generate output in this format.</li> - </ul> - - <p> - The source directory is the directory under which Maven expects source - documents in this format (e.g. <code>src/site/apt/</code> for Apt), the - file extension is the default file extension, and the parser id is gives the - unique identifier that is used by plexus to lookup the corresponding - component. - </p> - - <table border="0"> - <tr> - <th>Format</th> - <th>Short description</th> - <th align="center">Parser<br/>(input)</th> - <th align="center">Sink<br/>(output)</th> - <th>Source Directory</th> - <th>File Extension</th> - <th>Doxia Module</th> - <th>Parser Id</th> - </tr> - - <tr> - <td><a href="./apt-format.html">Apt</a></td> - <td>Almost Plain Text</td> - <td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/></td> - <td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/></td> - <td><code>apt</code></td> - <td><code>apt</code></td> - <td><a href="../doxia/doxia-modules/doxia-module-apt/"><code>doxia-module-apt</code></a></td> - <td><code>apt</code></td> - </tr> - - <tr> - <td><a href="https://asciidoctor.org/";>AsciiDoc</a></td> - <td><a href="https://docs.asciidoctor.org/maven-tools/latest/site-integration/converter-module-setup-and-configuration/";>Asciidoctor Converter Doxia Module</a></td> - <td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/></td> - <td align="center"><img src="../images/icon_error_sml.gif" alt="No"/></td> - <td><code>asciidoc</code></td> - <td><code>adoc</code>, <code>asciidoc</code></td> - <td><a href="https://github.com/asciidoctor/asciidoctor-maven-plugin#maven-site-integration";><code>asciidoctor-converter-doxia-module</code></a></td> - <td><code>asciidoc</code></td> - </tr> - - <tr> - <td><a href="https://asciidoctor.org/";>AsciiDoc</a></td> - <td><a href="https://docs.asciidoctor.org/maven-tools/latest/site-integration/parser-module-setup-and-configuration/";>Asciidoctor Parser Doxia Module</a></td> - <td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/></td> - <td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/></td> - <td><code>asciidoc</code></td> - <td><code>adoc</code>, <code>asciidoc</code></td> - <td><a href="https://github.com/asciidoctor/asciidoctor-maven-plugin#maven-site-integration";><code>asciidoctor-parser-doxia-module</code></a></td> - <td><code>asciidoc</code></td> - </tr> - - <tr> - <td><a href="../modules/index.html#Confluence">Confluence</a></td> - <td>Confluence Enterprise Wiki</td> - <td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/></td> - <td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/><sup>*</sup></td> - <td><code>confluence</code></td> - <td><code>confluence</code></td> - <td><a href="../doxia/doxia-modules/doxia-module-confluence/"><code>doxia-module-confluence</code></a></td> - <td><code>confluence</code></td> - </tr> - - <tr> - <td><a href="../modules/index.html#Simplified_DocBook">Simplified DocBook</a></td> - <td>Simplified DocBook XML Standard</td> - <td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/></td> - <td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/></td> - <td><code>docbook</code></td> - <td><code>xml</code></td> - <td><a href="../doxia/doxia-modules/doxia-module-docbook-simple/"><code>doxia-module-docbook-simple</code></a></td> - <td><code>docbook</code></td> - </tr> - - <tr> - <td><a href="./fml-format.html">FML</a></td> - <td>FAQ Markup Language</td> - <td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/></td> - <td align="center"><img src="../images/icon_error_sml.gif" alt="No"/></td> - <td><code>fml</code></td> - <td><code>fml</code></td> - <td><a href="../doxia/doxia-modules/doxia-module-fml/"><code>doxia-module-fml</code></a></td> - <td><code>fml</code></td> - </tr> - - <tr> - <td><a href="../modules/index.html#Markdown">Markdown</a><sup>**</sup></td> - <td>Markdown markup language</td> - <td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/></td> - <td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/><sup>****</sup></td> - <td><code>markdown</code></td> - <td><code>md</code>, <code>markdown</code><sup>***</sup></td> - <td><a href="../doxia/doxia-modules/doxia-module-markdown/"><code>doxia-module-markdown</code></a></td> - <td><code>markdown</code></td> - </tr> - - <tr> - <td><a href="../modules/index.html#TWiki">TWiki</a><sup>*</sup></td> - <td>TWiki Structured Wiki</td> - <td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/></td> - <td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/></td> - <td><code>twiki</code></td> - <td><code>twiki</code></td> - <td><a href="../doxia/doxia-modules/doxia-module-twiki/"><code>doxia-module-twiki</code></a></td> - <td><code>twiki</code></td> - </tr> - - <tr> - <td><a href="./xdoc-format.html">Xdoc</a></td> - <td>XML Documentation Format</td> - <td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/></td> - <td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/></td> - <td><code>xdoc</code></td> - <td><code>xml</code></td> - <td><a href="../doxia/doxia-modules/doxia-module-xdoc/"><code>doxia-module-xdoc</code></a></td> - <td><code>xdoc</code></td> - </tr> - - <tr> - <td><a href="../modules/index.html#XHTML">XHTML</a></td> - <td>Extensible Hypertext Markup Language</td> - <td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/></td> - <td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/></td> - <td><code>xhtml</code></td> - <td><code>xhtml</code></td> - <td><a href="../doxia/doxia-modules/doxia-module-xhtml/"><code>doxia-module-xhtml</code></a></td> - <td><code>xhtml</code></td> - </tr> - </table> - - <p> - Note some modules are not included per default with the site plugin. - Have a look at the available modules here: <a href="https://repo.maven.apache.org/maven2/org/apache/maven/doxia/";>https://repo.maven.apache.org/maven2/org/apache/maven/doxia/</a>. - <br/> - If you need to add module for the maven site plugin simply add it as a dependency of the plugin - <source><|Almost Plain Text|||`apt`|`apt`|[`doxia-module-apt`](../doxia/doxia-modules/doxia-module-apt/)|`apt`| +|[AsciiDoc](https://asciidoctor.org/)|[Asciidoctor Converter Doxia Module](https://docs.asciidoctor.org/maven-tools/latest/site-integration/converter-module-setup-and-configuration/)|||`asciidoc`|`adoc`, `asciidoc`|[`asciidoctor-converter-doxia-module`](https://github.com/asciidoctor/asciidoctor-maven-plugin#maven-site-integration)|`asciidoc`| +|[AsciiDoc](https://asciidoctor.org/)|[Asciidoctor Parser Doxia Module](https://docs.asciidoctor.org/maven-tools/latest/site-integration/parser-module-setup-and-configuration/)|||`asciidoc`|`adoc`, `asciidoc`|[`asciidoctor-parser-doxia-module`](https://github.com/asciidoctor/asciidoctor-maven-plugin#maven-site-integration)|`asciidoc`| +|[Confluence](../modules/index.html#Confluence)|Confluence Enterprise Wiki||<sup>*</sup>|`confluence`|`confluence`|[`doxia-module-confluence`](../doxia/doxia-modules/doxia-module-confluence/)|`confluence`| +|[Simplified DocBook](../modules/index.html#Simplified_DocBook)|Simplified DocBook XML Standard|||`docbook`|`xml`|[`doxia-module-docbook-simple`](../doxia/doxia-modules/doxia-module-docbook-simple/)|`docbook`| +|[FML](./fml-format.html)|FAQ Markup Language|||`fml`|`fml`|[`doxia-module-fml`](../doxia/doxia-modules/doxia-module-fml/)|`fml`| +|[Markdown](../modules/index.html#Markdown)<sup>**</sup>|Markdown markup language||<sup>****</sup>|`markdown`|`md`, `markdown`<sup>***</sup>|[`doxia-module-markdown`](../doxia/doxia-modules/doxia-module-markdown/)|`markdown`| +|[TWiki](../modules/index.html#TWiki)<sup>*</sup>|TWiki Structured Wiki|||`twiki`|`twiki`|[`doxia-module-twiki`](../doxia/doxia-modules/doxia-module-twiki/)|`twiki`| +|[Xdoc](./xdoc-format.html)|XML Documentation Format|||`xdoc`|`xml`|[`doxia-module-xdoc`](../doxia/doxia-modules/doxia-module-xdoc/)|`xdoc`| +|[XHTML](../modules/index.html#XHTML)|Extensible Hypertext Markup Language|||`xhtml`|`xhtml`|[`doxia-module-xhtml`](../doxia/doxia-modules/doxia-module-xhtml/)|`xhtml`| + +Note some modules are not included per default with the site plugin. Have a look at the available modules here: [https://repo.maven.apache.org/maven2/org/apache/maven/doxia/](https://repo.maven.apache.org/maven2/org/apache/maven/doxia/). + +If you need to add module for the maven site plugin simply add it as a dependency of the plugin + +```unknown + <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-site-plugin</artifactId> <version>3.2</version> @@ -191,61 +63,26 @@ under the License. <version>1.3</version> </dependency> </dependencies> - </plugin>]]> - </source> - </p> - - <p> - <sup>*</sup> Since Doxia 1.1 - </p> - <p> - <sup>**</sup> Since Doxia 1.3 - </p> - <p> - <sup>***</sup> Since Doxia 1.7 - </p> - <p> - <sup>****</sup> Since Doxia 1.12.0 - </p> - </section> - - <section name="Doxia Page Output Format (deprecated)"> - <p> - The following table gives an overview of the output-only page-oriented deprecated (in Doxia 1.11) formats: - </p> - - <table border="0"> - <tr> - <th>Format</th> - <th>Short description</th> - <th>Doxia Module</th> - </tr> - - <tr> - <td><a href="../modules/index.html#iText">iText</a></td> - <td>iText PDF Library</td> - <td><a href="../doxia/doxia-modules/doxia-module-itext/"><code>doxia-module-itext</code></a></td> - </tr> - - <tr> - <td><a href="../modules/index.html#FO">FO</a><sup>*</sup></td> - <td>XSL formatting objects (XSL-FO)</td> - <td><a href="../doxia/doxia-modules/doxia-module-fo/"><code>doxia-module-fo</code></a></td> - </tr> - - <tr> - <td><a href="../modules/index.html#LaTeX">LaTeX</a></td> - <td>LaTeX typesetting system</td> - <td><a href="../doxia/doxia-modules/doxia-module-latex/"><code>doxia-module-latex</code></a></td> - </tr> - - <tr> - <td><a href="../modules/index.html#RTF">RTF</a></td> - <td>Microsoft Rich Text Format</td> - <td><a href="../doxia/doxia-modules/doxia-module-rtf/"><code>doxia-module-rtf</code></a></td> - </tr> - </table> - </section> - </body> - -</document> + </plugin> + +``` + +<sup>*</sup> Since Doxia 1\.1 + +<sup>**</sup> Since Doxia 1\.3 + +<sup>***</sup> Since Doxia 1\.7 + +<sup>****</sup> Since Doxia 1\.12\.0 + +# Doxia Page Output Format \(deprecated\) + +The following table gives an overview of the output-only page-oriented deprecated \(in Doxia 1\.11\) formats: + +|Format|Short description|Doxia Module| +|---|---|---| +|[iText](../modules/index.html#iText)|iText PDF Library|[`doxia-module-itext`](../doxia/doxia-modules/doxia-module-itext/)| +|[FO](../modules/index.html#FO)<sup>*</sup>|XSL formatting objects \(XSL-FO\)|[`doxia-module-fo`](../doxia/doxia-modules/doxia-module-fo/)| +|[LaTeX](../modules/index.html#LaTeX)|LaTeX typesetting system|[`doxia-module-latex`](../doxia/doxia-modules/doxia-module-latex/)| +|[RTF](../modules/index.html#RTF)|Microsoft Rich Text Format|[`doxia-module-rtf`](../doxia/doxia-modules/doxia-module-rtf/)| + diff --git a/content/markdown/references/xdoc-format.md b/content/markdown/references/xdoc-format.md index 2428492..bd37566 100644 --- a/content/markdown/references/xdoc-format.md +++ b/content/markdown/references/xdoc-format.md @@ -1,4 +1,8 @@ -<?xml version="1.0" encoding="UTF-8"?> +--- +title: The Xdoc format +author: + - Lukas Theussl +--- <!-- Licensed to the Apache Software Foundation (ASF) under one @@ -19,61 +23,35 @@ specific language governing permissions and limitations under the License. --> -<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";> +# Content - <properties> - <title>The Xdoc format</title> - <author email="ltheussl_AT_apache_DOT_org">Lukas Theussl</author> - </properties> +<a id="Content"></a> - <body> +<!-- MACRO{toc|fromDepth=1|toDepth=2} --> - <section name="Content"> - <a name="Content"/> - <macro name="toc"> - <param name="fromDepth" value="1"/> - <param name="toDepth" value="2"/> - </macro> - </section> +# The XDoc format - <section name="The XDoc format"> - <a name="The_XDoc_format"/> - <a name="Overview"/> - <subsection name="Overview"> - <p> - An 'xdoc' is an XML document conforming to a small and simple set of tags. - Xdoc was the primary documentation format in <a href="http://maven.apache.org/maven-1.x/";>Maven 1</a>, - Maven 2 largely replaced this by <a href="apt-format.html">Apt</a>, but xdoc is still supported. - </p> - - <p> - Historically, the xdoc format can be traced back to the - <a href="http://velocity.apache.org/anakia/devel/";>Anakia</a> format, as once used by the - <a href="http://jakarta.apache.org/";>Apache Jakarta</a> project then moved - to <a href="http://velocity.apache.org/";>Velocity</a>. - </p> - - <p> - The Maven 1 Xdoc plugin introduced a few additions to the Anakia format, they are highlighted in the - <a href="http://maven.apache.org/maven-1.x/plugins/xdoc/reference/xdocs.html";>plugin</a> documentation. - </p> - </subsection> +<a id="The_XDoc_format"></a> <a id="Overview"></a> +## Overview - <a name="The_XDoc_xsd"/> - <subsection name="The XDoc xsd"> - <p> - The full documentation is available <a href="../doxia/doxia-modules/doxia-module-xdoc/xsddoc/index.html">here</a>. - </p> - </subsection> +An 'xdoc' is an XML document conforming to a small and simple set of tags. Xdoc was the primary documentation format in [Maven 1](http://maven.apache.org/maven-1.x/), Maven 2 largely replaced this by [Apt](apt-format.html), but xdoc is still supported. + +Historically, the xdoc format can be traced back to the [Anakia](http://velocity.apache.org/anakia/devel/) format, as once used by the [Apache Jakarta](http://jakarta.apache.org/) project then moved to [Velocity](http://velocity.apache.org/). + +The Maven 1 Xdoc plugin introduced a few additions to the Anakia format, they are highlighted in the [plugin](http://maven.apache.org/maven-1.x/plugins/xdoc/reference/xdocs.html) documentation. - <a name="XDoc_Sample"/> - <subsection name="XDoc Sample"> - <p> - The following is a sample XDoc document: - </p> - <source><. + +<a id="XDoc_Sample"></a> +## XDoc Sample + +The following is a sample XDoc document: + +```unknown +<?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";> @@ -115,130 +93,94 @@ code line 2 </body> -</document>]]></source> +</document> +``` + +<a id="The_source_tag"></a> +## The <source> tag - </subsection> +`<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: - <a name="The_source_tag"/> - <subsection name="The <source> tag"> - <p> - <code><source></code> 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: - </p> -<source><source><![CDATA[ content here <a href="">foo</a>]]></source></source> - </subsection> +```unknown +<source><![CDATA[ content here <a href="">foo</a>]]></source> +``` - <a name="Additional_sectioning"/> - <subsection name="Additional sectioning"> - <p> - Doxia will produce <code><h2></code> and - <code><h3></code> headings for <code><section></code> - and <code><subsection></code> elements, respectively. - It is therefore perfectly valid to put some sub-headings - (<code><h4></code>, <code><h5></code>, - <code><h6></code>) inside a subsection. For instance, - </p> +<a id="Additional_sectioning"></a> +## Additional sectioning - <source><![CDATA[<h4>A subsubsection</h4>]]></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, - <p> - will produce: - </p> +```unknown +<h4>A subsubsection</h4> +``` - <h4>A subsubsection</h4> - </subsection> +will produce: + +#### A subsubsection + +<a id="Referencing_sections_and_subsections"></a> +## Referencing sections and subsections - <a name="Referencing_sections_and_subsections"/> - <subsection name="Referencing sections and subsections"> - <p> - The core doxia modules do <b>not</b> construct anchors from - section/subsection names. If you want to reference a section, - you should either provide an explicit anchor: - </p> +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: - <source><![CDATA[<a name="Section1"/> +```unknown +<a name="Section1"/> <section name="Section"> <a name="SubSection1"/> <subsection name="SubSection"> </subsection> -</section>]]></source> +</section> +``` - <p> - or use an <code>id</code> attribute for section and subsections - (note that <code>id</code>'s have to be unique within one xdoc - source document): - </p> +or use an `id` attribute for section and subsections \(note that `id`'s have to be unique within one xdoc source document\): - <source><![CDATA[<section name="Section" id="Section1"> +```unknown +<section name="Section" id="Section1"> <subsection name="SubSection" id="SubSection1"> </subsection> -</section>]]></source> +</section> +``` - <p> - <b>Note</b> that this differs from previous behavior, where anchors - were constructed from section/subsection names, replacing special - characters by underscores. This behavior presents two shortcomings: - </p> +**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: - <ul> +- 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. - <li> - 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. - </li> +- For long section titles, this leads to rather cumbersome anchor names. - <li> - For long section titles, this leads to rather cumbersome anchor names. - </li> +If automatic anchor generation is desired for a particular output format, it should be implemented / overridden by the corresponding low-level Sink. - </ul> +# Validation - <p> - If automatic anchor generation is desired for a particular output format, - it should be implemented / overridden by the corresponding low-level Sink. - </p> +<a id="Validation"></a> - </subsection> - </section> - - <section name="Validation"> - <a name="Validation"/> - <p> - Doxia is able to validate your xdoc files as described - <a href="../doxia/doxia-modules/doxia-module-xdoc/using-xdoc-xsd.html">here</a>. - </p> +Doxia is able to validate your xdoc files as described [here](../doxia/doxia-modules/doxia-module-xdoc/using-xdoc-xsd.html). - <p> - Here is a list of common mistakes to be aware of: - </p> +Here is a list of common mistakes to be aware of: - <a name="Dont_nest_block_level_elements"/> - <subsection name="Don't nest block level elements"> +<a id="Dont_nest_block_level_elements"></a> +## Don't nest block level elements - <p>Wrong:</p> +Wrong: - <source><![CDATA[<p> +```unknown +<p> Here's a list: <ul> <li>item 1</li> <li>item 2</li> </ul> of things to do. -</p>]]></source> +</p> +``` - <p>Correct:</p> +Correct: - <source><![CDATA[<p> +```unknown +<p> Here's a list: </p> <ul> @@ -247,79 +189,59 @@ code line 2 </ul> <p> of things to do. -</p>]]></source> - - <p> - Typical block level elements are list elements, - <code><table></code>, <code><source></code>, - <code><div></code>, <code><p></code> and - <code><pre></code>. - </p> +</p> +``` - </subsection> +Typical block level elements are list elements, `<table>`, `<source>`, `<div>`, `<p>` and `<pre>`. - <a name="Put_inline_elements_inside_block_level_elements"/> - <subsection name="Put inline elements inside block level elements"> +<a id="Put_inline_elements_inside_block_level_elements"></a> +## Put inline elements inside block level elements - <p>Wrong:</p> +Wrong: - <source><![CDATA[<section name="Downloads"> +```unknown +<section name="Downloads"> <a href="downloads.html">Downloads</a> -</section>]]></source> +</section> +``` - <p>Correct:</p> +Correct: - <source><![CDATA[<section name="Downloads"> +```unknown +<section name="Downloads"> <p> <a href="downloads.html">Downloads</a> </p> -</section>]]></source> +</section> +``` - <p> - Typical inline elements are - <code><a></code>, <code><strong></code>, - <code><code></code>, <code><font></code>, - <code><br></code> and <code><img></code>. - </p> +Typical inline elements are `<a>`, `<strong>`, `<code>`, `<font>`, `<br>` and `<img>`. - </subsection> - - <a name="Right_order_of_elements_in_properties"/> - <subsection name="Right order of elements in <properties>"> +<a id="Right_order_of_elements_in_properties"></a> +## Right order of elements in <properties> - <p> - The <code><title></code> element has to come before - <code><author></code>. - </p> +The `<title>` element has to come before `<author>`. - </subsection> +<a id="Dont_put_source_inside_paragraphs"></a> +## Don't put <source> inside paragraphs - <a name="Dont_put_source_inside_paragraphs"/> - <subsection name="Don't put <source> inside paragraphs"> +Wrong: - <p>Wrong:</p> - - <source><![CDATA[<p> +```unknown +<p> The following command executes the program: <source>java -jar CoolApp.jar</source> -</p>]]></source> +</p> +``` - <p>Correct:</p> +Correct: - <source><![CDATA[<p> +```unknown +<p> The following command executes the program: </p> -<source>java -jar CoolApp.jar</source>]]></source> - - <p> - However, you may put <code><source></code> elements inside - list items or table rows. - </p> +<source>java -jar CoolApp.jar</source> +``` - </subsection> +However, you may put `<source>` elements inside list items or table rows. - </section> - - </body> - -</document> diff --git a/content/markdown/scm.md b/content/markdown/scm.md index 7d30806..3e8a847 100644 --- a/content/markdown/scm.md +++ b/content/markdown/scm.md @@ -1,4 +1,6 @@ -<?xml version="1.0" encoding="UTF-8"?> +--- +title: Source Repository +--- <!-- Licensed to the Apache Software Foundation (ASF) under one @@ -19,66 +21,29 @@ specific language governing permissions and limitations under the License. --> -<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>Source Repository</title> - </properties> - <body> - <section name="Source Repository"> - <p> - Maven Doxia projects use <a href="http://git-scm.com/";>Git</a> or <a href="http://subversion.apache.org/";>Subversion</a> to manage their source code: - decisions to stay with Subversion or move to Git are tracked on <a href="https://cwiki.apache.org/confluence/display/MAVEN/Git+Migration";>Maven's Wiki</a>. - </p> - <p> - Instructions on Subversion use can be found in the online book <a href="http://svnbook.red-bean.com/";>Version Control with Subversion</a>. - Instructions on Git use can be found in the online book <a href="http://git-scm.com/book/";>Pro Git</a>. - Instructions for using the Apache Software Foundation Git repositories are at <a href="https://git-wip-us.apache.org/";>https://git-wip-us.apache.org</a>. - </p> +# Source Repository - <subsection name="Doxia Website"> - <p>The sources for this site are available in a separate Git repository: - <table> - <tr> - <td><a href="/doxia/">Apache Maven Doxia website</a></td> - <td><source><a href="https://gitbox.apache.org/repos/asf/maven-doxia-site.git";>https://gitbox.apache.org/repos/asf/maven-doxia-site.git</a></source></td> - <td><a href="https://github.com/apache/maven-doxia-site/";>(GitHub mirror)</a></td> - </tr> - </table> - </p> - </subsection> +Maven Doxia projects use [Git](http://git-scm.com/) or [Subversion](http://subversion.apache.org/) to manage their source code: decisions to stay with Subversion or move to Git are tracked on [Maven's Wiki](https://cwiki.apache.org/confluence/display/MAVEN/Git+Migration). + +Instructions on Subversion use can be found in the online book [Version Control with Subversion](http://svnbook.red-bean.com/). Instructions on Git use can be found in the online book [Pro Git](http://git-scm.com/book/). Instructions for using the Apache Software Foundation Git repositories are at [https://git-wip-us.apache.org](https://git-wip-us.apache.org/). + +## Doxia Website + +The sources for this site are available in a separate Git repository: + +| | | | +|---|---|---| +|[Apache Maven Doxia website](/doxia/)|<pre><code><a href="https://gitbox.apache.org/repos/asf/maven-doxia-site.git"; class="externalLink">https://gitbox.apache.org/repos/asf/maven-doxia-site.git</a></code></pre>|[\(GitHub mirror\)](https://github.com/apache/maven-doxia-site/)| + +## Components in Git + +The components in Git are: + +| | | | +|---|---|---| +|[Apache Maven Doxia base](doxia/)|<pre><code><a href="https://gitbox.apache.org/repos/asf/maven-doxia.git"; class="externalLink">https://gitbox.apache.org/repos/asf/maven-doxia.git</a></code></pre>|[\(GitHub mirror\)](https://github.com/apache/maven-doxia/)| +|[Apache Maven Doxia Sitetools](doxia-sitetools/)|<pre><code><a href="https://gitbox.apache.org/repos/asf/maven-doxia-sitetools.git"; class="externalLink">https://gitbox.apache.org/repos/asf/maven-doxia-sitetools.git</a></code></pre>|[\(GitHub mirror\)](https://github.com/apache/maven-doxia-sitetools/)| +|Doxia Tools| +|[Apache Maven Doxia Converter](doxia-tools/doxia-converter/)|<pre><code><a href="https://gitbox.apache.org/repos/asf/maven-doxia-converter.git"; class="externalLink">https://gitbox.apache.org/repos/asf/maven-doxia-converter.git</a></code></pre>|[\(GitHub mirror\)](https://github.com/apache/maven-doxia-converter/)| +|[Apache Maven Doxia LinkCheck](doxia-tools/doxia-linkcheck/)|<pre><code><a href="https://gitbox.apache.org/repos/asf/maven-doxia-linkcheck.git"; class="externalLink">https://gitbox.apache.org/repos/asf/maven-doxia-linkcheck.git</a></code></pre>|[\(GitHub mirror\)](https://github.com/apache/maven-doxia-linkcheck/)| - <subsection name="Components in Git"> - <p> - The components in Git are: - <table> - <tr> - <td><a href="doxia/">Apache Maven Doxia base</a></td> - <td><source><a href="https://gitbox.apache.org/repos/asf/maven-doxia.git";>https://gitbox.apache.org/repos/asf/maven-doxia.git</a></source></td> - <td><a href="https://github.com/apache/maven-doxia/";>(GitHub mirror)</a></td> - </tr> - <tr> - <td><a href="doxia-sitetools/">Apache Maven Doxia Sitetools</a></td> - <td><source><a href="https://gitbox.apache.org/repos/asf/maven-doxia-sitetools.git";>https://gitbox.apache.org/repos/asf/maven-doxia-sitetools.git</a></source></td> - <td><a href="https://github.com/apache/maven-doxia-sitetools/";>(GitHub mirror)</a></td> - </tr> - <tr> - <th>Doxia Tools</th> - </tr> - <tr> - <td><a href="doxia-tools/doxia-converter/">Apache Maven Doxia Converter</a></td> - <td><source><a href="https://gitbox.apache.org/repos/asf/maven-doxia-converter.git";>https://gitbox.apache.org/repos/asf/maven-doxia-converter.git</a></source></td> - <td><a href="https://github.com/apache/maven-doxia-converter/";>(GitHub mirror)</a></td> - </tr> - <tr> - <td><a href="doxia-tools/doxia-linkcheck/">Apache Maven Doxia LinkCheck</a></td> - <td><source><a href="https://gitbox.apache.org/repos/asf/maven-doxia-linkcheck.git";>https://gitbox.apache.org/repos/asf/maven-doxia-linkcheck.git</a></source></td> - <td><a href="https://github.com/apache/maven-doxia-linkcheck/";>(GitHub mirror)</a></td> - </tr> - </table> - </p> - </subsection> - </section> - </body> -</document>
