Documentation update
git-svn-id: https://svn.apache.org/repos/asf/maven/maven-1/plugins/trunk@292501 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
ltheussl
@@ -31,8 +31,8 @@
|
||||
<name>xdoc</name>
|
||||
<description>
|
||||
The default goal. This goal simply executes the
|
||||
<a href="#xdoc:generate-from-pom">xdoc:generate-from-pom</a>
|
||||
and <a href="#xdoc:transform">xdoc:transform</a> goals
|
||||
<code>xdoc:generate-from-pom</code>
|
||||
and <code>xdoc:transform</code> goals.
|
||||
</description>
|
||||
</goal>
|
||||
<goal>
|
||||
@@ -40,13 +40,20 @@
|
||||
<description>
|
||||
Generate a set of reports from your <code>project.xml</code> file.
|
||||
This includes the dependency, mailing list, project info, project
|
||||
reports and team list pages
|
||||
reports and team list pages.
|
||||
</description>
|
||||
</goal>
|
||||
<goal>
|
||||
<name>xdoc:transform</name>
|
||||
<description>
|
||||
Transforms user supplied documents into html.
|
||||
</description>
|
||||
</goal>
|
||||
<goal>
|
||||
<name>xdoc:validate</name>
|
||||
<description>
|
||||
Validates the user xdoc documents.
|
||||
Validates the user xdoc documents. See
|
||||
<a href="reference/xdocs.html#Validation">Validation</a>.
|
||||
</description>
|
||||
</goal>
|
||||
<goal>
|
||||
|
||||
@@ -1,7 +1,4 @@
|
||||
<?xml version="1.0"?>
|
||||
<!DOCTYPE document [
|
||||
<!ENTITY escapeXmlExample SYSTEM "file:xdocs/escapeXml.xml">
|
||||
]>
|
||||
<!--
|
||||
/*
|
||||
* Copyright 2001-2005 The Apache Software Foundation.
|
||||
@@ -44,71 +41,6 @@
|
||||
<p>In addition to xdocs, users may wish to include other types of files such as images, their own HTML files, PDFs, etc. By default, this plugin will copy all files located in the <code>maven.docs.src</code> directory (<code>xdocs</code> by default) to the final generated site.</p>
|
||||
<p>If you create a <code>style/project.css</code> stylesheet under <code>maven.docs.src</code>, it will be copied to the resulting document tree and imported into each page (via <code>@import</code>). This allows you to easily add and modify the styles that are provided by Maven.</p>
|
||||
</subsection>
|
||||
<subsection name="Footer Tag">
|
||||
<p>You can use the <code>footer</code> tag for including text or images just below the navigation menu and above the copyright notice. This tag is only usefull in the navigation.xml file and should be placed within the body element. For example:</p>
|
||||
<source><![CDATA[<!-- footer will be placed above the (c) -->
|
||||
<footer>
|
||||
<A href="http://sourceforge.net/projects/ctecl">
|
||||
<IMG src="http://sourceforge.net/sflogo.php?group_id=72748" border="0" alt="sf logo"/>
|
||||
</A>
|
||||
</footer>]]></source>
|
||||
</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>, as shown in the following example: </p>
|
||||
<source><![CDATA[<navbar prev="first.html" home="../index.html" next="next.html"/>]]></source>
|
||||
</subsection>
|
||||
<subsection name="Google Search">
|
||||
<p>If a <code><search/></code> element is found in the <code>navigation.xml</code> body, a search navigation menu is generated that uses <a href="http://www.google.com">google</a>
|
||||
</p>
|
||||
</subsection>
|
||||
<subsection name="Additional 'powered-by' logos">
|
||||
<p>
|
||||
You can add additional 'powered-by' logos above the maven logo by
|
||||
specifying a <code><powered-by></code> element in the body
|
||||
of <code>navigation.xml</code>, e.g.:
|
||||
</p>
|
||||
<source><![CDATA[<powered-by>
|
||||
<item
|
||||
name="Hosted by SourceForge"
|
||||
href="http://www.sourceforge.net"
|
||||
img="http://sourceforge.net/sflogo.php?group_id=16035&type=1"/>
|
||||
</powered-by>]]></source>
|
||||
<p>You may specify several items to include more logos.</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>
|
||||
</subsection>
|
||||
<subsection name="Open Link in New Window">
|
||||
<p>To open a link in a new window, use the "target" attribute. For example, for a menu item: </p>
|
||||
<source><![CDATA[<item name="Name" href="URL" target="_blank"/>]]></source>
|
||||
<p>XDoc automatically adds the "Opens in a new window" icon and "New Window" tooltip to links with the "target" attribute.</p>
|
||||
</subsection>
|
||||
<subsection name="External Link Icon">
|
||||
<p>XDoc automatically adds the "External Link" icon and tooltip to links referring to external sites (actually, any absolute url).</p>
|
||||
</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> tag 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> tag, so you can reference sections and subsections from other source documents. Note that each <code>id</code> tag has to be unique within one source document.</p>
|
||||
<p>In previous versions of the plugin, an <code>id</code> tag 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> tag is present, an anchor is constructed from the <code>name</code> tag. 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> tag if you want to reference a section or subsection.</p>
|
||||
</subsection>
|
||||
</section>
|
||||
</body>
|
||||
</document>
|
||||
|
||||
@@ -30,7 +30,11 @@
|
||||
<item name="Goals" href="/goals.html"/>
|
||||
<item name="Properties" href="/properties.html"/>
|
||||
<item name="Tags" href="/tags.html"/>
|
||||
<item name="i18n" href="/i18n.html"/>
|
||||
<item name="Reference" href="/reference/index.html" collapse="true">
|
||||
<item name="Navigation file" href="/reference/navfile.html"/>
|
||||
<item name="Xdoc documents" href="/reference/xdocs.html"/>
|
||||
<item name="i18n" href="/reference/i18n.html"/>
|
||||
</item>
|
||||
<item name="FAQs" href="/faq.html"/>
|
||||
</menu>
|
||||
</body>
|
||||
|
||||
@@ -164,5 +164,6 @@ maven.xdoc.locale.supported=fr, de</pre>
|
||||
</p>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
</body>
|
||||
</document>
|
||||
62
xdoc/xdocs/reference/index.xml
Normal file
62
xdoc/xdocs/reference/index.xml
Normal file
@@ -0,0 +1,62 @@
|
||||
<?xml version="1.0"?>
|
||||
<!--
|
||||
/*
|
||||
* 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>Reference</title>
|
||||
</properties>
|
||||
|
||||
<body>
|
||||
|
||||
<section name="Reference documents">
|
||||
<table>
|
||||
<tr>
|
||||
<th>Document</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<a href="navfile.html">Navigation file</a>
|
||||
</td>
|
||||
<td>
|
||||
Describes the <code>navigation.xml</code> file format.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<a href="xdocs.html">Xdoc documents</a>
|
||||
</td>
|
||||
<td>
|
||||
Some notes on the <code>xdoc</code> file format.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<a href="i18n.html">i18n</a>
|
||||
</td>
|
||||
<td>
|
||||
Describes how to internationalize your site.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</section>
|
||||
|
||||
</body>
|
||||
</document>
|
||||
143
xdoc/xdocs/reference/navfile.xml
Normal file
143
xdoc/xdocs/reference/navfile.xml
Normal file
@@ -0,0 +1,143 @@
|
||||
<?xml version="1.0"?>
|
||||
<!--
|
||||
/*
|
||||
* 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>Navigation</title>
|
||||
</properties>
|
||||
<body>
|
||||
<section name="The navigation file">
|
||||
<p>
|
||||
Here is a template for a typical navigation file:
|
||||
</p>
|
||||
<source><![CDATA[<?xml version="1.0" encoding="ISO-8859-1"?>
|
||||
|
||||
<project name="My project">
|
||||
|
||||
<title>My project title</title>
|
||||
|
||||
<body>
|
||||
|
||||
<breadcrumbs>
|
||||
<item name="Home" href="/index.html"/>
|
||||
.
|
||||
</breadcrumbs>
|
||||
|
||||
<links>
|
||||
<item name="Home" href="/index.html"/>
|
||||
.
|
||||
</links>
|
||||
|
||||
|
||||
<menu name="Documentation">
|
||||
.
|
||||
</menu>
|
||||
.
|
||||
|
||||
<search/>
|
||||
|
||||
<powered-by>
|
||||
.
|
||||
</powered-by>
|
||||
|
||||
<footer>
|
||||
.
|
||||
</footer>
|
||||
|
||||
</body>
|
||||
</project>]]></source>
|
||||
<p>
|
||||
There has to be at least one <code><menu></code> element
|
||||
present in the documents body, all other elements are optional.
|
||||
The core elements of this navigation file are described in a
|
||||
<a href="http://maven.apache.org/using/site.html#Creating_a_Site_Descriptor">section</a>
|
||||
of the main Maven site, we'll just discuss the few additions here.
|
||||
</p>
|
||||
|
||||
<subsection name="Breadcrumbs">
|
||||
<p>
|
||||
A list of items that are displayed on the top left of the site.
|
||||
Check the top of this page for an example.
|
||||
</p>
|
||||
</subsection>
|
||||
|
||||
<subsection name="Menu">
|
||||
<p>
|
||||
The <code><menu></code> element takes an optional
|
||||
<code>type</code> attribute which can be set to
|
||||
"<code>header</code>" or "<code>footer</code>". This will put
|
||||
the corresponding menu on top or on bottom of the navigation
|
||||
menu, respectively.
|
||||
</p>
|
||||
<p>
|
||||
To open a link in a new window, use the "target" attribute.
|
||||
For example, for a menu item:
|
||||
</p>
|
||||
<source><![CDATA[<item name="Name" href="URL" target="_blank"/>]]></source>
|
||||
<p>
|
||||
XDoc automatically adds the "Opens in a new window" icon and
|
||||
"New Window" tooltip to links with the "target" attribute.
|
||||
</p>
|
||||
<p>
|
||||
XDoc also automatically adds the "External Link" icon and tooltip to
|
||||
links referring to external sites (actually, any absolute url).
|
||||
</p>
|
||||
</subsection>
|
||||
|
||||
<subsection name="Google Search">
|
||||
<p>
|
||||
If a <code><search/></code> element is found in the
|
||||
<code>navigation.xml</code> body, a search navigation menu is
|
||||
generated that uses <a href="http://www.google.com">google</a>.
|
||||
</p>
|
||||
</subsection>
|
||||
|
||||
<subsection name="Additional 'powered-by' logos">
|
||||
<p>
|
||||
You can add additional 'powered-by' logos above the maven logo by
|
||||
specifying a <code><powered-by></code> element in the body
|
||||
of <code>navigation.xml</code>, e.g.:
|
||||
</p>
|
||||
<source><![CDATA[<powered-by>
|
||||
<item
|
||||
name="Hosted by SourceForge"
|
||||
href="http://www.sourceforge.net"
|
||||
img="http://sourceforge.net/sflogo.php?group_id=16035&type=1"/>
|
||||
</powered-by>]]></source>
|
||||
<p>You may specify several items to include more logos.</p>
|
||||
</subsection>
|
||||
|
||||
<subsection name="Footer">
|
||||
<p>
|
||||
You can use the <code>footer</code> tag for including text or
|
||||
images just below the navigation menu and above the copyright notice.
|
||||
This tag is only useful in the navigation.xml file and should be
|
||||
placed within the body element. For example:
|
||||
</p>
|
||||
<source><![CDATA[<!-- footer will be placed above the (c) -->
|
||||
<footer>
|
||||
<a href="http://sourceforge.net/projects/ctecl">
|
||||
<img src="http://sourceforge.net/sflogo.php?group_id=72748" border="0" alt="sf logo"/>
|
||||
</a>
|
||||
</footer>]]></source>
|
||||
</subsection>
|
||||
|
||||
|
||||
</section>
|
||||
</body>
|
||||
</document>
|
||||
207
xdoc/xdocs/reference/xdocs.xml
Normal file
207
xdoc/xdocs/reference/xdocs.xml
Normal file
@@ -0,0 +1,207 @@
|
||||
<?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/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 currently it is not possible to validate
|
||||
arbitrary xml files with the <code>xdoc:validate</code> goal.
|
||||
You will get an error for both, the document that defines the
|
||||
external entity and the external xml file (except if it is actually
|
||||
valid). You can 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>
|
||||
|
||||
</section>
|
||||
|
||||
<navbar prev="navfile.html" home="../index.html" next="i18n.html"/>
|
||||
|
||||
</body>
|
||||
</document>
|
||||
Reference in New Issue
Block a user