diff --git a/xdoc/xdocs/goals.xml b/xdoc/xdocs/goals.xml index c52f541d..830313da 100644 --- a/xdoc/xdocs/goals.xml +++ b/xdoc/xdocs/goals.xml @@ -31,8 +31,8 @@ xdoc The default goal. This goal simply executes the - xdoc:generate-from-pom - and xdoc:transform goals + xdoc:generate-from-pom + and xdoc:transform goals. @@ -40,13 +40,20 @@ Generate a set of reports from your project.xml file. This includes the dependency, mailing list, project info, project - reports and team list pages + reports and team list pages. + + + + xdoc:transform + + Transforms user supplied documents into html. xdoc:validate - Validates the user xdoc documents. + Validates the user xdoc documents. See + Validation. diff --git a/xdoc/xdocs/index.xml b/xdoc/xdocs/index.xml index e1d033bd..7405c857 100644 --- a/xdoc/xdocs/index.xml +++ b/xdoc/xdocs/index.xml @@ -1,7 +1,4 @@ - -]> - ]]> - - -

You can put a navigation bar on bottom of each page by including a <navbar/> element in an xdoc's body. This element takes three optional attributes, prev, home and next, as shown in the following example:

- ]]> - - -

If a <search/> element is found in the navigation.xml body, a search navigation menu is generated that uses google -

- - -

- You can add additional 'powered-by' logos above the maven logo by - specifying a <powered-by> element in the body - of navigation.xml, e.g.: -

- - -]]> -

You may specify several items to include more logos.

- - -

If you need to include the contents of another XML document in your document, you can use the <escapeXml> tag, as demonstrated below. For instance, the code:

- - -]> -&escapeXmlExample;]]> -

Would produce the following output (click here to see the content of escapeXml.xml):

- - &escapeXmlExample; - - - -

To open a link in a new window, use the "target" attribute. For example, for a menu item:

- ]]> -

XDoc automatically adds the "Opens in a new window" icon and "New Window" tooltip to links with the "target" attribute.

- - -

XDoc automatically adds the "External Link" icon and tooltip to links referring to external sites (actually, any absolute url).

- - -

From version 1.10 on, the xdoc plugin allows for an optional id tag in the section and subsection elements:

- - - -]]> -

An anchor is constructed from each id tag, so you can reference sections and subsections from other source documents. Note that each id tag has to be unique within one source document.

-

In previous versions of the plugin, an id tag was constructed from section/subsection names, replacing special characters by underscores. For backwards compatibility reasons, we keep this behaviour, i.e., if no id tag is present, an anchor is constructed from the name tag. Note that this presents two shortcomings:

- -

We recommend that you provide an id tag if you want to reference a section or subsection.

- diff --git a/xdoc/xdocs/navigation.xml b/xdoc/xdocs/navigation.xml index 8b15ee64..06bbd70f 100644 --- a/xdoc/xdocs/navigation.xml +++ b/xdoc/xdocs/navigation.xml @@ -30,7 +30,11 @@ - + + + + + diff --git a/xdoc/xdocs/escapeXml.xml b/xdoc/xdocs/reference/escapeXml.xml similarity index 100% rename from xdoc/xdocs/escapeXml.xml rename to xdoc/xdocs/reference/escapeXml.xml diff --git a/xdoc/xdocs/i18n.xml b/xdoc/xdocs/reference/i18n.xml similarity index 99% rename from xdoc/xdocs/i18n.xml rename to xdoc/xdocs/reference/i18n.xml index 8c2e90bc..c582f4df 100644 --- a/xdoc/xdocs/i18n.xml +++ b/xdoc/xdocs/reference/i18n.xml @@ -164,5 +164,6 @@ maven.xdoc.locale.supported=fr, de

+ diff --git a/xdoc/xdocs/reference/index.xml b/xdoc/xdocs/reference/index.xml new file mode 100644 index 00000000..19a664ba --- /dev/null +++ b/xdoc/xdocs/reference/index.xml @@ -0,0 +1,62 @@ + + + + + + + Reference + + + + +
+ + + + + + + + + + + + + + + + + +
DocumentDescription
+ Navigation file + + Describes the navigation.xml file format. +
+ Xdoc documents + + Some notes on the xdoc file format. +
+ i18n + + Describes how to internationalize your site. +
+
+ + + diff --git a/xdoc/xdocs/reference/navfile.xml b/xdoc/xdocs/reference/navfile.xml new file mode 100644 index 00000000..456fac45 --- /dev/null +++ b/xdoc/xdocs/reference/navfile.xml @@ -0,0 +1,143 @@ + + + + + Navigation + + +
+

+ Here is a template for a typical navigation file: +

+ + + + + My project title + + + + + + . + + + + + . + + + + + . + + . + + + + + . + + +
+ . +
+ + +]]> +

+ There has to be at least one <menu> element + present in the documents body, all other elements are optional. + The core elements of this navigation file are described in a + section + of the main Maven site, we'll just discuss the few additions here. +

+ + +

+ A list of items that are displayed on the top left of the site. + Check the top of this page for an example. +

+ + + +

+ The <menu> element takes an optional + type attribute which can be set to + "header" or "footer". This will put + the corresponding menu on top or on bottom of the navigation + menu, respectively. +

+

+ To open a link in a new window, use the "target" attribute. + For example, for a menu item: +

+ ]]> +

+ XDoc automatically adds the "Opens in a new window" icon and + "New Window" tooltip to links with the "target" attribute. +

+

+ XDoc also automatically adds the "External Link" icon and tooltip to + links referring to external sites (actually, any absolute url). +

+ + + +

+ If a <search/> element is found in the + navigation.xml body, a search navigation menu is + generated that uses google. +

+ + + +

+ You can add additional 'powered-by' logos above the maven logo by + specifying a <powered-by> element in the body + of navigation.xml, e.g.: +

+ + +]]> +

You may specify several items to include more logos.

+ + + +

+ You can use the footer 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: +

+ + ]]> + + + +
+ + diff --git a/xdoc/xdocs/reference/xdocs.xml b/xdoc/xdocs/reference/xdocs.xml new file mode 100644 index 00000000..b89066a2 --- /dev/null +++ b/xdoc/xdocs/reference/xdocs.xml @@ -0,0 +1,207 @@ + + +]> + + + + + + Xdocs + + +
+

+ A template for a typical 'xdoc' can be found in this + section + of the main Maven site, we'll just discuss a few additions here. +

+ + +

+ The xdoc plugin 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, +

+ A subsubsection]]> +

+ will produce: +

+

A subsubsection

+ + + +

+ From version 1.10 on, the xdoc plugin + allows for an optional id attribute in the + section and subsection elements: +

+ + + +
]]> +

+ An anchor is constructed from each id attribute, so you can + reference sections and subsections from other source documents. + Note that each id attribute has to be unique within one + source document. +

+

+ In previous versions of the plugin, an id attribute was + constructed from section/subsection names, replacing special + characters by underscores. For backwards compatibility reasons, + we keep this behaviour, i.e., if no id attribute + is present, an anchor is constructed from the name attribute. + Note that this presents two shortcomings: +

+
    +
  • + 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 long section titles, this leads to rather + cumbersome anchor names. +
    • +
+

+ We recommend that you provide an id attribute if you want + to reference a section or subsection. +

+ + + +

+ If you need to include the contents of another XML document in your + document, you can use the <escapeXml> tag, + as demonstrated below. For instance, the code: +

+ + +]> +&escapeXmlExample;]]> +

+ would produce the following output (click + here to see the content of + escapeXml.xml): +

+ &escapeXmlExample; +

+ Note that currently it is not possible to validate + arbitrary xml files with the xdoc:validate 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 maven.xdoc.validate.exclude + property to exclude specific files from validation. +

+ + + +

+ You can put a navigation bar on bottom of each page by including a + <navbar/> element in an xdoc's body. + This element takes three optional attributes, + prev, home and next: +

+ ]]> +

+ This element should appear after the last + <section/> of the document. + Check the bottom of this page for an example. +

+ + + + +
+

+ The xdoc:validate goal can be used to check whether your + source files are valid xdoc documents. This should ensure that the + generated html files are valid + XHTML1-transitional. + Here is a list of common mistakes to be aware of: +

+ + +

Wrong:

+ + Here's a list: +
    +
  • item 1
    • +
  • item 2
    • +
+ of things to do. +

]]> +

Correct:

+ + Here's a list: +

+
    +
  • item 1
    • +
  • item 2
    • +
+

+ of things to do. +

]]> +

+ Typical block level elements are list elements, + <table>, <source>, + <div>, <p> and + <pre>. +

+ + + +

Wrong:

+ + Downloads +
]]> +

Correct:

+ +

+ Downloads +

+]]> +

+ Typical inline elements are + <a>, <strong>, + <code>, <font>, + <br> and <img>. +

+ + + +

+ The <title> element has to come before + <author>. +

+ + + + + + + +