92e602a98c
git-svn-id: https://svn.apache.org/repos/asf/maven/maven-1/plugins/trunk@328487 13f79535-47bb-0310-9956-ffa450edef68
226 lines
7.9 KiB
XML
226 lines
7.9 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE document [
|
|
<!ENTITY escapeXmlExample SYSTEM "file:xdocs/reference/escapeXml.xml">
|
|
]>
|
|
|
|
<!--
|
|
/*
|
|
* Copyright 2001-2005 The Apache Software Foundation.
|
|
*
|
|
* Licensed 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>
|
|
<properties>
|
|
<title>Xdocs</title>
|
|
</properties>
|
|
<body>
|
|
<section name="Xdoc documents">
|
|
<p>
|
|
A template for a typical 'xdoc' can be found in this
|
|
<a href="http://maven.apache.org/maven-1.x/using/site.html#Creating_a_new_Document">section</a>
|
|
of the main Maven site, we'll just discuss a few additions here.
|
|
</p>
|
|
|
|
<subsection name="Additional sectioning">
|
|
<p>
|
|
The xdoc plugin 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>
|
|
|
|
<subsection name="Referencing sections and subsections">
|
|
<p>
|
|
From version <code>1.10</code> on, the <code>xdoc</code> plugin
|
|
allows for an optional <code>id</code> attribute in the
|
|
<code>section</code> and <code>subsection</code> elements:
|
|
</p>
|
|
<source><![CDATA[<section name="Section" id="Section1">
|
|
<subsection name="SubSection" id="SubSection1">
|
|
</subsection>
|
|
</section>]]></source>
|
|
<p>
|
|
An anchor is constructed from each <code>id</code> attribute, so you can
|
|
reference sections and subsections from other source documents.
|
|
Note that each <code>id</code> attribute has to be unique within one
|
|
source document.
|
|
</p>
|
|
<p>
|
|
In previous versions of the plugin, an <code>id</code> attribute was
|
|
constructed from section/subsection names, replacing special
|
|
characters by underscores. For backwards compatibility reasons,
|
|
we keep this behaviour, <em>i.e.</em>, if no <code>id</code> attribute
|
|
is present, an anchor is constructed from the <code>name</code> attribute.
|
|
Note that this 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.
|
|
</li>
|
|
<li>
|
|
For long section titles, this leads to rather
|
|
cumbersome anchor names.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
We recommend that you provide an <code>id</code> attribute if you want
|
|
to reference a section or subsection.
|
|
</p>
|
|
</subsection>
|
|
|
|
<subsection name="escapeXml Tag">
|
|
<p>
|
|
If you need to include the contents of another XML document in your
|
|
document, you can use the <code><escapeXml></code> tag,
|
|
as demonstrated below. For instance, the code:
|
|
</p>
|
|
<source><![CDATA[<?xml version="1.0"?>
|
|
<!DOCTYPE document [
|
|
<!ENTITY escapeXmlExample SYSTEM "file:xdocs/escapeXml.xml">
|
|
]>
|
|
<escapeXml>&escapeXmlExample;</escapeXml>]]></source>
|
|
<p>
|
|
would produce the following output (click
|
|
<a href="escapeXml.html">here</a> to see the content of
|
|
<code>escapeXml.xml</code>):
|
|
</p>
|
|
<source><escapeXml>&escapeXmlExample;</escapeXml></source>
|
|
<p>
|
|
<strong>Note</strong> that it is possible to validate the included
|
|
xml file with the <code>xdoc:validate</code> goal even if it is not
|
|
a valid xdoc document (like in the example above). You just have to
|
|
provide a custom <code>.dtd</code> or <code>.xsd</code> schema file
|
|
with the same base name in the same directory. Otherwise,
|
|
you should use the <code>maven.xdoc.validate.exclude</code>
|
|
property to exclude specific files from validation.
|
|
</p>
|
|
</subsection>
|
|
|
|
<subsection name="Navigation bar">
|
|
<p>
|
|
You can put a navigation bar on bottom of each page by including a
|
|
<code><navbar/></code> element in an xdoc's body.
|
|
This element takes three optional attributes,
|
|
<code>prev</code>, <code>home</code> and <code>next</code>:
|
|
</p>
|
|
<source><![CDATA[<navbar prev="first.html" home="../index.html" next="next.html"/>]]></source>
|
|
<p>
|
|
This element should appear after the last
|
|
<code><section/></code> of the document.
|
|
Check the bottom of this page for an example.
|
|
</p>
|
|
</subsection>
|
|
|
|
</section>
|
|
|
|
<section name="Validation">
|
|
<p>
|
|
The <code>xdoc:validate</code> goal can be used to check whether your
|
|
source files are valid xdoc documents. This should ensure that the
|
|
generated html files are valid
|
|
<a href="http://www.w3.org/TR/xhtml1/">XHTML1-transitional</a>.
|
|
Here is a list of common mistakes to be aware of:
|
|
</p>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<subsection name="Right order of elements in <properties>">
|
|
<p>
|
|
The <code><title></code> element has to come before
|
|
<code><author></code>.
|
|
</p>
|
|
</subsection>
|
|
|
|
<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>
|
|
|
|
<navbar prev="navfile.html" home="../index.html" next="i18n.html"/>
|
|
|
|
</body>
|
|
</document>
|