APT 格式

APT 代表“几乎纯文本”。APT 是一种标记语言,它通过力求简单化来消除文档编写的麻烦。它的语法更类似于纯文本,而不是大多数其他标记格式(例如 HTML)。

本文档提供了一些可用 APT 格式的示例。

重要的提醒

本文档中包含的信息对应于Xmlmind发布的原始 APT 格式。在 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
            ------
            Author
            ------
             Date

标题栏是缩进的(居中更好)。它以包含至少 3 个破折号 ( ---) 的行开头。

在第一---行之后,一行或几行连续的文本(每行后隐式换行)指定文档的标题。

该文本后面可能紧跟另一---行和一行或几行指定文档作者的连续文本。

作者子块可以可选地跟随使用相同语法的日期子块。

以下示例用于具有标题和日期但没有声明作者的文档。

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

最后一行被忽略。它只是为了使块更好。

注意:日期没有特定格式,将被解析为字符串。但我们建议使用 ISO-8601 标准,因为世界各地的日期格式各不相同:

YYYY-MM-DD

其中YYYY是公历中的年份,MM是介于 01(一月)和 12(十二月)之间的月份, DD是介于 01 和 31 之间的月份。

段落

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

  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.

列表项缩进并以星号 ( *) 开头。

比第一个列表项缩进更多的普通段落嵌套在该列表中。诸如表格(不缩进)之类的显示总是嵌套在当前列表中。

要将列表嵌套在列表中,请将其第一项缩进多于其父列表。要结束一个列表,请添加一个缩进小于当前列表的段落或列表项。

章节标题总是以列表结尾。显示无法结束列表,但[]伪元素可用于强制结束列表。

      * List item 3.
        Force end of list:

      []

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

在前面的示例中,如果没有[],逐字文本(并非所有显示都缩进)将包含在列表项 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.

编号列表项以两个方括号之间的标签开始。第一项的标签确定了整个列表的编号方案:

[[1]]
十进制编号: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.
----------------------------------------

逐字块不缩进。它以包含至少 3 个破折号 ( ---) 的非缩进行开头。它以类似的行结束。

+--而不是---在逐字文本周围绘制一个框。

与 HTML 一样,逐字文本是预先格式化的。与 HTML 不同,逐字文本被转义:在逐字显示中,标记不被 APT 处理器解释。

数字
[Figure name] Figure caption

图形块不缩进。它以方括号之间的图形名称开头。图形名称可选地后跟一些文本:图形标题。

图形名称是包含图形但没有扩展名的文件的路径名。示例:如果您的图形包含在 中/home/joe/docs/mylogo.jpeg,则图形名称为/home/joe/docs/mylogo[改变]

如果图形名称来自相对路径名(推荐做法)而不是绝对路径名,则此相对路径名被视为相对于当前 APT 文档的目录(a la HTML)而不是相对于当前工作目录。

为什么不在图形名称中保留文件扩展名?这可以通过一个例子更好地解释。您需要将 APT 文档转换为 PostScript,并且您的图形名称为/home/joe/docs/mylogo. APT 处理器将首先尝试加载/home/joe/docs/mylogo.eps. 当未找到所需格式时,APT 处理器会尝试转换现有格式之一。在我们的示例中,APT 处理器尝试转换/home/joe/docs/mylogo.jpeg为封装的 PostScript。

桌子

表格块不缩进。它以包含星号和至少 2 个破折号 ( *--) 的非缩进行开头。它以类似的行结束。

第一行不仅用于识别表格,还用于指定列对齐方式。在以下示例中,

  • 第二个星号 ( *) 用于指定第 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

行由以 开头的非缩进行分隔*--

可选的表格标题(非缩进文本)可以紧跟在表格后面。

行可能包含单行或多行单元格。|每行单元格文本通过竖线字符 ( )与相邻单元格隔开。(|如果引用,可以在单元格文本中使用:\|。)

最后一个|仅用于使桌子更好。第一个|不仅用于使表格更漂亮,还用于指定要在表格单元格周围绘制网格。

以下示例显示了一个没有网格和标题的简单表格。

*-----*------*
 cell | cell
*-----*------*
 cell | cell
*-----*------*
水平尺
=====================

包含至少 3 个等号 ( ===) 的非缩进行。

分页符
^L

包含单个换页符 (Control-L) 的非缩进行。

文本级元素

字体
  <Italic> font. <<Bold>> font. <<<Monospaced>>> font.

< 和 > 之间的文本必须以斜体显示。<< 和 >> 之间的文本必须以粗体呈现。<<< 和 >>> 之间的文本必须使用等宽、类似打字机的字体呈现。

字体元素可以出现在除其他字体元素之外的任何地方。

不建议在标题、章节标题、链接和定义的术语中使用字体元素,因为 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 }}时,链接文本文本可能与链接名称name不同。

锚/链接元素可以出现在除其他锚/链接元素之外的任何地方。

节标题是隐式定义的锚。[改变]

越线
  Force line\
  break.

反斜杠字符 ( \) 后跟换行符。

不能在标题和表格中使用换行符(它们是带有隐式换行符的面向行的块)。

非破坏空间
  Non\ breaking\ space.

反斜杠字符 ( \) 后跟空格字符。

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

在某些情况下,这些字符具有特殊含义,因此如果需要,必须按原样进行转义。它们通过在它们前面添加反斜杠来进行转义。反斜杠本身可以通过在其前面添加另一个反斜杠来进行转义。

请注意,例如,星号仅在其开始段落时才需要转义。(*在段落中间没有特殊含义。)

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

Latin-1 字符(无论 APT 文档的编码是什么)可以通过其代码使用反斜杠后跟一到三个八进制数字或使用\xNN表示法来指定,其中NN是两个十六进制数字。

Unicode 字符可以通过使用\uNNNN表示法的代码来指定,其中NNNN是四个十六进制数字。

评论
~~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.
        强制结束列表:

      []

+--------------------------------------------+
清单项目 3 中不包含逐字记录
+--------------------------------------------+

      [[1]] Numbered item 1.

                [[A]] Numbered item A.

                [[B]] Numbered item B.

      [[2]] Numbered item 2.

  列表编号方案:[[1]]、[[a]]、[[A]]、[[i]]、[[I]]。

      定义列表的[定义项1]。

      [定义项2]定义列表。

+-------------------------------+
逐字逐句
                        在盒子里
+-------------------------------+

  --- 而不是 +-- 禁止逐字文本周围的框。

[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

  没有网格,没有标题:

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

  水平线:

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

^L
  新的一页。

  <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.