由 Maven 构建

内容

XDoc 格式

概述

'xdoc' 是符合一组小而简单的标签的 XML 文档。Xdoc 是Maven 1中的主要文档格式，Maven 2 在很大程度上用Apt取代了它，但仍然支持 xdoc。

从历史上看，xdoc 格式可以追溯到 Anakia格式，曾经被 Apache Jakarta项目使用，然后转移到Velocity。

Maven 1 Xdoc 插件为 Anakia 格式引入了一些附加功能，它们在 插件文档中突出显示。

XDoc xsd

完整的文档可在此处获得。

XDoc 示例

以下是一个示例 XDoc 文档： 

<?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> 标签

<source>标签是特殊的。此标记中的任何内容都在“逐字框”中呈现为预先格式化的文本。如果要在源标记中嵌入其他 XML/XHTML 标记，则需要在源部分中放置一个 CDATA 部分。例子： 

<source><![CDATA[ content here <a href="">foo</a>]]></source>

附加切片

Doxia 将分别生成<h2>和 <h3>指向<section> 和<subsection>元素。因此，将一些小标题（<h4>, <h5>, <h6>）放在一个小节中是完全有效的。例如， 

<h4>A subsubsection</h4>

将产生：

一个小节

参考章节和小节

核心 doxia 模块不会从节/小节名称构造锚点。如果你想引用一个部分，你应该提供一个明确的锚点： 

<a name="Section1"/>
<section name="Section">

  <a name="SubSection1"/>
  <subsection name="SubSection">
  </subsection>

</section>

或使用idsection 和 subsections 的属性（注意id' 在一个 xdoc 源文档中必须是唯一的）： 

<section name="Section" id="Section1">

  <subsection name="SubSection" id="SubSection1">
  </subsection>

</section>

请注意，这与以前的行为不同，其中锚点是从节/子节名称构造的，用下划线替换特殊字符。这种行为有两个缺点：

  • 如果两个部分或子部分具有相同的名称（在一个源文档中），则在引用它们时会产生歧义。生成的 html 文档也不是有效的 XHTML。对于其他输出格式（例如 pdf），甚至可能无法生成目标文档。
  • 对于长节标题，这会导致相当麻烦的锚名称。

如果特定输出格式需要自动生成锚点，则应由相应的低级接收器实现/覆盖。

验证

Doxia 能够按照 此处所述验证您的 xdoc 文件。

以下是需要注意的常见错误列表：

不要嵌套块级元素

错误的：

<p>
  Here's a list:
  <ul>
    <li>item 1</li>
    <li>item 2</li>
  </ul>
  of things to do.
</p>

正确的：

<p>
  Here's a list:
</p>
<ul>
  <li>item 1</li>
  <li>item 2</li>
</ul>
<p>
  of things to do.
</p>

典型的 块级元素是列表 元素<table>、、、、<source>和 。 <div><p><pre>

将内联元素放在块级元素中

错误的：

<section name="Downloads">
  <a href="downloads.html">Downloads</a>
</section>

正确的：

<section name="Downloads">
  <p>
    <a href="downloads.html">Downloads</a>
  </p>
</section>

典型的内 联元素是 <a>、<strong>、 <code>、<font>和 。 <br><img>

<properties> 中元素的正确顺序

<title>元素必须在 前面<author>。

不要将 <source> 放在段落中

错误的：

<p>
  The following command executes the program:
  <source>java -jar CoolApp.jar</source>
</p>

正确的：

<p>
  The following command executes the program:
</p>
<source>java -jar CoolApp.jar</source>

但是，您可以将<source>元素放在列表项或表格行中。