《Maven官方指南》APT格式

原文链接    译者:carvendy

APT格式

APT是标准的纯文本。APT 标记语言，它力求简单的文档编写的解决方案。它的语法像纯文本多于像其他标记格式（例如HTML）。文档提供一些可用的APT格式例子。

重要笔记

在文档中信息包含对应的源APT格式像发布的Xmlmind。在版本1.1 Maven Doxia已经同意一些改变源码格式，看看文档中的细节描述。值得注意的以下是一个[改变]链接的显著区别。

随着选项包含着格式文本，演示APT用于创建段落、头部、选项、列表、代码样本、图像、表格、规则、打破和文本级别元素例如样式、锚和特殊字符。在盒子包含打字机字体是APT源码的例子。

文档结构

一个短的APT文档是包含在一个文本文件。一个长文档可能包含一个排序的列表文件。作为实例，第一个文件包含选项1，第二个文本文件包含选项2，等等。

笔记： 在几个文本文件中分割APT文档边界不是强制性的。分割可能出现在任何地方。无论如何这样做是提醒，英文一个文本文件包含选项是它的合法APT文档。

一个文件包含序列的段落和“展示”（不是段落例如表格）分割成一行一行。 一个段落是简单的一个序列的连续文本行。

First line of first paragraph.
  Second line of first paragraph.
  Third line of first paragraph.
 
  Line 1 of paragraph 2 (separated from first paragraph by an open line).
  Line 2 of paragraph 2.

第一行段落的缩进是主方法，用于APT进程识别段落的类型。作为一个例子，一个选项标题不是必须被缩进。

My section title (not indented).
 
  My paragraph first line (indented by 2 spaces).

缩进不是固执的。你可以做的空间很大。你不需要使用一个缩进组成的文档。真正的问题是APT进程是无论段落不是缩进或者当它在一个列表，无论一个段落比读一个列表多还是少的缩进。（关于最新）。

First paragraph has its first line indented by four
spaces. Then the author did not even bother to indent the
other lines of the paragraph.
 
  Second paragraph contains several lines which are all
  indented by two spaces. This style is much nicer than
  the one used for the previous paragraph.

注意，制表符被展开，制表符宽度设置为8。

文档元素

块级别元素

标题

标题是可选的。如果使用，它必须出现在文档的第一块中。

------
            Title
            ------
            ------
             Date
            ------

一个标题是缩进（置于中心它是良好的）。它开始使用一行包含至少3个破折号(—)。

在第一个==—==行，一个或多个连续行文本（每行之后的隐式换行符）制定文档的标题。

这个文本可能马上跟着另外一个==—==行和一个或多个连续行文本制定文档的作者。

作者子块可以选择跟着一个使用相同语法的日期子块。

跟着例子是用于文档的标题和日期但是没有声明作者。

------
            Title
            ------
            ------
             Date
            ------

最后一行是忽略的。它指示作为一个良好的块。

注意，日期没有指定格式和将被转化为字符串。但是我们推荐使用ISO-8601标准，全世界支持格式日期各种各样。

YYYY-MM-DD

YYYY是格林威治的年，MM是年的1月到12月，和DD是一个月的一天从01到31.

Paragraph

除标题栏外的段落可能出现在第一节之前。

Paragraph 1, line 1.
  Paragraph 1, line 2.
 
  Paragraph 2, line 1.
  Paragraph 2, line 2.

段落是缩进的。他们已经描述在了文档结构部分。

Section

Section 是在文档中被创建插入到section标题。简单的文档不需要包含sections。

Section title
 
* Sub-section title
 
** Sub-sub-section title
 
*** Sub-sub-sub-section title
 
**** Sub-sub-sub-sub-section title

Section标题没有缩进。一个子部分标题开始于一个星号（*），一个子子部分标题有两个星号（*），所以高达四个子级别。

List

* List item 1.
 
      * List item 2.
 
        Paragraph contained in list item 2.
 
            * Sub-list item 1.
 
            * Sub-list item 2.
 
      * List item 3.

列表选项是缩进的和开始有一个星号（*）

纯段落比列表选项嵌套的列表有更多缩进。展示像一个表格（没有缩进）总是嵌套在当前列表。

在列表中嵌套一个列表,第一项的缩进比它的父级多一点。结束名单，加入一个段落或者列表项比当前列表缩进少。

section标题总是在列表的最后。显示不能在列表最后但是==[]==伪元素路被用于列表的结束。

* List item 3.
        Force end of list:
 
      []
 
--------------------------------------------
Verbatim text not contained in list item 3
--------------------------------------------

在前面的例子中，没有==[]==,逐字（显示没有缩进）将被包含在列表的第三项。

一个==[]可以被用于嵌套列表的结束在这时。[]==的压痕可以被指定确切的列表结束。例子：

* List item 1.
 
      * List item 2.
 
        * Sub-list item 1.
 
        * Sub-list item 2.
 
        []
 
-------------------------------------------------------------------
Verbatim text contained in list item 2, but not in sub-list item 2
-------------------------------------------------------------------

这里有三个列表，这强调符号的列表我们已经描述了。编号列表和定义：

[[1]] Numbered item 1.
 
                [[A]] Numbered item A.
 
                [[B]] Numbered item B.
 
      [[2]] Numbered item 2.

一个编号列表开始于一个label直接有两个方括号。第一项的label为了整个列表建立在数字方案。

[[1]] Decimal数字：1,2，3，4等。

[[a]] 小写编号：a,b,c,d等

[[A]] 大写编号：A,B,C,D等

[[i]] 小写罗马编号:i, ii, iii, iv等。

[[I]] 大写罗马编号：I, II, III, IV等。

忽略第一个项目以外的项目的标签。这里推荐花时间用正确的标签为每一个项目排序，并保持APT源码文档可读性。

[Defined term 1] of definition list 2.
 
      [Defined term 2] of definition list 2.

定义列表项以定义的术语开始：方括号之间的文本。

逐字文本

----------------------------------------
Verbatim
         text,
                preformatted,
                                escaped.
----------------------------------------

一个逐字块是没有缩进的。开始没有缩进行包含至少三个破折号（—）。像结束行。

==+–代替了—==画一个盒子包含逐字文本。

像HTML，逐字文本是预定格式。不像HTML,逐字文本是逃脱的：在逐字显示，标记没有解释APT进程。

图

[Figure name] Figure caption

图形块不缩进。它从方括号中的图形名称开始。数字名称可选后跟一些文本：数字标题。

图形名是文件的路径名包含图形但是没有扩展名。例子：如果你的图是包含在==/home/joe/docs/mylogo.jpeg==，图形名是。[[改变]http://maven.apache.org/doxia/references/doxia-apt.html#Figure_extensions)]

如果图形名来自一个相对路径（推荐实践）而不是绝对路径，这个相对路径名是被认为相对于当前APT文档的目录而不是相对于当前工作目录。

为什么不留文件扩展名在图形名？最好的解释就是例子。你需要转换APT文档成PostScript和你的图形名是/home/joe/docs/mylogo。一个APT进程将首先尝试加载==/home/joe/docs/mylogo.eps==。当希望的格式没有找到，一个APT进程尝试转换其中存在的格式。在我们的例子，APT进程尝试转换==/home/joe/docs/mylogo.jpeg==成封装的PostScript。

表格

一个表格块是没有缩进的。它开始没有缩进行包含一个星号和最少两个破折号（*—）。它结束于一个相似的行。

在首行是不进使用表格而且指定列的正当理由。在下面的例子，

  • 第二个星号(*)是用于指定列1是居中的。
  • 加号(+) 指定列2是左对齐。
  • 冒号(:) 指定列3是右对齐。
*----------*--------------+----------------:
| Centered | Left-aligned | Right-aligned  |
| cell 1,1 | cell 1,2     | cell 1,3       |
*----------*--------------+----------------:
| cell 2,1 | cell 2,2     | cell 2,3       |
*----------*--------------+----------------:
Table caption

这些行是由没有缩进的由 *– 的行。

一个可选的表格字幕（无缩进文本）可能马上跟着表格。

这些行可能包含单行或者多行单元格。每行单元格文本从相邻的单元格分开通过管字符（|）。（|肯被用在单元格文本如果引用：|）

最后一个====指南被用于做table好了。第一个====不仅被用于做table，并且指定网格画表格单元格。

通过下面的例子展示一下简单的表格，没有网格和字幕。

*-----*------*
 cell | cell
*-----*------*
 cell | cell
*-----*------*

水平规则

=====================

一个非缩进的行，包含至少3个相等的符号（===）

分页

^L

包含单个表单馈送字符的非缩进行（Control-L）。

行级元素

字体

<Italic> font. <<Bold>> font. <<<Monospaced>>> font.

文本之间的<and> 必须提供斜体。文本直接的 <<and>>提供的是粗体。文本之间的 <<<and>>>提供的是等宽，像打字机的字体。

字体元素可能出现在任意字体元素里面。

这不推荐在标题、部分标题、链接和定义条款中 使用字体元素，因为APT进程自动同意字体样式给其他元素控制。

锚和链接

{Anchor}. Link to {{anchor}}. Link to {{http://www.pixware.fr}}.
  Link to {{{anchor}showing alternate text}}.
  Link to {{{http://www.pixware.fr}Pixware home page}}.

文本之间需要大括号({})指定一个锚。文本之间有两个大括号({{}})指定一个链接。

这是一个错误地创建链接元素因为它没有引用一个同样名字的锚。这个锚和链接的名字是所有非字母数字字符。[改变]

这些规则不应用于链接额外的锚。文本开头为 http:/, https:/ ,ftp:/,file:/,mailto:,../,./(..==和 ==.==在Windows)是认为额外的锚名字。

当建造{{{name}text}} 被使用了，链接文本肯不同于链接名。

锚链接元素可能出现在其他锚链接里面。

部分标题隐式定义锚。[改变]

分行

Force line\
  break.

一个反斜杠（\）后跟一个换行符 在标题和表中不能使用换行符（这是带有隐式换行的行定向块）。

非破碎空间

Non\ breaking\ space.

一个反斜杠（\）后面的空间特征

特殊字符

Escaped special characters: \~, \=, \-, \+, \*, \[, \], \<, \>, \{, \}, \\.

在某些容器，这些字符有特别的意思和它们必须使用转义如果需要用的时候。他们转义是在前面加上斜杠。反斜杠本身可以逃脱它前面添加一个反斜杠。

注意这个星号，作为例子，如果它们开始需要转义它应该在段落的开始。（==*==没有特别意思在段落中间）

Copyright symbol: \251, \xA9, \u00a9.

Latin-1字符 （APT文档使用的编码）可能被指定他们编码使用反斜杠跟着使用1个三位的八进制或使用==\x==符号，NN是两个十六进制数字。

Unicode 编码可能被指定他们编码使用\u NNNN符号，NNNN是4位十六进制数字。

注释

~~Commented out.

经过两个符号发现的文本（~ ~）被忽略到行末。

为了使它们在其他段落中脱颖而出，经常使用一行“下划线”的标题。

------
            Title
            ------
            Author
            ------
             Date

  Paragraph 1, line 1.
  Paragraph 1, line 2.

  Paragraph 2, line 1.
  Paragraph 2, line 2.

Section title

* Sub-section title

** Sub-sub-section title

*** Sub-sub-sub-section title

**** Sub-sub-sub-sub-section title

      * List item 1.

      * List item 2.

        Paragraph contained in list item 2.

            * Sub-list item 1.

            * Sub-list item 2.

      * List item 3.
        Force end of list:

      []

+------------------------------------------+
Verbatim text not contained in list item 3
+------------------------------------------+

      [[1]] Numbered item 1.

                [[A]] Numbered item A.

                [[B]] Numbered item B.

      [[2]] Numbered item 2.

  List numbering schemes: [[1]], [[a]], [[A]], [[i]], [[I]].

      [Defined term 1] of definition list.

      [Defined term 2] of definition list.

+-------------------------------+
Verbatim text
                        in a box
+-------------------------------+

  --- instead of +-- suppresses the box around verbatim text.

[Figure name] Figure caption

*----------*--------------+----------------:
| Centered | Left-aligned | Right-aligned  |
| cell 1,1 | cell 1,2     | cell 1,3       |
*----------*--------------+----------------:
| cell 2,1 | cell 2,2     | cell 2,3       |
*----------*--------------+----------------:
Table caption

  No grid, no caption:

*-----*------*
 cell | cell
*-----*------*
 cell | cell
*-----*------*

  Horizontal line:

=======================================================================

^L
  New page.

  <Italic> font. <<Bold>> font. <<<Monospaced>>> font.

  {Anchor}. Link to {{anchor}}. Link to {{http://www.pixware.fr}}.
  Link to {{{anchor}showing alternate text}}.
  Link to {{{http://www.pixware.fr}Pixware home page}}.

  Force line\
  break.

  Non\ breaking\ space.

  Escaped special characters: \~, \=, \-, \+, \*, \[, \], \<, \>, \{, \}, \\.

  Copyright symbol: \251, \xA9, \u00a9.

~~Commented out.

原创文章，转载请注明： 转载自并发编程网 – ifeve.com本文链接地址: 《Maven官方指南》APT格式

  • Trackback 关闭
  • 评论 (0)

  1. 暂无评论

return top