| <?xml version="1.0" encoding="UTF-8"?> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| 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 Xdoc format</title> |
| <author email="ltheussl_AT_apache_DOT_org">Lukas Theussl</author> |
| </properties> |
| |
| <body> |
| |
| <section name="Content"> |
| <a name="Content"/> |
| <macro name="toc"> |
| <param name="fromDepth" value="1"/> |
| <param name="toDepth" value="2"/> |
| </macro> |
| </section> |
| |
| <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 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> |
| |
| <a name="XDoc_Sample"/> |
| <subsection name="XDoc Sample"> |
| <p> |
| The following is a sample XDoc document: |
| </p> |
| <source><![CDATA[<?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="user@company.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> |
| |
| </subsection> |
| |
| <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> |
| |
| <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> |
| |
| <source><![CDATA[<h4>A subsubsection</h4>]]></source> |
| |
| <p> |
| will produce: |
| </p> |
| |
| <h4>A subsubsection</h4> |
| </subsection> |
| |
| <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> |
| |
| <source><![CDATA[<a name="Section1"/> |
| <section name="Section"> |
| |
| <a name="SubSection1"/> |
| <subsection name="SubSection"> |
| </subsection> |
| |
| </section>]]></source> |
| |
| <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> |
| |
| <source><![CDATA[<section name="Section" id="Section1"> |
| |
| <subsection name="SubSection" id="SubSection1"> |
| </subsection> |
| |
| </section>]]></source> |
| |
| <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> |
| |
| <ul> |
| |
| <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> |
| |
| <li> |
| For long section titles, this leads to rather cumbersome anchor names. |
| </li> |
| |
| </ul> |
| |
| <p> |
| If automatic anchor generation is desired for a particular output format, |
| it should be implemented / overridden by the corresponding low-level Sink. |
| </p> |
| |
| </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> |
| |
| <p> |
| Here is a list of common mistakes to be aware of: |
| </p> |
| |
| <a name="Dont_nest_block_level_elements"/> |
| <subsection name="Don't nest block level elements"> |
| |
| <p>Wrong:</p> |
| |
| <source><![CDATA[<p> |
| Here's a list: |
| <ul> |
| <li>item 1</li> |
| <li>item 2</li> |
| </ul> |
| of things to do. |
| </p>]]></source> |
| |
| <p>Correct:</p> |
| |
| <source><![CDATA[<p> |
| Here's a list: |
| </p> |
| <ul> |
| <li>item 1</li> |
| <li>item 2</li> |
| </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> |
| |
| </subsection> |
| |
| <a name="Put_inline_elements_inside_block_level_elements"/> |
| <subsection name="Put inline elements inside block level elements"> |
| |
| <p>Wrong:</p> |
| |
| <source><![CDATA[<section name="Downloads"> |
| <a href="downloads.html">Downloads</a> |
| </section>]]></source> |
| |
| <p>Correct:</p> |
| |
| <source><![CDATA[<section name="Downloads"> |
| <p> |
| <a href="downloads.html">Downloads</a> |
| </p> |
| </section>]]></source> |
| |
| <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> |
| |
| </subsection> |
| |
| <a name="Right_order_of_elements_in_properties"/> |
| <subsection name="Right order of elements in <properties>"> |
| |
| <p> |
| The <code><title></code> element has to come before |
| <code><author></code>. |
| </p> |
| |
| </subsection> |
| |
| <a name="Dont_put_source_inside_paragraphs"/> |
| <subsection name="Dont put <source> inside paragraphs"> |
| |
| <p>Wrong:</p> |
| |
| <source><![CDATA[<p> |
| The following command executes the program: |
| <source>java -jar CoolApp.jar</source> |
| </p>]]></source> |
| |
| <p>Correct:</p> |
| |
| <source><![CDATA[<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> |
| |
| </subsection> |
| |
| </section> |
| |
| </body> |
| |
| </document> |