PageRenderTime 30ms CodeModel.GetById 20ms RepoModel.GetById 0ms app.codeStats 0ms

/doc/Chinese/userguide-zh/userguide-zh.t2t

http://txt2tags.googlecode.com/
Unknown | 1534 lines | 1059 code | 475 blank | 0 comment | 0 complexity | 17d568d75fdc2580d9e44190ffa51893 MD5 | raw file
Possible License(s): GPL-2.0, GPL-3.0, WTFPL 
    

  1. Txt2tags用户指南

    2. 

  2. 

    3. 

  3. %%date(%Y-%m-%d)

    4. 

  4. %!target:html

    5. 

  5. %%!target: tex

    6. 

  6. %!encoding: UTF-8

    7. 

  7. %!options(html): --toc --toc-level 2 --css-sugar

    8. 

  8. %!options(tex): --toc --toc-level 2

    9. 

  9. %!options(html): --style userguide.css

    10. 

  10. 

    11. 

  11. %!preproc: IMGPATH ./img

    12. 

  12. %!preproc(tex): '^ *--------*'  ''

    13. 

  13. %!preproc(tex): '^ *========*'  ''

    14. 

  14. 

    15. 

  15. 

    16. 

  16. ========================================================

    17. 

  17. 

    18. 

  18. %%toc

    19. 

  19. 

    20. 

  20. ========================================================

    21. 

  21. 

    22. 

  22. = 关于本文 =[about]

    23. 

  23. 

    24. 

  24. 本文根据[txt2tags http://txt2tags.org/]（当前版本为2.5）的**用户指南**英文版翻译而来，读者可通过以下途径获得用户指南的英文原版：

    25. 

  25. - 用户指南官方网址：http://txt2tags.org/userguide

    26. 

  26. - 用户指南的PDF版本：http://txt2tags.org/userguide/userguide.pdf

    27. 

  27. 

    28. 

  28. 

    29. 

  29. 本译文依照[创作共用约定（署名-非商业性使用-相同方式共享）3.0 http://creativecommons.org/licenses/by-nc-sa/3.0]发布。

    30. 

  30. 

    31. 

  31. ========================================================

    32. 

  32. 

    33. 

  33. + 第一部分  初识txt2tags +[chap1-intro]

    34. 

  34. 

    35. 

  35. 本章为概述，介绍txt2tags程序的用途和特色。

    36. 

  36. 

    37. 

  37. ++ 第一个可能的问题 ++[1st-question]

    38. 

  38. 

    39. 

  39. +++ txt2tags是什么？ +++

    40. 

  40. 

    41. 

  41. txt2tags是一个文本格式化和转换工具，能够将带有特定标记的纯文本文件转换为支持的任意一种目标格式，包括：

    42. 

  42. 

    43. 

  43. - HTML文档

    44. 

  44. - XHTML文档

    45. 

  45. - SGML文档

    46. 

  46. - LaTeX源文件

    47. 

  47. - Unix手册页（man page）

    48. 

  48. - MagicPoint演示文稿

    49. 

  49. - Wikipedia维基百科页面

    50. 

  50. - Google Wiki 页面

    51. 

  51. - DokuWiki页面

    52. 

  52. - MoinMoin页面

    53. 

  53. - PageMaker 6.0 文档

    54. 

  54. - 纯文本文件

    55. 

  55. 

    56. 

  56. 

    57. 

  57. +++ 为什么使用txt2tags？ +++

    58. 

  58. 

    59. 

  59. 你会发现txt2tags十分有用，如果你：

    60. 

  60. 

    61. 

  61. - 需要将文档以不同格式发布

    62. 

  62. - 需要以不同格式维护文档的更新

    63. 

  63. - 撰写技术文档或者手册

    64. 

  64. - 需要用你不熟悉的某种格式撰写文档

    65. 

  65. - 对于某种文档格式缺少一个专门的编辑器

    66. 

  66. - 想用一个简单的文本编辑器维护和更新你的文档

    67. 

  67. 

    68. 

  68. 

    69. 

  69. 而最大的诱人之处在于：

    70. 

  70. 

    71. 

  71. - 节省时间，专注于 **内容**，抛开 **格式**

    72. 

  72. 

    73. 

  73. 

    74. 

  74. +++ 相较于其他工具，txt2tags有哪些优点？ +++

    75. 

  75. 

    76. 

  76. | **源文件可读性好** | txt2tags的标记非常简单，使得源文件几乎是自然语言。

    77. 

  77. | **目标文件可读性好** | 与源文件一样，生成的目标文件带有缩进和较短的行长度，可读性好。

    78. 

  78. | **一致的标记** | txt2tags的标记是独特的，足以适应各种文档而不至于与文档内容产生混淆。

    79. 

  79. | **一致的规则** | 每种标记与其对应的规则是一一对应的，不存在“例外”或“特殊情形”

    80. 

  80. | **结构简单** | 所有支持的格式都是**简单的**，不带有附加选项或者复杂的修饰。标记只是标记而已，没有任何选项。

    81. 

  81. | **易于学习** | 由于简单的标记和可读的源文件，txt2tags的学习曲线非常的“用户友好”。

    82. 

  82. | **漂亮的示例** | 无论用txt2tags编写简单还是复杂的文档，包含在软件包中的**示例文件**都给出了生动实用的例子。

    83. 

  83. | **有用的工具** | 包含于软件包中的**语法规则文件**帮助你写出没有语法错误的文档（适用于vim, emacs, nano和kate）。

    84. 

  84. | **三种用户接口** | 用//Tk//编写的**图形接口**，可供远程和内部网使用的**网页接口**，以及共高级用户和脚本使用的**命令行接口**。

    85. 

  85. | **脚本** | 有经验的用户能够通过完全的命令行模式进行**自动任务**，以及对转换后的文件进行**后编辑**。

    86. 

  86. | **下载、运行和跨平台** | txt2tags只是一个简单的**Python 脚本**，毋需编译或下载额外的模块，因此在各种*NIX、Linux、Windows和Macintosh主机上均能完美运行。

    87. 

  87. | **时常更新** | 活跃的邮件列表有用户提供修正和改进。作者本人在工作和业余也在使用txt2tags，因此开发不会无故终止。

    88. 

  88. 

    89. 

  89. 

    90. 

  90. +++ 我需要为此付费吗？ +++

    91. 

  91. 

    92. 

  92.             ||  当然不需要！ |

    93. 

  93. 

    94. 

  94. txt2tags在GPL许可证下发布，并且完全免费。

    95. 

  95. 

    96. 

  96. ++ 支持的文档结构 ++[formats]

    97. 

  97. 

    98. 

  98. 以下列出了txt2tags支持的文档结构。

    99. 

  99. 

    100. 

  100. - 头部（文档标题、作者、日期）

    101. 

  101. - 章节标题（带有/不带编号）

    102. 

  102. - 段落

    103. 

  103. - 字体美化

    104. 

  104.  - 粗体

    105. 

  105.  - 斜体

    106. 

  106.  - 下划线

    107. 

  107.  - 删除线

    108. 

  108. - 等宽字体（完全引用）

    109. 

  109.  - 段落内的等宽字体

    110. 

  110.  - 等宽的行

    111. 

  111.  - 等宽的区域（多行）

    112. 

  112. - 引用

    113. 

  113. - 链接

    114. 

  114.  - URL/Internet链接

    115. 

  115.  - e-mail链接

    116. 

  116.  - 本地链接

    117. 

  117.  - 命名的链接

    118. 

  118. - 列表

    119. 

  119.  - 以符号引导的列表

    120. 

  120.  - 编号的列表

    121. 

  121.  - 定义列表

    122. 

  122. - 水平分隔线

    123. 

  123. - 图片（智能对齐）

    124. 

  124. - 表格（带/不带边框，智能对齐，列贯穿）

    125. 

  125. - 针对原文域的特殊标记（不解析）

    126. 

  126. - 对当前日期的特殊宏定义（能灵活的改变格式）

    127. 

  127. - 注释（作者备注；TODO；FIXME）

    128. 

  128. 

    129. 

  129. 

    130. 

  130. ++ 支持的目标文件格式 ++[targets]

    131. 

  131. 

    132. 

  132. : **HTML**

    133. 

  133. HTML是众所周知的格式（提示：Internet）。

    134. 

  134. 

    135. 

  135. Txt2tags能生成干净漂亮，源文件可读的HTML文档，不使用JavaScript、框架或是其他无效的、简洁的技术文档所不需要的格式化技术，但是可以使用独立的CSS文件。txt2tags生成的代码符合“//HTML 4.0 Transitional//”标准。

    136. 

  136. 

    137. 

  137. 自2.0版起，txt2tags生成的HTML代码100%通过[w3c validator validator.w3.org]的校验。

    138. 

  138. 

    139. 

  139. : **XHTML**

    140. 

  140. 新一代的HTML，具有更严格的语法——所有的标记都必须闭合，这使得代码更易理解和解析。大体上来说，可以将其看做HTML。Txt2tags生成的代码符合“//XHTML 1.0 Transitional//”标准。

    141. 

  141. 

    142. 

  142. 自2.0版起，txt2tags生成的XHTML代码100%通过[w3c validator validator.w3.org]的校验。

    143. 

  143. 

    144. 

  144. : **SGML**

    145. 

  145. 格式转换软件[SGML工具 www.sgmltools.org]的通用格式。单一的SGML文件能转换为HTML、PDF、PS、info、LaTeX、Lyx、rtf以及XML格式的文档。SGML2* 工具还能自动生成目录表，以及按照章节将文件分割为子页（sgml2html）。

    146. 

  146. 

    147. 

  147. Txt2tags生成的SGML文件为Linux系统文档格式，通过SGML2*工具能够直接转换，而毋需任何额外的目录文件或是SGML那些恼人的要求。

    148. 

  148. 

    149. 

  149. : **LATEX**

    150. 

  150. 超出你想象的强大格式，学术论文的通用格式。用它能生成整本的书、复杂的公式以及任何复杂的文字格式，然而，如果你打算手写那些标记，就准备掉头发吧……

    151. 

  151. 

    152. 

  152.   Txt2tags将为你处理所有的细节和例外情形，完成能够直接使用的LaTeX文档，你只需考虑文字内容。

    153. 

  153. 

    154. 

  154. : **LOUT**

    155. 

  155. 与LaTeX非常相似，但是以“@”代替“\”作为命令引导符，同时尽量避免使用括号。它“一切皆对象”的处理方式使得标记更加健壮。

    156. 

  156. 

    157. 

  157. Txt2tags能生成可以直接使用的文件，通过“lout”命令即可转换为PDF或PS文件。

    158. 

  158. 

    159. 

  159. : **MAN**

    160. 

  160. UNIX手册页。

    161. 

  161. 

    162. 

  162. 文档格式产生消亡，来来去去，UNIX手册页却存活多年，始终坚挺。

    163. 

  163. 

    164. 

  164. 有各种工具可以生成手册页文档，但是txt2tags自有其优势：一个源文件，多种产出物。因此，手册页的内容还能转换为HTML、MagicPoint演示文稿，等等。

    165. 

  165. 

    166. 

  166. : **MGP**

    167. 

  167. [MagicPoint www.mew.org/mgp]是一个非常方便的幻灯片工具（就如同Microsoft PowerPoint）。它使用标记语言来定义每一屏显示，因此你可以使用 vi/emacs/记事本 这样的文本编辑器来完成复杂的幻灯片。

    168. 

  168. 

    169. 

  169. Txt2tags为你完成所有被ISO-8859标准所支持的字体和外观的定义，生成的.mgp文件能够直接使用。

    170. 

  170. 

    171. 

  171. **HOTSPOT 1:** txt2tags在生成的.mgp文件中使用XFree86 Type1字体！因此你的幻灯片毋需额外配合TrueType字体。

    172. 

  172. 

    173. 

  173. **HOTSPOT 2:** 字体颜色的定义简洁，即使在只有简陋调色板的系统中（比如``startx -- -bpp 8``），幻灯片依然美观。

    174. 

  174. 

    175. 

  175. 你需要做的只是：转换，然后使用。毋需任何修复或是其他额外的工作。

    176. 

  176. 

    177. 

  177. : **WIKI**

    178. 

  178. 想必你一定听说过[维基百科(Wikipedia) wikipedia.org]吧？现在你不必另外学习一种新的标记语法，txt2tags将为你把标记文本转换为维基百科的格式。

    179. 

  179. 

    180. 

  180. : **GWIKI**

    181. 

  181. 使你能轻松的将项目文档粘贴到[Google Code code.google.com] Wiki。

    182. 

  182. 

    183. 

  183. : **DOKU**

    184. 

  184. [DokuWiki http://wiki.splitbrain.org/wiki:dokuwiki]是一种遵从标准并且易于使用的Wiki，被设计来创建各种类型的文档，其目标群体包括开发团队、工作组以及小型公司。其语法简洁而强大，确保数据文件脱离Wiki仍然保有可读性，同时简化结构化文本的创建，所有的数据都以纯文本文件格式存储——毋需数据库。

    185. 

  185. 

    186. 

  186. : **MOIN**

    187. 

  187. [MoinMoin moinmo.in]是什么？它是一种[WikiWiki www.c2.com/cgi/wiki]！

    188. 

  188. 

    189. 

  189. Moin的语法是有些乏味儿的，你必须不断的``{{{'''''adding braces and quotes'''''}}}``。Txt2tags为你带来简单的标记和统一的解决方案：一个源文件，多种产出物。

    190. 

  190. 

    191. 

  191. : **PM6**

    192. 

  192. 我估猜你不会知道这是 Adobe PageMaker 6.0 独有的标记语言！它包含了样式、颜色表、美化、以及绝大部分PageMaker中的鼠标点击特性。你可以通过“Import Tagged text”菜单项来使用它。从记录上来看，它具有“类HTML”的标记格式。

    193. 

  193. 

    194. 

  194. Txt2tags能生成所有的标记，并且定义好丰富而有效的导言以设置段落样式和格式——这个部分通常是让人头疼的。**特别提醒：**不能有断行！每个段落必须是单独一行。

    195. 

  195. 

    196. 

  196. （作者按：//笔者的《[regular expression's book http://guia-er.sf.net]》这本书的葡萄牙语版就是用VI编辑，再用txt2tags转换为PageMaker格式然后付印的。//）

    197. 

  197. 

    198. 

  198. : **TXT**

    199. 

  199. 纯文本，唯一的真实格式。

    200. 

  200. 

    201. 

  201. 尽管txt2tags的标记非常直观而且不显眼，你仍然可以选择移除它们——只需将文件转换为纯文本即可。

    202. 

  202. 

    203. 

  203. 在源文件中，标题添加下划线，而文本则是左对齐的。

    204. 

  204. 

    205. 

  205. 

    206. 

  206. ++ 目标文件结构支持一览 ++[struct-support]

    207. 

  207. 

    208. 

  208.   || 结构        | html | xhtml | sgml | tex | lout | man | mgp | wiki | gwiki | doku | moin | pm6 | txt |

    209. 

  209.   | 头部           |  Y   |   Y   |  Y   |  Y  |  Y   |  Y  |  Y  |  -   |   -   |  -   |  -   |  N  |  Y  |

    210. 

  210.   | 章节标题     |  Y   |   Y   |  Y   |  Y  |  Y   |  Y  |  Y  |  Y   |   Y   |  Y   |  Y   |  Y  |  Y  |

    211. 

  211.   | 段落        |  Y   |   Y   |  Y   |  Y  |  Y   |  Y  |  Y  |  Y   |   Y   |  Y   |  Y   |  Y  |  Y  |

    212. 

  212.   | 粗体字              |  Y   |   Y   |  Y   |  Y  |  Y   |  Y  |  Y  |  Y   |   Y   |  Y   |  Y   |  Y  |  -  |

    213. 

  213.   | 斜体字            |  Y   |   Y   |  Y   |  Y  |  Y   |  Y  |  Y  |  Y   |   Y   |  Y   |  Y   |  Y  |  -  |

    214. 

  214.   | 下划线字体         |  Y   |   Y   |  -   |  Y  |  Y   |  -  |  Y  |  Y   |   -   |  Y   |  Y   |  Y  |  -  |

    215. 

  215.   | 删除线字体            |  Y   |   Y   |  N   |  Y  |  -   |  -  |  -  |  Y   |   Y   |  Y   |  Y   |  N  |  -  |

    216. 

  216.   | 等宽字体   |  Y   |   Y   |  Y   |  Y  |  Y   |  -  |  Y  |  Y   |   Y   |  Y   |  Y   |  Y  |  -  |

    217. 

  217.   | 未格式化行     |  Y   |   Y   |  Y   |  Y  |  Y   |  Y  |  Y  |  Y   |   Y   |  Y   |  Y   |  Y  |  -  |

    218. 

  218.   | 未格式化区域     |  Y   |   Y   |  Y   |  Y  |  Y   |  Y  |  Y  |  Y   |   Y   |  Y   |  Y   |  Y  |  -  |

    219. 

  219.   | 引用区域       |  Y   |   Y   |  Y   |  Y  |  Y   |  Y  |  Y  |  Y   |   Y   |  Y   |  Y   |  Y  |  Y  |

    220. 

  220.   | 超链接    |  Y   |   Y   |  Y   |  -  |  -   |  -  |  -  |  Y   |   Y   |  Y   |  Y   |  -  |  -  |

    221. 

  221.   | e-mail链接      |  Y   |   Y   |  Y   |  -  |  -   |  -  |  -  |  Y   |   Y   |  Y   |  Y   |  -  |  -  |

    222. 

  222.   | 本机链接       |  Y   |   Y   |  Y   |  N  |  N   |  -  |  -  |  N   |   N   |  Y   |  Y   |  -  |  -  |

    223. 

  223.   | 命名链接       |  Y   |   Y   |  Y   |  -  |  -   |  -  |  -  |  Y   |   Y   |  Y   |  Y   |  -  |  -  |

    224. 

  224.   | 列表     |  Y   |   Y   |  Y   |  Y  |  Y   |  Y  |  Y  |  Y   |   Y   |  Y   |  Y   |  Y  |  Y  |

    225. 

  225.   | 计数列表     |  Y   |   Y   |  Y   |  Y  |  Y   |  Y  |  Y  |  Y   |   Y   |  Y   |  Y   |  Y  |  Y  |

    226. 

  226.   | 定义列表   |  Y   |   Y   |  Y   |  Y  |  Y   |  Y  |  N  |  Y   |   -   |  -   |  Y   |  N  |  Y  |

    227. 

  227.   | 水平线   |  Y   |   Y   |  -   |  Y  |  Y   |  -  |  Y  |  Y   |   -   |  Y   |  Y   |  N  |  Y  |

    228. 

  228.   | 图片             |  Y   |   Y   |  Y   |  Y  |  Y   |  -  |  Y  |  Y   |   Y   |  Y   |  Y   |  N  |  -  |

    229. 

  229.   | 表格             |  Y   |   Y   |  Y   |  Y  |  N   |  Y  |  N  |  Y   |   Y   |  Y   |  Y   |  N  |  N  |

    230. 

  230.   || 附加结构           | html | xhtml | sgml | tex | lout | man | mgp | wiki | gwiki | doku | moin | pm6 | txt |

    231. 

  231.   | 图片对齐       |  Y   |   Y   |  N   |  N  |  Y   |  -  |  Y  |  Y   |   -   |  Y   |  N   |  N  |  -  |

    232. 

  232.   | 单元格对齐  |  Y   |   Y   |  Y   |  Y  |  N   |  Y  |  N  |  N   |   -   |  -   |  Y   |  N  |  N  |

    233. 

  233.   | 跨列单元格 |  Y   |   Y   |  N   |  N  |  N   |  N  |  N  |  N   |   -   |  -   |  N   |  N  |  N  |

    234. 

  234. 

    235. 

  235.   ||      | 图例

    236. 

  236.   | **Y** | 支持

    237. 

  237.   | **N** | 不支持（后续版本可能会支持）

    238. 

  238.   | **-** | 不支持（在该目标格式中不存在）

    239. 

  239. 

    240. 

  240. 

    241. 

  241. ++ 三种用户接口：GUI、网页和命令行 ++[interfaces]

    242. 

  242. 

    243. 

  243. 不同用户的需求和使用环境不同，txt2tags相应的也具有灵活的执行方式。

    244. 

  244. 

    245. 

  245. 程序有三种用户接口，每一种各有其目标和特性：

    246. 

  246. 

    247. 

  247. - **图形用户接口（GUI）**：使用Tk写成，支持窗口环境和鼠标点击。

    248. 

  248. - **网页**：使用PHP开发，支持通过浏览器运行txt2tags，而毋需安装任何客户端程序。

    249. 

  249. - **命令行**：程序的核心，使用Python开发，所有的特性都包含于命令行选项之中。

    250. 

  250. 

    251. 

  251. 

    252. 

  252. +++ 基于Tk的图形用户接口 +++[tk-interface]

    253. 

  253. 

    254. 

  254. 自1.0版本开始，txt2tags就有一个能工作于Linux、Windows、Mac以及其他操作系统之上的图形用户接口。

    255. 

  255. 

    256. 

  256. 程序能自动检测你的系统能否显示图形，如果可以，则不带任何参数的命令调用时运行图形接口。你也可以通过命令行参数 ``--gui`` 强制运行图形接口。当某些资源缺失时，程序给出错误信息。

    257. 

  257. 

    258. 

  258. 	提示：Tkinter是必须的。因为Python的标准发布总是包含它，实际上

    259. 

  259. 	你的系统中应该已经有了。

    260. 

  260. 

    261. 

  261. 图形界面的使用相当的简洁和直观：

    262. 

  262. 

    263. 

  263.            [IMGPATH/gui.png] 

    264. 

  264. 

    265. 

  265. + 加载本机的.t2t文件，其内部定义的选项将自动识别。

    266. 

  266. + 如果目标格式为空，必须在此处指定。

    267. 

  267. + 此外还有一些选项可以附加选择，但并非必须。

    268. 

  268. + 最后，点击“Convert!”按钮。

    269. 

  269. 

    270. 

  270. 一个有用的选项是“//Dump to screen//”，输出结果不会写到文件，而是显示于屏幕上，以便检查，确认无误之后再输出到文件存储。

    271. 

  271. 

    272. 

  272. 界面的默认颜色可以通过修改 ``~/.txt2tagsrc`` 文件的 ``%!guicolors`` 设定来更改。比如：

    273. 

  273. 

    274. 

  274. ```

    275. 

  275. % set my own colors for the graphical interface (bg1, fg1, bg2, fg2)

    276. 

  276. %!guicolors: blue white brown yellow

    277. 

  277. ```

    278. 

  278. 

    279. 

  279. 

    280. 

  280. +++ 在线方式 +++

    281. 

  281. 

    282. 

  282. 基于Web的界面可以通过互联网地址http://txt2tags.org/online.php来访问，你可以在下载之前先试用txt2tags。

    283. 

  283. 

    284. 

  284.         [IMGPATH/web.png] 

    285. 

  285. 

    286. 

  286. Web接口也可以部署于本地局域网（intranet）内，免去在每台机器上安装txt2tags的麻烦。

    287. 

  287. 

    288. 

  288. 

    289. 

  289. +++ 命令行 +++

    290. 

  290. 

    291. 

  291. 对于有经验的命令行用户来说，``--help`` 选项提供的帮助信息应该足够了：

    292. 

  292. 

    293. 

  293. ```

    294. 

  294. Usage: txt2tags [OPTIONS] [infile.t2t ...]

    295. 

  295. 

    296. 

  296.   -t, --target=TYPE   set target document type. currently supported:

    297. 

  297.                       html, xhtml, sgml, tex, lout, man, mgp, wiki,

    298. 

  298.                       gwiki, doku, moin, pm6, txt

    299. 

  299.   -i, --infile=FILE   set FILE as the input file name ('-' for STDIN)

    300. 

  300.   -o, --outfile=FILE  set FILE as the output file name ('-' for STDOUT)

    301. 

  301.   -n, --enum-title    enumerate all title lines as 1, 1.1, 1.1.1, etc

    302. 

  302.   -H, --no-headers    suppress header, title and footer contents

    303. 

  303.       --headers       show header, title and footer contents (default ON)

    304. 

  304.       --encoding      set target file encoding (utf-8, iso-8859-1, etc)

    305. 

  305.       --style=FILE    use FILE as the document style (like HTML CSS)

    306. 

  306.       --css-sugar     insert CSS-friendly tags for HTML and XHTML targets

    307. 

  307.       --css-inside    insert CSS file contents inside HTML/XHTML headers

    308. 

  308.       --mask-email    hide email from spam robots. x@y.z turns <x (a) y z>

    309. 

  309.       --toc           add TOC (Table of Contents) to target document

    310. 

  310.       --toc-only      print document TOC and exit

    311. 

  311.       --toc-level=N   set maximum TOC level (depth) to N

    312. 

  312.       --rc            read user config file ~/.txt2tagsrc (default ON)

    313. 

  313.       --gui           invoke Graphical Tk Interface

    314. 

  314.   -q, --quiet         quiet mode, suppress all output (except errors)

    315. 

  315.   -v, --verbose       print informative messages during conversion

    316. 

  316.   -h, --help          print this help information and exit

    317. 

  317.   -V, --version       print program version and exit

    318. 

  318.       --dump-config   print all the config found and exit

    319. 

  319. 

    320. 

  320. Turn OFF options:

    321. 

  321.      --no-outfile, --no-infile, --no-style, --no-encoding, --no-headers

    322. 

  322.      --no-toc, --no-toc-only, --no-mask-email, --no-enum-title, --no-rc

    323. 

  323.      --no-css-sugar, --no-css-inside, --no-quiet

    324. 

  324. 

    325. 

  325. Example:

    326. 

  326.      txt2tags -t html --toc myfile.t2t

    327. 

  327. 

    328. 

  328. By default, converted output is saved to 'infile.<target>'.

    329. 

  329. Use --outfile to force an output file name.

    330. 

  330. If  input file is '-', reads from STDIN.

    331. 

  331. If output file is '-', dumps output to STDOUT.

    332. 

  332. ```

    333. 

  333. 

    334. 

  334. ++++ 示例 ++++

    335. 

  335. 

    336. 

  336. 假设你已经编写好一个正确标记的文件 ``file.t2t``，现在我们来尝试一些转换。

    337. 

  337. 

    338. 

  338. | **转换为HTML**                 | ``$ txt2tags -t html file.t2t``

    339. 

  339. | **转换为HTML，使用输出重定向** | ``$ txt2tags -t html -o - file.t2t > file.html``

    340. 

  340. |  | .

    341. 

  341. | **包含目录表**                 | ``$ txt2tags -t html --toc file.t2t``

    342. 

  342. | **带数字编号的目录表**         | ``$ txt2tags -t html --toc --enum-title file.t2t``

    343. 

  343. |  | .

    344. 

  344. | **内容概览**                   | ``$ txt2tags --toc-only file.t2t``

    345. 

  345. | **编号的概览**                 | ``$ txt2tags --toc-only --enum-title file.t2t``

    346. 

  346. |  | .

    347. 

  347. | **从标准输入读取一行**         | ``$ echo -e "\n**bold**" | txt2tags -t html --no-headers -``

    348. 

  348. | **Email地址识别测试**          | ``$ echo -e "\njohn.wayne@farwest.com" | txt2tags -t txt --mask-email --no-headers -``

    349. 

  349. | **转换后编辑**                 | ``$ txt2tags -t html -o- file.t2t | sed "s/<BODY .*/<BODY BGCOLOR=green>/" > file.html``

    350. 

  350. 

    351. 

  351. 

    352. 

  352. 	提示：从1.6版本起，前处理和后处理可以通过 ``%!preproc`` 和

    353. 

  353. 	``%!postproc`` 宏来完成。

    354. 

  354. 

    355. 

  355. --------------------------------------------------------

    356. 

  356. 

    357. 

  357. + 第二部分 如何开始？ +[install]

    358. 

  358. 

    359. 

  359. 下载然后运行——一切就是这么简单。

    360. 

  360. 

    361. 

  361. ++ 下载、安装Python ++[download-python]

    362. 

  362. 

    363. 

  363. 首先你必须下载安装Python解释器，如果你的系统已经安装过Python，请跳过本节。

    364. 

  364. 

    365. 

  365. Python是一种极好的编程语言，能够跨平台的在Windows、Linux、UNIX、Macintosh以及其他的操作系统上运行。你可以从[Python主页 http://www.python.org/]找到安装文件以及安装指南。Txt2tags运行要求Python 2.0以后的版本。

    366. 

  366. 

    367. 

  367. 如果你不确定是否已经安装过Python，请打开一个控制台（tty、xterm、MSDOS），输入命令 ``python``，如果Python并未安装，系统会给出错误信息。

    368. 

  368. 

    369. 

  369. ++ 下载txt2tags ++[download-txt2tags]

    370. 

  370. 

    371. 

  371. Txt2tags的项目主页是http://txt2tags.org。全部程序文件打包成一个tarball压缩文件（.tgz 文件），你可以使用大多数的压缩工具来提取（包括WinZip）。请下载**最新**的版本，早期版本仅仅作为历史存档之用。

    372. 

  372. 

    373. 

  373. ++ 安装txt2tags ++[install-txt2tags]

    374. 

  374. 

    375. 

  375. 事实上，txt2tags只是一个单文件的Python脚本，毋需安装。

    376. 

  376. 

    377. 

  377. 运行程序需要的唯一一个文件是脚本 ``txt2tags``，压缩包内的其他文件是软件的文档、示例以及一些工具。

    378. 

  378. 

    379. 

  379. 最低级的使用txt2tags的方法是直接通过Python来调用：

    380. 

  380. 

    381. 

  381. ``` prompt$ python txt2tags

    382. 

  382. 

    383. 

  383. 如果想将 txt2tags 作为一个能够直接运行的程序“安装”到系统，请将 txt2tags 脚本复制（或者创建一个链接）到系统 PATH 变量定义的目录，并且确认系统能够运行它。

    384. 

  384. 

    385. 

  385. : UNIX/Linux/Mac

    386. 

  386. 将脚本文件赋予执行权限（``chmod +x txt2tags``），然后复制到 $PATH 变量定义的目录下（比如：``cp txt2tags /usr/local/bin``）。

    387. 

  387. 

    388. 

  388. : Windows

    389. 

  389. 重命名脚本文件，添加 .py 作为扩展名（命令行下执行：``ren txt2tags txt2tags.py``），然后复制到系统 PATH 环境变量定义的路径下（比如：``copy txt2tags.py C:\WINNT``）

    390. 

  390. 

    391. 

  391. 

    392. 

  392. 如果想要使用图形用户接口，你可以创建一个桌面启动器（快捷方式）。

    393. 

  393. 

    394. 

  394. +++ 为Windows用户专门打包的安装程序 +++

    395. 

  395. 

    396. 

  396. 对于Windows用户，txt2tags还有两个打包好的安装程序，你只需点击鼠标即可完成安装：

    397. 

  397. 

    398. 

  398. - 单独的txt2tags脚本，针对已经安装过Python解释器的系统。

    399. 

  399. - 独立运行的版本，毋需另外安装Python解释器（包含一个嵌入的版本）。

    400. 

  400. 

    401. 

  401. 

    402. 

  402. 你可以访问 //Txt2tags-Win// 主页下载安装包：http://txt2tags-win.sf.net/

    403. 

  403. 

    404. 

  404. ++ 安装编辑器的语法高亮文件 ++

    405. 

  405. 

    406. 

  406. Txt2tags提供适合以下编辑器使用的语法高亮文件：

    407. 

  407. 

    408. 

  408. - Vim (www.vim.org)

    409. 

  409. - Emacs (www.emacs.org)

    410. 

  410. - Nano (www.nano-editor.org)

    411. 

  411. - Kate (http://kate.kde.org)

    412. 

  412. - gedit ( http://www.gnome.org/projects/gedit/)

    413. 

  413. - TextMate (http://macromates.com/ )

    414. 

  414. 

    415. 

  415. 

    416. 

  416. 语法高亮文件包含全部txt2tags标记和规则，以帮助用户编写出无误的文档——正确书写的标记将以彩色显示。

    417. 

  417. 

    418. 

  418.         |   [IMGPATH/vim.png] 

    419. 

  419.         |  用Vim打开示例文件 

    420. 

  420. 

    421. 

  421. 语法文件对于不同的编辑器有不同的安装过程，请参考语法文件的头部说明和编辑器的文档。

    422. 

  422. 

    423. 

  423. --------------------------------------------------------

    424. 

  424. 

    425. 

  425. + 第三部分 第一个文档 +[your-1st-doc]

    426. 

  426. 

    427. 

  427. ++ 先利其器 ++

    428. 

  428. 

    429. 

  429. 你需要三件工具来完成你的第一次转换尝试：txt2tags，一个文本编辑器和一个网络浏览器。

    430. 

  430. 

    431. 

  431. + 确认一下txt2tags是否已经安装并且能够正确运行。

    432. 

  432.   - **命令行方式**：执行“``txt2tags``”命令，程序会返回一个“缺少输入文件（Missing input file）”的信息。如果不能正确运行，尝试使用“``python /path/to/txt2tags``”，甚至“``/path/to/python /path/to/txt2tags``”以防止Python不在环境变量定义的路径中。

    433. 

  433.   - **图形化操作**：点击程序图标启动图形界面。

    434. 

  434. + 开启你喜欢的文本编辑器——任何一个都行，无论是古老的 VI，还是 M$ Word，乃至 OpenOffice.org。用编辑器创建一个空文档作为你的第一个txt2tags源文件。

    435. 

  435. + 启动你偏爱的浏览器，用来查看转换得到的HTML网页。

    436. 

  436. 

    437. 

  437. 

    438. 

  438. ++ 编写文档头部 ++

    439. 

  439. 

    440. 

  440. + 在编辑器中，在第一行写上文档的主标题：//我的第一个文档//

    441. 

  441. + 在第二行写上子标题：//txt2tags测试//

    442. 

  442. + 然后在第三行写上时间，比如：//星期日，2009//

    443. 

  443. 

    444. 

  444. 

    445. 

  445. 如果一切正常，现在你可以看到一个包含三行内容的文档：

    446. 

  446. 

    447. 

  447. ```

    448. 

  448. 我的第一个文档

    449. 

  449. txt2tags测试

    450. 

  450. 星期日，2009

    451. 

  451. ```

    452. 

  452. 

    453. 

  453. 这只是一般文档的一部分，但是我们已经可以用它来尝试一下转换工作了。

    454. 

  454. 

    455. 

  455. 将文档以文件名 ``test.txt`` 保存，记得要记住保存的路径，因为一会儿你要用到它。

    456. 

  456. 

    457. 

  457. ++ 第一次转换——图形界面操作 ++

    458. 

  458. 

    459. 

  459. 如果你使用命令行，请跳过本节，直接阅读下一节。

    460. 

  460. 

    461. 

  461. 如果你使用图形界面，请跟着我做：

    462. 

  462. 

    463. 

  463.         [IMGPATH/firstdoc.png] 

    464. 

  464. 

    465. 

  465. + 点击“Browse”按钮，选择你刚才保存的 ``test.txt`` 文件。

    466. 

  466. + 回到第一个窗口，在“Target document type”下拉菜单中选择“HTML page”。

    467. 

  467. + 点击“Convert!”按钮。

    468. 

  468. 

    469. 

  469. 

    470. 

  470.         [IMGPATH/firstdoc-done.png] 

    471. 

  471. 

    472. 

  472. 这时会弹出一个对话框，告诉你文件已经成功的转换了。生成的HTML文件与源文件在同一个文件夹下，以“html”为扩展名。

    473. 

  473. 

    474. 

  474. 

    475. 

  475. ++ 第一次转换——命令行方式 ++

    476. 

  476. 

    477. 

  477. 如果你使用图形界面，请跳过本节直接阅读下一节。

    478. 

  478. 

    479. 

  479. 如果你使用命令行方式，请切换到源文件所在的目录，执行：

    480. 

  480. 

    481. 

  481. ``` txt2tags --target html test.txt

    482. 

  482. 

    483. 

  483. 请注意：在命令的各部分中间以空格分隔，但是在选项字符串“``--target``”内部不能有空格，这个选项后面紧跟着字符串“``html``”，告诉程序你想要的目标文件格式。最后一部分是源文件的文件名。

    484. 

  484. 

    485. 

  485. 如果转换正常完成，结果会存储到文件 ``test.html`` 中，同时给出“//txt2tags wrote test.html//”的信息。如果不是这样，程序会报错，提示你可能出错了，请仔细检查一下。

    486. 

  486. 

    487. 

  487. 一个示例：

    488. 

  488. 

    489. 

  489. ```

    490. 

  490. prompt$ txt2tags --target html test.txt

    491. 

  491. txt2tags wrote test.html

    492. 

  492. prompt$

    493. 

  493. ```

    494. 

  494. 

    495. 

  495. ++ 查看结果 ++

    496. 

  496. 

    497. 

  497. 用浏览器打开文件 ``test.html`` 以检查是否正常。

    498. 

  498. 

    499. 

  499.         [IMGPATH/firstdoc-html.png] 

    500. 

  500. 

    501. 

  501. 看见结果了吗！你只是简单的输入了三行文字，txt2tags则为你完成了所有设置HTML文件头部信息的工作：对齐方式、大小、间隔以及外观。文档的主标题同时也出现在了浏览器的标题栏中。

    502. 

  502. 

    503. 

  503.   || 你只需输入文本，txt2tags帮你搞定一切 ;) |

    504. 

  504. 

    505. 

  505. 提示：txt2tags生成的HTML页还能使用外部CSS，以实现对页面外观100%的定制。

    506. 

  506. 

    507. 

  507. ++ 编写文档体 ++

    508. 

  508. 

    509. 

  509. 现在返回文本编辑器进行下一步：撰写文档的内容。你可以像平日里撰写电子邮件一样的输入文字，毋需特别的“标记”，txt2tags会自动识别出段落和列表。

    510. 

  510. 

    511. 

  511. 然后，再一次：保存、转换再查看结果。这就是txt2tags文档的编写流程。你可以把精力放在内容上，更快的完成文件的编写——毋需点鼠标，毋需菜单，没有窗口，没有什么来分散你的注意力。

    512. 

  512. 

    513. 

  513. 假设文件 ``test.txt`` 中写上了如下的内容，完全的纯文本，将它们跟生成的HTML文件做一个对比：

    514. 

  514. ```

    515. 

  515. 我的第一个文档

    516. 

  516. txt2tags测试

    517. 

  517. 星期日，2009

    518. 

  518. 

    519. 

  519. 现在我们来试一试txt2tags好了。我也不晓得该写点啥……

    520. 

  520. 

    521. 

  521. 唔……好吧，列一下我马上该去做的事情：

    522. 

  522. - 洗个澡

    523. 

  523. - 吃块批萨

    524. 

  524. - 去睡觉

    525. 

  525. ```

    526. 

  526. 

    527. 

  527.         [IMGPATH/firstdoc-fullhtml.png] 

    528. 

  528. 

    529. 

  529. 你毋需任何HTML语言的准备知识就能够编写出完整的主页，不必插入任何标记。进一步，同一个源文件还可以转换为其他任何txt2tags所支持的格式。

    530. 

  530. 

    531. 

  531. 除了纯文本之外，txt2tags有一些非常简单的标记来实现其他的格式和文档结构，比如**粗体**、//斜体//、标题、图片、表格，等等。举个简单的例子，``**产生粗体**``，``== 得到标题 ==``。详情请参阅[标记示例（Txt2tags Markup Demo） http://txt2tags.sourceforge.net/zh/markup-zh.html]。

    532. 

  532. 

    533. 

  533. --------------------------------------------------------

    534. 

  534. 

    535. 

  535. + 第四部分 掌握txt2tags的结构 +[concepts]

    536. 

  536. 

    537. 

  537. ++ 文档的各个部分 ++[areas]

    538. 

  538. 

    539. 

  539. Txt2tags的标记文本可以分为三个部分，每个部分各自的规则，实现不同的功能，包括：

    540. 

  540. 

    541. 

  541. : //头部域（Header Area）//

    542. 

  542. 放置文档标题、作者、版本号以及日期信息。可选区域。

    543. 

  543. : //设置域（Config Area）//

    544. 

  544. 定义全局设定，修改解析时行为（Place for general Document Settings and Parser behavior modifiers.）。可选区域。

    545. 

  545. : //主体域（Body Area）//

    546. 

  546. 文件内容。必须的区域。

    547. 

  547. 

    548. 

  548. 

    549. 

  549. 前两个区域是可选的，只有 //主体域// 是必须的。

    550. 

  550. 

    551. 

  551. 各个区域之间的分隔方式比较特别，下一章会详细描述，现在我们给出一个直观的图形化的描述：

    552. 

  552. 

    553. 

  553. ```

    554. 

  554.              ____________

    555. 

  555.             |            |

    556. 

  556.             |   HEADERS  |       1. First, the Headers

    557. 

  557.             |            |

    558. 

  558.             |   CONFIG   |       2. Then the Settings

    559. 

  559.             |            |

    560. 

  560.             |    BODY    |       3. And finally the Document Body,

    561. 

  561.             |            |

    562. 

  562.             |    ...     |          which goes until the end

    563. 

  563.             |    ...     |

    564. 

  564.             |____________|

    565. 

  565. 

    566. 

  566. ```

    567. 

  567. 

    568. 

  568. 简单的说，各个部分是这样定义的：

    569. 

  569. 

    570. 

  570.  |   **头部域**   | 文件内容的前三行；或者第一行是空白行，表示“没有头部”。

    571. 

  571.  |  **设置域**  | 紧接着头部（第四行或者第二行）开始，结束于//主体域//的开始。

    572. 

  572.  | **主体域** | 从//头部//区域之后的第一个有效的行（非注释或设置）开始。

    573. 

  573. 

    574. 

  574. 

    575. 

  575. +++ 完整的示例 +++

    576. 

  576. 

    577. 

  577. ```

    578. 

  578. My nice doc Title

    579. 

  579. Mr. John Doe

    580. 

  580. Last Updated: %%mtime(%c)

    581. 

  581. 

    582. 

  582. %! Target  : html

    583. 

  583. %! Style   : fancy.css

    584. 

  584. %! Encoding: iso-8859-1

    585. 

  585. %! Options : --toc --enum-title

    586. 

  586. 

    587. 

  587. Hi! This is my test document.

    588. 

  588. Its content will end here.

    589. 

  589. ```

    590. 

  590. 

    591. 

  591. ++ 头部域 ++[headers-area]

    592. 

  592. 

    593. 

  593. 位置：

    594. 

  594. - 固定位置：文件的**头三行**。

    595. 

  595. - 固定位置：文件的**第一行**，并且为空白行。这意味着“没有头部”。

    596. 

  596. 

    597. 

  597. 

    598. 

  598. 头部是唯一固定位置和行数的区域，总是出现在源文件的头三行。各行的内容可以随意，并没有特别的要求。不过，对于大多数的文档，推荐以下的内容作为头部：

    599. 

  599. - //第一行//：文档标题

    600. 

  600. - //第二行//：作者姓名和（或）邮件地址

    601. 

  601. - //第三行//：文档的编写日期和（或）版本号（推荐使用宏 ``%%date``）

    602. 

  602. 

    603. 

  603. 

    604. 

  604. 请记住：源文件的头三行将会是目标文件的头三行，在目标文件中会以高的对比与文档内容相区分（比如：大号字体，粗体）。如果允许分页，头部将会单独的在第一页居中显示。

    605. 

  605. 

    606. 

  606. ==== 较少（或无）头部 ====

    607. 

  607. 

    608. 

  608. 有些时候作者会希望少于三行的头部，仅仅给出文档标题和（或）日期信息，这时只需将第二行和（或）第三行留为空行，这部份就不会在目标文件中显示。但是，请切记：即使是留为空白，这些行仍然是头部的一部分，主体域总是在这三行之后开始。

    609. 

  609. 

    610. 

  610. 只有标题（第一行）是必须的，但是你也可以把它留白，这意味着文档**没有头部**，而主体域就紧接着从第二行开始。如果你打算在完成转换之后再来定制头部信息，那么没有头部的选择是很有用的。命令行选项 ``--no-headers`` 通常用来完成这一操作。

    611. 

  611. 

    612. 

  612. ==== 总结 ====

    613. 

  613. 

    614. 

  614. 简而言之：“**头部只是__位置__，而非内容**”

    615. 

  615. 

    616. 

  616. 源文件的第一行会出现在目标文件的第一行，二三行同样。

    617. 

  617. 

    618. 

  618. ++ 设置域 ++[config-area]

    619. 

  619. 

    620. 

  620. 位置：

    621. 

  621. - 紧接着头部区域之后开始

    622. 

  622.  - 如果定义了**头部**则从**第四行**开始

    623. 

  623.  - 如果**无头部**，则从**第二行**开始

    624. 

  624. - 结束于主体域开始

    625. 

  625.  - 结束于一个非属性设定，空白或者注释行

    626. 

  626. 

    627. 

  627. 

    628. 

  628. 设置域是可选的。普通用户甚至可以编写出许多txt2tags文档，却不知道这个区域的存在，但是有经验的用户往往受益于它提供的有效的控制功能。设置域用来记录具体文档的设置，这样就省略了转换时繁杂的命令行选项。比如说，你可以设定好缺省的目标文件类型和字符编码。在“[设定 #settings]”一节中对此有详细的叙述。

    629. 

  629. 

    630. 

  630. ++ 主体域 ++[body-area]

    631. 

  631. 

    632. 

  632. 位置：

    633. 

  633. - 开始于第一个有效行

    634. 

  634.  - 头部、设置域以及注释都**不是**有效的行。

    635. 

  635. - 结束于文件的末尾（EOF）

    636. 

  636. 

    637. 

  637. 

    638. 

  638. 除了头部和设置域以外的所有内容都是主体域。主体域包含来了文件的内容以及txt2tags支持的所有格式和文档结构的信息。在主体域内你也可以放置注释，作为 //TODOs// 和自提示。

    639. 

  639. 

    640. 

  640. 命令行选项 ``--no-headers`` 会忽略头部，只转换主体域的内容。这是很有用的：你可以用单独的文件来定义头部，然后与转换后的主体域连接起来。

    641. 

  641. 

    642. 

  642. ++ 设定 ++[settings-overview]

    643. 

  643. 

    644. 

  644. 设定（Settings）是特殊的配置选项，位于文档的设置域内，用以控制转换的过程。设定的语法如：

    645. 

  645. 

    646. 

  646. ``` $! 关键词 : 设定值

    647. 

  647. 

    648. 

  648. 以下是有效的关键词列表：

    649. 

  649. 

    650. 

  650.  ||  关键词  |  描述  |

    651. 

  651.  |  target  | 设定缺省的目标文件格式。 |

    652. 

  652.  |  options  | 设定缺省的转换选项，格式与命令行选项相同。 |

    653. 

  653.  |  style  | 设定文档样式。主要用作为HTML/XHTML文档定义外联的CSS样式表，以及为LaTeX文档加载宏包。 |

    654. 

  654.  |  encoding  | 设定字符编码。当文档包含国际化字符和非ASCII字符时需要指定编码。 |

    655. 

  655.  |  preproc  | 输入文件处理。设定应用于源文件的主体域中的“查找/替换”规则。 |

    656. 

  656.  |  postproc  | 输出文件处理。设定应用与输出文件中的“查找/替换”规则。 |

    657. 

  657. 

    658. 

  658. 

    659. 

  659. 示例：

    660. 

  660. 

    661. 

  661. ```

    662. 

  662. %! Target  : html

    663. 

  663. %! Options : --toc --toc-level 3

    664. 

  664. %! Style   : fancy.css

    665. 

  665. %! Encoding: iso-8859-1

    666. 

  666. %! PreProc : "AMJ"        "Aurelio Marinho Jargas"

    667. 

  667. %! PostProc: '<BODY.*?>'  '<BODY bgcolor="yellow">'

    668. 

  668. ```

    669. 

  669. 

    670. 

  670. 

    671. 

  671. ++ 命令行选项 ++[cmd-options]

    672. 

  672. 

    673. 

  673. 改变txt2tags默认行为最快捷的方式是使用命令行选项。顾名思义，这些选项只能应用于命令行方式，不适用于GUI和Web界面。

    674. 

  674. 

    675. 

  675. 与其他工具一样，程序接受一串预定义的选项，每个选项都是由一个单连字符引导的字母，或者两个连续的连字符引导的一个或多个单词，比如 ``-t`` 和 ``--target``。“target”选项是唯一的一个必须的选项，其他的都是可省略的选项。

    676. 

  676. 

    677. 

  677. 常用的选项包括：``--outfile``，指定输出文件名；``--toc``，自动生成目录表；``--encoding``，设定文档的字符编码。大多数的选项可以通过前缀一个“``no-``”来关闭，比如：``--no-encoding`` 和 ``--no-toc``。

    678. 

  678. 

    679. 

  679. 使用 ``%!options`` 的格式，你可以在源文件的设置域设定需要的选项，这样在命令行中就可以省略掉这些选项了。比如：``%!options: --toc -o mydoc.html``。目标文件格式的指定是个例外，它有自己的格式：``%!target: html``。

    680. 

  680. 

    681. 

  681. 使用 ``--help`` 选项能获得完整的选项列表。

    682. 

  682. 

    683. 

  683. 

    684. 

  684. ++ 用户配置文件（RC文件） ++[rc]

    685. 

  685. 

    686. 

  686. 通用的设定存储于用户配置文件（又称为RC文件）中。对于在每一个源文件中反复使用的设定，你可以把它们写到RC文件中，以便于所有的源文件使用。这个文件的缺省位置取决于你使用的操作系统，你也可以通过定义环境变量来指定其位置。

    687. 

  687. 

    688. 

  688.   ||              RC 文件的位置             ||

    689. 

  689.   |          Windows | ``%HOMEPATH%\_t2trc``

    690. 

  690.   |  Linux and other | ``$HOME/.txt2tagsrc``

    691. 

  691.   |     User defined | ``T2TCONFIG`` 环境变量

    692. 

  692. 

    693. 

  693. 

    694. 

  694. 设定的格式与源文件设置域中使用的选项格式完全相同。以下是包含在程序包的 ``doc/txt2tagsrc`` 的示例文件：

    695. 

  695. 

    696. 

  696. ```

    697. 

  697. % my configs

    698. 

  698. 

    699. 

  699. %%% Always use CSS-friendly tags in HTML

    700. 

  700. %!options(html): --css-sugar

    701. 

  701. 

    702. 

  702. %%% Change the default TOC depth for all targets

    703. 

  703. %!options: --toc-level 4

    704. 

  704. 

    705. 

  705. %%% Set the default encoding for all documents

    706. 

  706. %!options: --encoding iso-8859-1

    707. 

  707. ```

    708. 

  708. 

    709. 

  709. 除去空白行、注释行和有效配置行之外的任何一个多余的行，都会使得txt2tags在运行时产生错误，因此编辑这个文件时请尽量小心。

    710. 

  710. 

    711. 

  711. 在执行转换时，程序自动将RC文件的内容应用于源文件，如果你想要关闭这一行为，则可使用命令行选项 ``--no-rc``。

    712. 

  712. 

    713. 

  713. 

    714. 

  714. ++ 配置的优先级和加载顺序 ++[config-loading]

    715. 

  715. 

    716. 

  716. 有三种方式告诉txt2tags需要使用的选项和设定，其读取和应用的顺序是：

    717. 

  717. 

    718. 

  718. + 用户配置文件的设定

    719. 

  719. + 源文件设置域的设定

    720. 

  720. + 命令行选项

    721. 

  721. 

    722. 

  722. 

    723. 

  723. 程序首先读取RC文件的内容（如果存在的话），并将相应的设置应用于当前源文件。然后它检查源文件的设置域的设定，如果找到，应用之并且覆盖掉RC文件的设定以壁面冲突。最后是命令行选项，它的效力比前两者都高。

    724. 

  724. 

    725. 

  725. 这即是说，如果文档的字符编码同时用三种方式来设定，最终被应用的是命令行选项的设定。

    726. 

  726. 

    727. 

  727. ++ %!include 指令 ++[include]

    728. 

  728. 

    729. 

  729. ``include`` 命令用于将外部文件的内容包含进源文件中。它不是一个配置选项而是一个命令，对于主体域区域来说，则是一个有效的行。

    730. 

  730. 

    731. 

  731. ``include`` 命令可用来将大型的文档分割为较小的片段（比如整本书中的章节），或者是将外部文件的全部内容包含进源文件中。比如：

    732. 

  732. 

    733. 

  733. ```

    734. 

  734. My first book

    735. 

  735. Dr. John Doe

    736. 

  736. 1st Edition

    737. 

  737. 

    738. 

  738. %!include: intro.t2t

    739. 

  739. %!include: chapter1.t2t

    740. 

  740. %!include: chapter2.t2t

    741. 

  741. ...

    742. 

  742. %!include: chapter9.t2t

    743. 

  743. %!include: ending.t2t

    744. 

  744. ```

    745. 

  745. 

    746. 

  746. 文件名接在字符串 ``%!include`` 后面。支持可选的“target”选项，因此下面的格式也是合法的：

    747. 

  747. 

    748. 

  748. ``` %!include(html): file.t2t

    749. 

  749. 

    750. 

  750. 注意：include 命令将被包含文件的主体域区域读入源文件中，而头部和设置域则被忽略。所以，你可以单独转换这个文件，或者将它包含进主文档中一同转换。

    751. 

  751. 

    752. 

  752. 此外，还有另外三种形式的包含：

    753. 

  753. - 完全引用（Verbatim）包含

    754. 

  754. - 原文（Raw）包含

    755. 

  755. - 带标记（Tagged）包含

    756. 

  756. 

    757. 

  757. 

    758. 

  758. **完全引用（Verbatim）**包含会保留读入文件原始的空格和格式，就像是txt2tags文件的完全引用（VERB）域一样。要实现这种类型的包含，请将文件名置于反引号中：

    759. 

  759. 

    760. 

  760. ``` %!include: ``/etc/fstab``

    761. 

  761. 

    762. 

  762. **原文（Raw）**包含会照原样包含读入文件，不会寻找和解析其中的任何标记，就像之余原文（RAW）域中一样。要实现这种类型的包含，请将文件名置于双引号中：

    763. 

  763. 

    764. 

  764. ``` %!include: ""nice_text.txt""

    765. 

  765. 

    766. 

  766. **带标记（Tagged）**包含会将读入文件内容直接传递给目标文件，txt2tags不会进行任何解析和控制。这种方式适用于在文档中包含额外的带标记的内容，对于缺省的头部或脚注信息以及txt2tags不支持的复杂标记十分有用：

    767. 

  767. 

    768. 

  768. ``` %!include: ''footer.html''

    769. 

  769. 

    770. 

  770. 注意：请将文件名置于两个单引号中间。由于插入的内容是已经格式化的，你必须确认目标文件格式以防止出错。

    771. 

  771. 

    772. 

  772. 

    773. 

  773. ++ %!includeconf 指令 ++[includeconf]

    774. 

  774. 

    775. 

  775. ``includeconf`` 命令用于将外部配置文件读入当前文件中。这个命令仅在源文件的设置域内出现才是合法而有效的。

    776. 

  776. 

    777. 

  777. 当多个文件共享同样的配置时，你可以将这些配置集中放置，然后用这个指令来读入。请在每个需要读入外部集中配置的文件中使用 ``includeconf`` 命令。比如：

    778. 

  778. 

    779. 

  779. ```

    780. 

  780. My First Document

    781. 

  781. John Doe

    782. 

  782. July, 2004

    783. 

  783. 

    784. 

  784. %!includeconf: config.t2t

    785. 

  785. 

    786. 

  786. Hi, this is my first document.

    787. 

  787. ```

    788. 

  788. 

    789. 

  789. 外部配置文件使用的格式与RC文件相同。

    790. 

  790. 

    791. 

  791. --------------------------------------------------------

    792. 

  792. 

    793. 

  793. + 第五部分 掌握标记 +[marks]

    794. 

  794. 

    795. 

  795. txt2tags的全部标记概览：

    796. 

  796.  ||                   基本                   ||           美化          ||

    797. 

  797.  |          //头部// |  First 3 lines       |            //粗体// |  ""**words**"" 

    798. 

  798.  |            //标题// |  = words =           |          //斜体// |  ""//words//"" 

    799. 

  799.  |   //带编号的标题// |  + words +           |       //下划线// |  ""__words__"" 

    800. 

  800.  |        //段落// |  words               |          //删除线// |  ""--words--"" 

    801. 

  801.  |            //链接// |  ""[label url]""     |      //等宽// |  ""``words``"" 

    802. 

  802.  |            //图片// |  ""[filename.jpg]""  |        //原始文字// |  """"words"""" 

    803. 

  803.  ||                                          其他                                ||||

    804. 

  804.  |            //引用// |  <TAB>words          |  //分隔线// |  ------------... 

    805. 

  805.  |             //列表// |  - words             |     //粗分隔线// |  ============... 

    806. 

  806.  |    //编号列表// |  + words             |           //表格// |  ""| cell1 | cell2 | cell3..."" 

    807. 

  807.  |  //定义列表// |  : words             |          //锚点（标签）// |  = title =[anchor] 

    808. 

  808.  |     //注释行// |  % comments          |    //注释域// |  %%%\n comments \n%%% 

    809. 

  809.  |    //完全引用行// |  ""```"" word        |   //完全引用域// |  ""```\n lines \n```"" 

    810. 

  810.  |         //原文行// |  """"""" words       |        //原文域// |  """""""\n lines \n""""""" 

    811. 

  811. 

    812. 

  812. 

    813. 

  813. 通用规则：

    814. 

  814. - **头部**是文档的头三行，其中的标记不会解析。

    815. 

  815. - **标题**是包围标题文字的对称的“=”或“+”字符。字符越多，标题级数越深。

    816. 

  816. - **美化符**会忽略标记与其中的内容之间的空格。

    817. 

  817. - **注释**符号“%”必须位于每一行的开头（第一列）。

    818. 

  818. - **图片**文件名必须以GIF、JPG、PNG或者类似的扩展名结束。

    819. 

  819. - 完全引用（Verbatim）和原文（Raw）中的标记不会被解析。

    820. 

  820. - **分隔线/粗分隔线**必须是连续20个字符以上。

    821. 

  821. - 引用和列表的**嵌套/解嵌套**通过缩进来定义。

    822. 

  822. - **表格标题**行通过位于行首的双管道符“||”来定义。

    823. 

  823. 

    824. 

  824. 

    825. 

  825. ++ 头部 ++[mark-headers]

    826. 

  826. 

    827. 

  827. - **描述**：确定文档头部

    828. 

  828. - **属性**：多行，空格自由（可自由包含空格，下同。原文：FreeSpace），无对齐，无嵌套

    829. 

  829. - **可包含**：宏

    830. 

  830. - **语法**：

    831. 

  831.  - 源文件的头三行

    832. 

  832.  - 第一行留空则表示无头部。适合于用户定制的头部（原文：Nice for command line oneliners or customized headers）。

    833. 

  833.  - 第二行和/或第三行留空，将忽略头部的部分内容。

    834. 

  834. - **细节**：

    835. 

  835.  - 头部域的标记**不会**被解析

    836. 

  836.  - 源文件的头三行也是目标文件的头三行，在目标文件中与主体域以高对比来显示，或者置于单独的第一页上（如果允许分页的话）。

    837. 

  837.  - 头部的内容可以随意，没有硬性规定的信息，然而推荐使用下面的写法：

    838. 

  838.   - 第一行：文件标题

    839. 

  839.   - 第二行：作者姓名和/或电子邮件

    840. 

  840.   - 第三行：文档日期和/或版本号（建议使用 ``%%mtime`` 宏）

    841. 

  841. 

    842. 

  842. 

    843. 

  843. ++ 标题与编号的标题 ++[mark-title]

    844. 

  844. 

    845. 

  845. - **描述**：确定一个编号或者不编号的章节标题

    846. 

  846. - **属性**：非多行，空格自由，无对齐，无嵌套

    847. 

  847. - **可包含**：原始文本（Raw）

    848. 

  848. - **语法**：

    849. 

  849.  - 对于所有的规则，用“+”替代“=”可得到编号的标题

    850. 

  850.  - 包围文字的符号数目保持对称，``=像这样=``

    851. 

  851.  - 符号数目增加，章节深度随之增加：``=title=, ==subtitle==, ===subsubtitle===, ...``

    852. 

  852.  - 最大深度为5级标题，``=====像这样=====``

    853. 

  853.  - 数目不对称的标记不构成标题，``=像这样===``

    854. 

  854.  - 标记包围的内部可以自由添加空格，``= 像 这 样 =``

    855. 

  855.  - 标题可以有锚点（anchor），``=像这样=[anchor]``。可以创建一个到此锚点的链接，形如 ``[本地链接 #anchor]``

    856. 

  856.  - 锚点名称只能由字母、数字、下划线和连字符构成（A-Za-z0-9_-）

    857. 

  857. - **细节**：

    858. 

  858.  - 标题中的其他标记不会解析

    859. 

  859.  - 标题中的宏不会解析

    860. 

  860. 

    861. 

  861. 

    862. 

  862. ++ 段落 ++[mark-par]

    863. 

  863. 

    864. 

  864. - **描述**：确定一个自然段

    865. 

  865. - **属性**：多行，空格自由，无对齐，无嵌套

    866. 

  866. - **可包含**：宏，美化符，原始文（Raw），链接，图片，注释

    867. 

  867. - **语法**：

    868. 

  868.  - 由空行分隔的多行文本构成段落

    869. 

  869.  - 其他的块，如列表、引用域、表格或完全引用域等，也可作为段落的结束

    870. 

  870. 

    871. 

  871. 

    872. 

  872. ++ 注释 ++[mark-comment]

    873. 

  873. 

    874. 

  874. - **描述**：用于插入不会写入目标文件的文本

    875. 

  875. - **属性**：非多行，非空格自由，无对齐，无嵌套

    876. 

  876. - **可包含**：无

    877. 

  877. - **语法**：

    878. 

  878.  - 以一个百分号 % 起始的行（%位于第一列）构成一个注释行，``%像这样``

    879. 

  879.  - **不能**有前导空格（按：这就是所谓“非空格自由”）

    880. 

  880. - **细节**：

    881. 

  881.  - 注释文本不会写入转换后的文件

    882. 

  882.  - 注释是非块状的，因此每一个注释行都必须以 % 作为前导

    883. 

  883.  - 可用于 TODO 和 FIXME 提示，以及作者自提示

    884. 

  884. 

    885. 

  885. 

    886. 

  886. ++ 粗体，斜体，下划线和删除线 ++[mark-beautifiers]

    887. 

  887. 

    888. 

  888. - **描述**：用于在段落、表格、列表和引用域内插入 粗体/斜体/下划线/删除线 字体

    889. 

  889. - **属性**：非多行，非空格自由，无对齐，可嵌套

    890. 

  890. - **可包含**：宏，美化符，原始文（Raw），链接，图片

    891. 

  891. - **语法**：

    892. 

  892.  - 双星号包围的文字产生**粗体**，``**像这样**``

    893. 

  893.  - 双斜杠包围的文字产生//斜体//，``//像这样//``

    894. 

  894.  - 双下划线包围的文字产生__下划线__字体，``__像这样__``

    895. 

  895.  - 双连字符包围的文字产生--删除线--字体，``--像这样--``

    896. 

  896.  - 标记必须与内部的文字紧密贴合（不能有空格）：``** 像这样 ** 是非法的``

    897. 

  897. - **细节**：：

    898. 

  898.  - 源文件中每一对美化符都必须位于同一行，中间不能有换行符

    899. 

  899.  - 美化符内可以包含宏，比如：``**%%date**``

    900. 

  900.  - 美化符可以混合使用，如：``""**__like__ //this//**""``

    901. 

  901. 

    902. 

  902. 

    903. 

  903. ++ 等宽字体 ++[mark-monospaced]

    904. 

  904. 

    905. 

  905. - **描述**：用于在段落、表格、列表和引用域内插入等宽字体的文本

    906. 

  906. - **属性**：非多行，非空格自由，无对齐，无嵌套

    907. 

  907. - **可包含**：无

    908. 

  908. - **语法**：

    909. 

  909.  - 用双反引号包围文字，````像这样````

    910. 

  910.  - 标记必须与内部文字紧密贴合（不能有空格）：```` 像这样 `` 是非法的``

    911. 

  911. - **细节**：

    912. 

  912.  - 内部的标记不会解析

    913. 

  913.  - 内部的宏不会解析

    914. 

  914.  - 所有的等宽文字必须位于单一行内，不能有换行符

    915. 

  915.  - 在部分目标文件中，内部的空格会被保留下来；在其他的目标格式中，连续的空格则被压缩为一个。

    916. 

  916.  - 还可以得到粗体的等宽字体，只需放置于粗体标记内部：""``**monobold**``""。这一规则对其他的美化符同样适用，比如：""``//italic//``""，""``__underline__``""。

    917. 

  917. 

    918. 

  918. 

    919. 

  919. ++ 完全引用行和完全引用域 ++[mark-verbatim]

    920. 

  920. 

    921. 

  921. - **描述**：用于插入程序源代码或者其他预格式化的文本，保留空格和换行符，并以等宽字体显示

    922. 

  922. - **属性**：多行，非空格自由，无对齐，无嵌套

    923. 

  923. - **可包含**：无

    924. 

  924. - **语法 - 完全引用行**：

    925. 

  925.  - 以三个相继的反引号加一个空格引导，后接文字，""``` 像这样""

    926. 

  926.  - 反引号必须位于每行的第一列，不能有前导空格

    927. 

  927. - **语法 - 完全引用域**：

    928. 

  928.  - 第一行为三个相继的反引号 ""```""，从下一行开始为单行或多行文本，最后一行为三个相继的反引号 ""```""

    929. 

  929.  - 标记不能有前导空格，也不能有后随的空格

    930. 

  930. - **细节**：

    931. 

  931.  - 内部的标记不会解析

    932. 

  932.  - 内部的宏不会解析

    933. 

  933.  - 如果到达源文件末尾（EOF），尚未闭合的完全引用域将自动关闭

    934. 

  934. 

    935. 

  935. 

    936. 

  936. ++ 隔离行和粗隔离行 ++[mark-seperator]

    937. 

  937. 

    938. 

  938. - **描述**：生成水平线隔离行或者粗隔离行

    939. 

  939. - **属性**：非多行，空格自由，无对齐，无嵌套

    940. 

  940. - **可包含**：无

    941. 

  941. - **语法**：

    942. 

  942.  - 隔离行由多个虚线“-”或者下划线“_”构成

    943. 

  943.  - 粗隔离行由多个等号“=”组成

    944. 

  944.  - 至少包括20个相应的字符

    945. 

  945.  - 线可以有前导和后随的空格

    946. 

  946.  - 在同一行的任何其他字符将破坏标记

    947. 

  947. - **细节**：

    948. 

  948.  - 如果目标格式不支持水平线，自动转化为一个注释行

    949. 

  949.  - 粗隔离行在某些目标格式中可能有不同的作用：

    950. 

  950.   - 更粗的隔离行

    951. 

  951.   - 放映暂停，比如在 MagicPoint 中

    952. 

  952.   - 分页，比如在 LaTeX 中

    953. 

  953. 

    954. 

  954. 

    955. 

  955. ++ 链接和命名链接 ++[mark-link]

    956. 

  956. 

    957. 

  957. - **描述**：确定一个指向互联网或本地的链接

    958. 

  958. - **属性**：非多行，非空格自由，无对齐，无嵌套

    959. 

  959. - **可包含**：宏，原始文（Raw），图片

    960. 

  960. - **语法**：

    961. 

  961.  - 合法的URL、ftp、新闻组或电子邮件地址能被程序自动识别并转换为超链接

    962. 

  962.  - 协议（http，https，ftp等）可省略，如：``www.likethis.com``

    963. 

  963.  - 可以为链接命名，如：``[click here www.url.com]``

    964. 

  964.  - 可以创建图片链接：``[[image.jpg] www.url.com]``

    965. 

  965.  - 链接地址允许宏替换：``[see source %%infile]``

    966. 

  966.  - 链接名字允许宏替换：``[mirror of %%outfile www.url.com]``

    967. 

  967.  - 全部链接标识符必须位于源文件的同一行内，不能有换行符

    968. 

  968. - **细节**：

    969. 

  969.  - 如果目标格式不支持链接，则链接文字仅仅加上下划线

    970. 

  970. 

    971. 

  971. 

    972. 

  972. ++ 引用 ++[mark-quote]

    973. 

  973. 

    974. 

  974. - **描述**：确定一个引用（缩进）行

    975. 

  975. - **属性**：多行，非空格自由，无对齐，可嵌套

    976. 

  976. - **可包含**：宏，美化符，引用，原始文，Bars，链接，图片，注释

    977. 

  977. - **语法**：

    978. 

  978.  - 以一个制表符（TAB）开始的一行

    979. 

  979.  - 更多的制表符则增加引用缩进的深度

    980. 

  980.  - 引用行能不允许列表和表格

    981. 

  981. - **细节**：

    982. 

  982.  - 如果到达文件末尾（EOF），尚未闭合的引用自动关闭

    983. 

  983.  - 某些目标格式不支持引用嵌套，则子嵌套自动外移到与外层嵌套同级

    984. 

  984.  - 引用深度原则上没有限制，但某些目标格式可能会有限制，则超过最大深度的子嵌套自动外移。

    985. 

  985. 

    986. 

  986. 

    987. 

  987. ++ 列表，编号列表和定义列表 ++[mark-list]

    988. 

  988. 

    989. 

  989. - **描述**：确定列表项开始

    990. 

  990. - **属性**：多行，非空格自由，无对齐，可嵌套

    991. 

  991. - **可包含**：宏，美化符，列表，表格，完全引用，原始文，Bars，链接，图片，注释

    992. 

  992. - **语法**：

    993. 

  993.  - 以单个 虚线“-”/加号“+”/冒号“:” 紧接单个空格开始一行

    994. 

  994.  - 列表项的第一个字符不能是空格（定义列表除外）

    995. 

  995.  - 可选的前导空格（普通空格，非制表符）将开始一个子列表（列表嵌套）

    996. 

  996.  - 子列表以较少深度的表项或者空表项结束

    997. 

  997.  - 所有开放的列表以两个相继的空行结束

    998. 

  998. - **细节**：

    999. 

  999.  - 如果到达文件末尾（EOF），所有尚未闭合的列表自动关闭

    1000. 

  1000.  - 列表可以混合使用，比如编号列表内部可以嵌套定义列表

    1001. 

  1001.  - 某些目标格式可能不支持列表嵌套，则子列表自动外移到与外层列表同级

    1002. 

  1002.  - 嵌套深度原则上没有限制，但是某些目标格式可能会有限制，则超过最大深度的子列表自动外移

    1003. 

  1003. 

    1004. 

  1004. 

    1005. 

  1005. ++ 图片 ++[mark-image]

    1006. 

  1006. 

    1007. 

  1007. - **描述**：插入一副图片

    1008. 

  1008. - **属性**：非多行，非空格自由，可对齐，无嵌套

    1009. 

  1009. - **可包含**：宏

    1010. 

  1010. - **语法**：

    1011. 

  1011.  - 将图片的文件名放在一对方括号中，如：``[likethis.jpg]``

    1012. 

  1012.  - 文件名必须以 PNG，JPG，GIF 等图形格式扩展名结束，不区分大小写

    1013. 

  1013.  - 文件名可以含有符号（原文：Symbols are allowed on the filename），如：``[likethis!~1.jpg]``

    1014. 

  1014.  - 文件名允许宏替换，比如：``[report-%%date(%Y-%m-%d).png]``

    1015. 

  1015.  - 文件名不能包含空格，如：``[like this.jpg]``

    1016. 

  1016.  - 文件名与方括号之间不能有空格，如：``[ likethis.jpg ]``

    1017. 

  1017. - **细节**：

    1018. 

  1018.  - 如果目标格式不支持插入图片，图片名称将置于一对圆括号中显示

    1019. 

  1019.  - 插入图片标记在一行中的位置定义了图形的对齐方式：

    1020. 

  1020.   - ``[LEFT.jpg]`` 左对齐左对齐左对齐

    1021. 

  1021.   - 居中居中居中 ``[CENTER.jpg]`` 居中居中居中

    1022. 

  1022.   - 右对齐右对齐右对齐 ``[RIGHT.jpg]``

    1023. 

  1023. 

    1024. 

  1024. 

    1025. 

  1025. ++ 表格 ++[mark-table]

    1026. 

  1026. 

    1027. 

  1027. - **描述**：限定有任意列的表格行

    1028. 

  1028. - **属性**：多行，空格自由，可对齐，无嵌套

    1029. 

  1029. - **可包含**：宏，美化符，原始文，链接，图片，注释

    1030. 

  1030. - **语法**：

    1031. 

  1031.  - 一个前导的管道符“|”确定一个表格行

    1032. 

  1032.  - 一对前导的管道符“||”确定一个表格的标题行

    1033. 

  1033.  - 首个管道符前的前导空格确定表格居中

    1034. 

  1034.  - 单元格以管道符间隔（形如：空格|空格）

    1035. 

  1035.  - 表格第一行以一个管道符结束，表示边框可见

    1036. 

  1036.  - 其余行结尾的管道符可以忽略（仅作装饰用）

    1037. 

  1037.  - 单元格以多余一个管道符结束获得“跨列”效果：“||”跨两列，“|||”跨三列，以此类推

    1038. 

  1038.  - 单元格内的空格决定内部的对齐方式

    1039. 

  1039.  - 示例：``| 包含 | 5列 | 的| 表格 | 行 |``

    1040. 

  1040. - **细节**：

    1041. 

  1041.  - 每一个表格行的内容必须在源文件内的同一行内，不能有换行符

    1042. 

  1042.  - 带列对齐的目标格式（比如SGML和LaTeX）以第一行的对齐方式作为所有行的缺省对齐方式

    1043. 

  1043.  - 任意的非表格行将结束一个表格，注释行除外

    1044. 

  1044.  - 单元格数目没有限定，不同的行可以包含不同数目的单元格

    1045. 

  1045.  - 目前尚无法实现“行跨越”

    1046. 

  1046.  - 如果目标格式不支持表格，则表格域视为完全引用域

    1047. 

  1047. 

    1048. 

  1048. 

    1049. 

  1049. ++ 原始文，原文行和原文域 ++[mark-raw]

    1050. 

  1050. 

    1051. 

  1051. - **描述**：用以“保护”某些文字不被解析，其内部的标记和宏均不会处理

    1052. 

  1052. - **属性**：非多行，非空格自由，无对齐，无嵌套

    1053. 

  1053. - **可包含**：无

    1054. 

  1054. - **语法 - 原始文**：

    1055. 

  1055.  - 连续的两个双引号包围文字，如：``""""like this""""``

    1056. 

  1056.  - 标记必须与内容紧密详解（不能有空格）

    1057. 

  1057. - **语法 - 原文行**：

    1058. 

  1058.  - 以3个相继的双引号开始的行，``""" like this``

    1059. 

  1059.  - 双引号必须位于行的第一列，不能有前导空格

    1060. 

  1060.  - 双引号后接一个空格，以分隔开标记与文本

    1061. 

  1061. - **语法 - 原文域**：

    1062. 

  1062.  - 第一行为3个相继的双引号，下一行开始为单行或多行文本，最后一行为3个相继的双引号作为结束

    1063. 

  1063.  - 标记不能有前导和后继空格

    1064. 

  1064. - **细节**：

    1065. 

  1065.  - 内部的标记不会解析

    1066. 

  1066.  - 内部的宏不会解析

    1067. 

  1067.  - 如果到达源文件末尾（EOF），尚未闭合的原文域自动关闭

    1068. 

  1068. 

    1069. 

  1069. 

    1070. 

  1070. --------------------------------------------------------

    1071. 

  1071. 

    1072. 

  1072. + 第六部分 宏 +[macro]

    1073. 

  1073. 

    1074. 

  1074. 宏是一些特殊的关键词，在转换的时候进行展开和替换。宏可以用来插入动态的信息，比如源文件的编辑日期或其他信息。

    1075. 

  1075. 

    1076. 

  1076. 宏的格式为：双百分号%%引导，后面紧跟着宏名，如：``%%date``。某些宏可以后接一对圆括号，里面是可选的格式选项字符串，诸如：``%%date(%Y-%m-%d)``，格式选项字符串由百分号%后接一个字符构成，如果未给出格式选项，则使用缺省的格式。

    1077. 

  1077. 

    1078. 

  1078.  ||  宏名  |   展开为   |   默认格式   |

    1079. 

  1079.  | ``%%date``  | 当前日期  |  ``%Y%m%d``  |

    1080. 

  1080.  | ``%%mtime``  | 源文件修改时间  |  ``%Y%m%d``  |

    1081. 

  1081.  | ``%%infile``  | 源文件路径  |  ``%f``  |

    1082. 

  1082.  | ``%%outfile``  | 输出文件路径  |  ``%f``  |

    1083. 

  1083.  | ``%%toc``  | 展开为目录表  |  -  |

    1084. 

  1084. 

    1085. 

  1085. 

    1086. 

  1086. 一般规则：

    1087. 

  1087. - 宏名不区分大小写，所以 ``%%date``、``%%DaTe`` 和 ``%%DATE`` 完全等效

    1088. 

  1088. - 宏放置于文档的头部和体区域都是有效的，只有 ``%%toc`` 例外，它只能放在主体域区域。

    1089. 

  1089. - 在设置域内的宏，意味着设置域结束，体区域开始

    1090. 

  1090. - 宏可以位于一行的任何位置，同一行可以包含各种不同的宏（``%%toc`` 除外，它必须独占一行）

    1091. 

  1091. - 链接和插图标记也可以使用宏（``%%toc`` 除外）

    1092. 

  1092. - 标题、完全引用和原文域内的宏不会解析

    1093. 

  1093. 

    1094. 

  1094. 

    1095. 

  1095. 一个完整的例子（粗体部分由宏展开得到）：

    1096. 

  1096. 

    1097. 

  1097. 本文是《Txt2tags用户指南》，由源文件 **%%infile** 通过Txt2tags转换得到，输出文件名 **%%outfile(%e)**。转换完成于 **%%date(%Y-%m-%d %X)**，而最后一次修改则是在 **%%mtime(%Y-%m-%d %X)**。源文件和目标文件均位于目录 **%%infile(%D)** 下。

    1098. 

  1098. 

    1099. 

  1099. （译者按：宏``%%infile``和``%%outfile``再Windows下无法正常展开。）

    1100. 

  1100. 

    1101. 

  1101. ++ %%date ++[macro-date]

    1102. 

  1102. 

    1103. 

  1103. 宏 ``%%date`` 将被替换为当前的日期和时间，可以用于在文档的头部或尾部注明生成的时间。如果要得到源文件最近一次编辑的时间，请参见 [``%mtime`` 宏 #macro-mtime]一节。

    1104. 

  1104. 

    1105. 

  1105. 宏展开时可以有若干不同的显示格式，完整的列表请参看 [Python主页  http://www.python.org/doc/current/lib/module-time.html]，以下是其中最常用的几种：

    1106. 

  1106. 

    1107. 

  1107.  ||  格式  |   描述   |

    1108. 

  1108.  |  ``%a``  | 星期名的缩写  |

    1109. 

  1109.  |  ``%A``  | 星期名的全称  |

    1110. 

  1110.  |  ``%b``  | 月份名的缩写  |

    1111. 

  1111.  |  ``%B``  | 月份名的全程  |

    1112. 

  1112.  |  ``%c``  | 日期和时间  |

    1113. 

  1113.  |  ``%d``  | 一个月中的第几天（01-31的十进制数）  |

    1114. 

  1114.  |  ``%H``  | 24小时制的小时数（00-23的十进制数）  |

    1115. 

  1115.  |  ``%I``  | 12小时制的小时数（01-12的十进制数）  |

    1116. 

  1116.  |  ``%m``  | 一年中的第几个月（01-12的十进制数）  |

    1117. 

  1117.  |  ``%M``  | 分钟数（01-59的十进制数）  |

    1118. 

  1118.  |  ``%p``  | 本地格式的 上午 或者 下午  |

    1119. 

  1119.  |  ``%S``  | 秒数（01-59的十进制数）  |

    1120. 

  1120.  |  ``%x``  | 本地的日期代称（原文：Locale's appropriate date representation）  |

    1121. 

  1121.  |  ``%X``  | 本地的时间代称  |

    1122. 

  1122.  |  ``%y``  | 两位数的年份表示（00-99的十进制数）  |

    1123. 

  1123.  |  ``%Y``  | 完整的年份表示  |

    1124. 

  1124.  |  ``%%``  | 百分号“""%""”  |

    1125. 

  1125. 

    1126. 

  1126. 

    1127. 

  1127. 

    1128. 

  1128. 示例：

    1129. 

  1129.  ||  宏                           |  -->  | 对 %%date(%Y, %b %d at %H:%M) 的展开效果 |

    1130. 

  1130.   | ""%%date(Converted on: %c)""    |  -->  | %%date(Converted on: %c)

    1131. 

  1131.   | ""%%date(%Y-%m-%d)""            |  -->  | %%date(%Y-%m-%d)

    1132. 

  1132.   | ""%%date(%I:%M %p)""            |  -->  | %%date(%I:%M %p)

    1133. 

  1133.   | ""%%date(Today is %A, on %B.)"" |  -->  | %%date(Today is %A, on %B.)

    1134. 

  1134. 

    1135. 

  1135. 

    1136. 

  1136. ++ %%mtime  ++[macro-mtime]

    1137. 

  1137. 

    1138. 

  1138. 宏 ``%%mtime`` 将被展开为源文件最近一次修改的时间。它可算作是[宏""%%date"" #macro-date]的“姊妹篇”，其格式指令与之完全相同。

    1139. 

  1139. 

    1140. 

  1140. 举一个例子，本文的源文件最近一次修改是在 %%mtime(%c) ，这一日期由``%%mtime(%c)``展开而来。

    1141. 

  1141. 

    1142. 

  1142. ++ %%infile ++[macro-infile]

    1143. 

  1143. 

    1144. 

  1144. 宏``%%infile``展开为源文件在系统中的路径信息，可用于生成html中“//查看本页面源文件//”的链接。

    1145. 

  1145. 

    1146. 

  1146. 该宏支持的格式指令如下：

    1147. 

  1147. 

    1148. 

  1148.  ||  指令  |  描述  |  本文源文件的宏展开输出  |

    1149. 

  1149.  |  ``%f``  | 文件名 | %%infile(%f) 

    1150. 

  1150.  |  ``%F``  | 文件名（不含扩展名） | %%infile(%F) 

    1151. 

  1151.  |  ``%e``  | 文件扩展名  | %%infile(%e) 

    1152. 

  1152.  |  ``%p``  | 文件绝对路径  | %%infile(%p) 

    1153. 

  1153.  |  ``%d``  | 文件所在目录  | %%infile(%d) 

    1154. 

  1154.  |  ``%D``  | 文件父目录  | %%infile(%D) 

    1155. 

  1155.  |  ``%%``  | 百分号  | %%infile(%%) 

    1156. 

  1156. 

    1157. 

  1157. 

    1158. 

  1158. 示例：

    1159. 

  1159. 

    1160. 

  1160.  || 源代码                                       |  -->  | 展开结果  |

    1161. 

  1161.  | This Guide parent dir is ""%%infile(%D)"".    |  -->  | This Guide parent dir is %%infile(%D). |

    1162. 

  1162.  | I do use the ""%%infile(%e)"" file extension. |  -->  | I do use the %%infile(%e) file extension. |

    1163. 

  1163.  | ""[See the source %%infile]""                 |  -->  | [See the source %%infile]

    1164. 

  1164.  | Converted to XHTML, I'll be ""%%infile(%F)"".xhtml |  -->  | Converted to XHTML, I'll be %%infile(%F).xhtml

    1165. 

  1165. 

    1166. 

  1166. 	注：若源文件为标准输入STDIN，则宏展开为“-”。

    1167. 

  1167. 

    1168. 

  1168. 

    1169. 

  1169. ++ %%outfile ++[macro-outfile]

    1170. 

  1170. 

    1171. 

  1171. 宏``%%outfile``将展开为目标文件的路径，可用于将文件名包含于文档的头部和主体内。它可算作是[宏""%%infile"" #macro-infile]的“姊妹篇”，格式指令也完全相同。

    1172. 

  1172. 

    1173. 

  1173. 示例：

    1174. 

  1174. 

    1175. 

  1175.  || 源代码                                    |  -->  | 展开结果  |

    1176. 

  1176.  | You are reading the ""%%outfile"" file.    |  -->  | You are reading the %%outfile file.

    1177. 

  1177.  | txt2tags -t ""%%outfile(%e)"" -i ""%%infile"" -o ""%%outfile"" |  -->  | txt2tags -t %%outfile(%e) -i %%infile -o %%outfile

    1178. 

  1178. 

    1179. 

  1179. 	注：若输出为标准输出STDOUT，则宏展开为“-”。

    1180. 

  1180. 

    1181. 

  1181. 

    1182. 

  1182. ++ %%toc ++[macro-toc]

    1183. 

  1183. 

    1184. 

  1184. 宏``%%toc``将展开为目录表。你可以把它放在文档主体域内的任何地方，甚至不止使用一次，比如你可以把它放在文档的末尾。本指南就是使用这个宏来放置了目录表。

    1185. 

  1185. 

    1186. 

  1186. 与其他的宏不同，``%%toc``没有格式字串，而使用规则也有不同：

    1187. 

  1187.  - 只在文档主体域中可用

    1188. 

  1188.  - 必须独占一行（前后可以有空格）

    1189. 

  1189.  - 必须与命令行选项``--toc``配合使用，否则将被忽略

    1190. 

  1190.  - 如果使用了``%%toc``，缺省的目录表位置和格式将被覆盖

    1191. 

  1191. 

    1192. 

  1192. --------------------------------------------------------

    1193. 

  1193. 

    1194. 

  1194. 

    1195. 

  1195. + 第七部分 设定+[settings]

    1196. 

  1196. 

    1197. 

  1197. 设定项位于文档的设置域内，在转换执行时生效。设定项均为可选的，普通用户完全可以不使用它们而完成所有工作；然而，一旦你学会使用设定项，我打赌你一定会上瘾，因为它们实在太好用了！

    1198. 

  1198. 

    1199. 

  1199. 设定行是特殊的注释行——由一个“!”引导，以此区别于普通的注释行。设定项的语法很简单，由关键词和值构成，二者由一个冒号（“:”）分隔。

    1200. 

  1200. 

    1201. 

  1201.   || %! keyword : value |

    1202. 

  1202. 

    1203. 

  1203. 语法细节：

    1204. 

  1204. 

    1205. 

  1205. - “%!”要写在一起，中间不能有空格，且置于行首

    1206. 

  1206. - 关键词和分隔符之间可以有空格

    1207. 

  1207. - 关键词和值均不区分大小写

    1208. 

  1208. 

    1209. 

  1209. 

    1210. 

  1210. 规则：

    1211. 

  1211. - 只有位于设置域内的设定项才生效，而位于主体域内的设定项将被视为普通的注释文本。

    1212. 

  1212. - 若相同关键词的设定项在设置域内出现多次，则使用最后一次的设定。例外：options, preproc和 postproc，这三个设定是累积的。

    1213. 

  1213. - 关键词写错的设定被视为普通注释文本。

    1214. 

  1214. - 设定项的优先级高于RC文件，但低于命令行选项。

    1215. 

  1215. 

    1216. 

  1216. 

    1217. 

  1217. ++ %!Target ++[setting-target]

    1218. 

  1218. 

    1219. 

  1219. 用来定义缺省的目标文件格式，如：

    1220. 

  1220. ``` %!target: html

    1221. 

  1221. 此时用户只需调用命令：

    1222. 

  1222. ``` $ txt2tags file.t2t

    1223. 

  1223. 即可将文档转换为预设的目标格式。

    1224. 

  1224. 

    1225. 

  1225. 本设定不支持指定可选的特定目标格式（原文：optional target specification），比如：``%!target(tex): html`` 是无效的。

    1226. 

  1226. 

    1227. 

  1227. ++ %!Options ++[setting-options]

    1228. 

  1228. 

    1229. 

  1229. 每次都输入冗长的命令行选项既累人又容易出错，使用Options设定项，用户可将转换选项与源文件放在一起，这同时也利于确保文档总能以相同的选项和相同的方式转换。

    1230. 

  1230. 

    1231. 

  1231. 书写这些选项时请确保不要有语法错误，就像使用命令行方式一样。当然，对程序“txt2tags”的调用、目标格式的指定和源文件名就不必写进来了。

    1232. 

  1232. 

    1233. 

  1233. 比如，假设你在命令行进行如下的转换：

    1234. 

  1234. ``` $ txt2tags -t html --toc --toc-level 2 --enum-title file.t2t

    1235. 

  1235. 把这些选项写入源文件：

    1236. 

  1236. ```

    1237. 

  1237. %!target: html

    1238. 

  1238. %!options(html): --toc --toc-level 2 --enum-title

    1239. 

  1239. ```

    1240. 

  1240. 现在你只需简单的使用命令“``txt2tags file.t2t”即可达到同样的目的，这样也便于你在编辑器中执行转换。比如，在Vi里面可以这样调用：

    1241. 

  1241. ``` :!txt2tags %

    1242. 

  1242. 

    1243. 

  1243. ++ %!Encoding ++[setting-encoding]

    1244. 

  1244. 

    1245. 

  1245. Encoding选项为非英语用户所需，因为他们需要使用本地语言的某些特殊字符以及细节，因此目标文件的**字符集**需要自行指定（如果允许的话）。

    1246. 

  1246. 

    1247. 

  1247. 有效的Encoding值与HTML所使用的**字符集**名称相同，比如：//iso-8859-1、koi8-r//等。如果你对此不确定，可以参见[完整的字符集列表 http://www.iana.org/assignments/character-sets]。

    1248. 

  1248. 

    1249. 

  1249. LaTeX使用的是字符集的别名，这对于用户来说并不是问题，因为txt2tags会替你完成名称的转换，比如：

    1250. 

  1250. 

    1251. 

  1251.       || txt2tags/HTML   |  >  | LaTeX  |

    1252. 

  1252.        | windows-1250    | >>> | cp1250 |

    1253. 

  1253.        | windows-1252    | >>> | cp1252 |

    1254. 

  1254.        | ibm850          | >>> | cp850  |

    1255. 

  1255.        | ibm852          | >>> | cp852  |

    1256. 

  1256.        | iso-8859-1      | >>> | latin1 |

    1257. 

  1257.        | iso-8859-2      | >>> | latin2 |

    1258. 

  1258.        | koi8-r          | >>> | koi8-r |

    1259. 

  1259. 

    1260. 

  1260. 就算设定的值txt2tags无法识别也可以通过，反正由用户自行定制。

    1261. 

  1261. 

    1262. 

  1262. ++ %!PreProc ++[setting-preproc]

    1263. 

  1263. 

    1264. 

  1264. PreProc选项在源文件读入后还没解析前，进行“查找和替换”的工作。

    1265. 

  1265. 

    1266. 

  1266. 可以用来定义一些常用词的缩写，如：

    1267. 

  1267. ```

    1268. 

  1268. %!preproc JJS          "John J. Smith"

    1269. 

  1269. %!preproc RELEASE_DATE "2003-05-01"

    1270. 

  1270. %!preproc BULLET       "[images/tiny/bullet_blue.png]"

    1271. 

  1271. ```

    1272. 

  1272. 

    1273. 

  1273. 源文档中的一行：

    1274. 

  1274. ``` Hi, I'm JJS. Today is RELEASE_DATE.

    1275. 

  1275. txt2tags在进行转换时会将其视为：

    1276. 

  1276. ``` Hi, I'm John J. Smith. Today is 2003-05-01.

    1277. 

  1277. 

    1278. 

  1278. 这相当于对源文件调用外部Sed/Perl进行过滤，然后传给txt2tags：

    1279. 

  1279. ``` $ cat file.t2t | preproc-script.sh | txt2tags -

    1280. 

  1280. txt2tags在PreProc处理结束后开始对源文件进行解析。

    1281. 

  1281. 

    1282. 

  1282. 	注：预处理仅仅对主体域进行，不会包含头部域和设置域。

    1283. 

  1283. 

    1284. 

  1284. ++ %!PostProc ++[setting-postproc]

    1285. 

  1285. 

    1286. 

  1286. PostProc选项在txt2tags进行解析和处理结束后，对于转换后的内容进行“查找和替换”的工作。

    1287. 

  1287. 

    1288. 

  1288. 可以用来对生成的文档进行进一步加工和微调，比如修改标记、添加额外的文本和标记，等等。比如：

    1289. 

  1289. ```

    1290. 

  1290. %!postproc(html): '<BODY.*?>' '<BODY BGCOLOR="green">'

    1291. 

  1291. %!postproc(tex) : "\\newpage" ""

    1292. 

  1292. ```

    1293. 

  1293. 作用是讲HTML文件的背景颜色改为绿色，以及移除LaTeX文件里的分页符。

    1294. 

  1294. 

    1295. 

  1295. 这相当于对转换后的内容调用外部Sed/Perl进行过滤，再生成目标文件：

    1296. 

  1296. ``` $ txt2tags -t html -o- file.t2t | postproc-script.sh > file.html

    1297. 

  1297. 

    1298. 

  1298. 在引入这一特性前，我们往往得使用一些小脚本来“调整”txt2tags处理的结果，这些脚本实际上多是大量的sed（或类似工具）替换命令。现在，这些繁琐的替换字符串可以放在文件中，并使用Python强大的正则表达式机制来进行匹配和处理。

    1299. 

  1299. 

    1300. 

  1300. ++ %!Style ++[setting-style]

    1301. 

  1301. 

    1302. 

  1302. - 用于在HTML和XHTML目标文件中指定样式表文件。

    1303. 

  1303. - 用于在LaTeX目标文件中使用``\usepackage``加载宏包。

    1304. 

  1304. - 效果等同于命令行选项 ``--style``。

    1305. 

  1305. - 命令行选项 ``--style`` 优先级高于设定项 ``%!style``。

    1306. 

  1306. 

    1307. 

  1307. 

    1308. 

  1308. ++ 针对特定的目标格式进行设定 ++[setting-specific]

    1309. 

  1309. 

    1310. 

  1310. 除了``%!target``之外的所有设定项均可作用于某一特定的目标格式，语法如：``%!key(target): value``。这使得用户可以针对不同的目标格式进行不同的设置。

    1311. 

  1311. 

    1312. 

  1312. 这一特性对所有支持它的设定项都有效，只不过在Pre/PostProc过滤器中显得尤其有用。举个例子，你可以对HTML和LaTeX文件设定不同的样式：

    1313. 

  1313. ```

    1314. 

  1314. %!style(html): fancy.css

    1315. 

  1315. %!style(tex) : amssymb

    1316. 

  1316. ```

    1317. 

  1317. 

    1318. 

  1318. 这一特性使得用户便于对转换后的文件进行微调：

    1319. 

  1319. ```

    1320. 

  1320. %!target: sgml

    1321. 

  1321. %!options(sgml): --toc

    1322. 

  1322. %!options(html): --style foo.css

    1323. 

  1323. %!options(txt ): --toc-only --toc-level 2

    1324. 

  1324. ```

    1325. 

  1325. 在这个例子中，缺省的目标格式为SGML，并且生成目录表。如果用户调用命令“``txt2tags -t html file.t2t”，则仅仅使用针对HTML定义的选项，生成的文件会使用外联的样式表“foo.css”，并且不生成目录表。

    1326. 

  1326. 

    1327. 

  1327. 

    1328. 

  1328. ++ 关于PreProc和PostProc过滤器的一些细节 ++[setting-filter-details]

    1329. 

  1329. 

    1330. 

  1330. - 按行进行“查找和替换”（类似与Sed）。

    1331. 

  1331. - 后定义的过滤器不会覆盖先定义的过滤器，而是累加的。因此你可以定义许多过滤器，它们会按照定义的顺序依次执行。

    1332. 

  1332. - 与其他的设定项不同，一般的和针对特定目标格式的过滤器均会被执行。在下面这个例子中，两个过滤器均会作用于HTML目标文件上：

    1333. 

  1333. ```

    1334. 

  1334. %!postproc      :   this   that

    1335. 

  1335. %!postproc(html):   that   other

    1336. 

  1336. ```

    1337. 

  1337. - 过滤器必须指定**两个**参数。

    1338. 

  1338. - 特定的转义字符，如换行符``\n``和制表符``\t``，均将被解释。

    1339. 

  1339. - 利用空字符进行替换，实现删除文本的功能：

    1340. 

  1340. ``` %!postproc: "undesired string" ""

    1341. 

  1341. - 使用PostProc替换标签时最好总是指明对应的目标格式，以避免出现问题：``%!PostProc(target): <thsi> <that>

    1342. 

  1342. - PreProc在行读入后立即起作用，而PostProc则是在所有的解析和处理过程结束后起作用，他们起作用的位置相当于：

    1343. 

  1343. ``` $ cat file.t2t | preproc.sh | txt2tags | postproc.sh

    1344. 

  1344. - 过滤器的“查找”过程使用正则表达式，而不是常规字符串。不理解什么是正则表达式也没关系，你只需记得某些特殊字符要使用反斜线“\”来进行“转义”就够了，这些特殊字符包括：

    1345. 

  1345. ``` \*  \+  \.  \^  \$  \?  \(  \)  \{  \[  \|  \\

    1346. 

  1346. - 支持Python的正则表达式（与Perl的正则表达式相似）。比如：在HTML中把标签“B”都替换为标签“STRONG”：

    1347. 

  1347. ``` %!postproc(html):   '(</?)B>'   '\1STRONG>'

    1348. 

  1348. - 过滤器参数有3种方式进行传递：

    1349. 

  1349.  + 单个未加引号的单词，诸如：FOO（不含空格）

    1350. 

  1350.  + 放在双引号中的字符串，诸如："FOO"

    1351. 

  1351.  + 放在单引号中的字符串，诸如：'FOO'

    1352. 

  1352. - 如果模式表达式包含双引号，将它放在一对单引号中保护起来，反之亦然。一些合法的模式表达式示例：

    1353. 

  1353. ```

    1354. 

  1354. %!postproc:   PATT    REPLACEMENT

    1355. 

  1355. %!postproc:  "PATT"  "REPLACEMENT"

    1356. 

  1356. %!postproc:  'PATT'  'REPLACEMENT'

    1357. 

  1357. %!postproc:   PATT   "REPLACEMENT"

    1358. 

  1358. %!postproc:  "PATT"  'REPLACEMENT'

    1359. 

  1359. ```

    1360. 

  1360. 

    1361. 

  1361. 

    1362. 

  1362. 

    1363. 

  1363. + 第八部分 黑魔法 +[black-magic]

    1364. 

  1364. 

    1365. 

  1365. 本章不推荐初级用户阅读。我们将在txt2tags的过滤器中使用一些复杂的模式和正则表达式，以此来实现一些“奇怪”的功能。

    1366. 

  1366. 

    1367. 

  1367. 	**请注意：**执行以下过程前建议谨慎，它们可能坏事，甚至于源文件中的某些文本在转换中会丢失，而不会出现在目标文件中。请在仅当你确实需要并且明白自己在干什么的情况下才使用这些技巧。

    1368. 

  1368. 

    1369. 

  1369. 	**注**：过滤器是强大却也危险的特性！

    1370. 

  1370. 	错误的过滤器会差生意想不到的结果。

    1371. 

  1371. 

    1372. 

  1372. 请切记！

    1373. 

  1373. 

    1374. 

  1374. ++ 使用%!PostProc插入多行文本（比如CSS规则） ++[postproc-multiline]

    1375. 

  1375. 

    1376. 

  1376. 过滤器中，用于替换的模式表达式可以包含多行（以 ``\n`` 作为换行符）。

    1377. 

  1377. 这便于在HTML目标文件中插入少量几行CSS规则，而毋需创建一个独立的外联样式表：

    1378. 

  1378. ```

    1379. 

  1379. %!postproc: <HEAD>      '<HEAD>\n<STYLE TYPE="text/css">\n</STYLE>'

    1380. 

  1380. %!postproc: (</STYLE>)  'body     { margin:3em               ;} \n\1'

    1381. 

  1381. %!postproc: (</STYLE>)  'a        { text-decoration:none     ;} \n\1'

    1382. 

  1382. %!postproc: (</STYLE>)  'pre,code { background-color:#ffffcc ;} \n\1'

    1383. 

  1383. %!postproc: (</STYLE>)  'th       { background-color:yellow  ;} \n\1'

    1384. 

  1384. ```

    1385. 

  1385. 如此，其余的过滤器通过替换一个插入的字符串而与第一个过滤器联系起来。现在，原来简单的一个“<HEAD>”变成了：

    1386. 

  1386. ```

    1387. 

  1387. <HEAD>

    1388. 

  1388. <STYLE TYPE="text/css">

    1389. 

  1389. body     { margin:3em               ;}

    1390. 

  1390. a        { text-decoration:none     ;}

    1391. 

  1391. pre,code { background-color:#ffffcc ;}

    1392. 

  1392. th       { background-color:yellow  ;}

    1393. 

  1393. </STYLE>

    1394. 

  1394. ```

    1395. 

  1395. 

    1396. 

  1396. ++ 使用%!PreProc创建“特定目标类型”的内容 ++[preproc-specific]

    1397. 

  1397. 

    1398. 

  1398. 有时候你打算在某一特定格式的目标文件中插入一些文本，而其他的格式则不作改变，这一目标可以通过PreProc的一些小技巧来实现。

    1399. 

  1399. 

    1400. 

  1400. 方法是：将这些文本作为注释插入源文件中，做上一些标记，而使用针对特定目标格式的过滤器将它们“反注释”掉。

    1401. 

  1401. 

    1402. 

  1402. 举个例子来说，我们想要在HTML输出中加入一个额外的段落，于是把这些文本写成特殊的注释行，比如：

    1403. 

  1403. ```

    1404. 

  1404. %html% This HTML page is Powered by [txt2tags http://txt2tags.org].

    1405. 

  1405. %html% See the source TXT file [here source.t2t].

    1406. 

  1406. ```

    1407. 

  1407. 

    1408. 

  1408. 这些行以%开头，属于普通的注释行，在转换时被忽略掉。但是当你添加一个过滤器之后：

    1409. 

  1409. ``` %!preproc(html): '^%html% ' ''

    1410. 

  1410. 

    1411. 

  1411. 通过显示的声明，这一过滤器仅仅在HTML作为目标格式时被应用。于是开头的百分号被移除，这些行被“激活”，不再是注释。

    1412. 

  1412. 

    1413. 

  1413. ++ 使用%!PreProc改变txt2tags标记 ++[creating-marks]

    1414. 

  1414. 

    1415. 

  1415. 对于某些正则表达式控来说，他可以自行定制源文件的语法，将txt2tags的默认标记修改为自己喜欢的标记。

    1416. 

  1416. 

    1417. 

  1417. 举个例子，位于行首的制表符是默认的引用标记，如果用户不喜欢，或者其编辑器关于制表符有奇怪的设定，他可以定义一个新的标记来标记引用域。比如他选择用用位于行首的“>>>”来作为引用标记，那么他只需定义一个简单的过滤器：

    1418. 

  1418. ``` %!PreProc: '>>> ' '\t'

    1419. 

  1419. 

    1420. 

  1420. 源文件里面的引用文本形如：

    1421. 

  1421. ```

    1422. 

  1422. >>> This is a quoted text.

    1423. 

  1423. >>> The user defined this strange mark.

    1424. 

  1424. >>> But they will be converted to TABs by PreProc.

    1425. 

  1425. ```

    1426. 

  1426. 

    1427. 

  1427. 在解析之前，这些诡异的“>>>”符号会被自动的替换为制表符，txt2tags则识别出引用标记。

    1428. 

  1428. 

    1429. 

  1429. 	**请注意：**极端的PreProc规则会改变整个标记语法，甚至会在标记之前产生冲突，因此在使用前务必小心谨慎。

    1430. 

  1430. 

    1431. 

  1431. --------------------------------------------------------

    1432. 

  1432. 

    1433. 

  1433. + 第九部分 软件历史 +[history]

    1434. 

  1434. 

    1435. 

  1435. Txt2tags的第一个公开发布的版本 version 0.1 是在2001年7月，然而其原型则比这个时间早上至少一年……

    1436. 

  1436. 

    1437. 

  1437. 本章将带领你纵览软件从最初的原型到当前版本的发展过程。

    1438. 

  1438. 

    1439. 

  1439. ++ 1999年1月：史前历史 ++

    1440. 

  1440. 

    1441. 

  1441. : 作者曰：

    1442. 

  1442. “我最初关于编写一个文本转换工具的尝试始于1999年，起初只是一个简单的、功能有限的Bourne Shell脚本，用来将标记文本转换为HTML页。哦是的，不过是又一个txt2html的工具，已经有无数人干过这个事情了……简单的说，它只能识别简单的标记比如 ``*bold*``、``/italic/``、``_under_``，以及转义典型的HTML特殊字符如 ``< & >``。不怎样对吧，但是！我还年轻呢，;)”

    1443. 

  1443. 

    1444. 

  1444. 

    1445. 

  1445. 

    1446. 

  1446. ++ 1999年6月：依然是史前历史 ++

    1447. 

  1447. 

    1448. 

  1448. : 作者还想说：

    1449. 

  1449. “几个月过后，关于SGML的宣传铺天盖地的淹没了我所任职的 Conectiva 公司，于是原来的txt2html变成了txt2sgml脚本。那时我正在学习SED，因此txt2sgml就成了一个110行的Bourne Shell脚本，其中包含了许多SED命令。”

    1450. 

  1450. 

    1451. 

  1451. 

    1452. 

  1452. 

    1453. 

  1453. 	注：SED是UNIX下的流编辑器，用来进行文本的自动化编辑。

    1454. 

  1454. 

    1455. 

  1455. 这一改进后的SGML版本支持更多的文档结构，比如列表、完全引用域等。在下面这个示例中，已经可以看到txt2tags标记的雏形了：

    1456. 

  1456. 

    1457. 

  1457. ```

    1458. 

  1458. * This was a bold line (BOLD line oriented? Well...)

    1459. 

  1459. 

    1460. 

  1460.   --

    1461. 

  1461. - bullet list was very similar to txt2tags list

    1462. 

  1462. - but with these -- to begin and close a list

    1463. 

  1463.   --

    1464. 

  1464. 

    1465. 

  1465. =----------------------

    1466. 

  1466. Verbatim text was delimited by the =-- pattern.

    1467. 

  1467. The other ------- were just cosmetic.

    1468. 

  1468. =----------------------

    1469. 

  1469. ```

    1470. 

  1470. 

    1471. 

  1471. 依然不怎样对吧。但是！接下来就是划时代的一步了……

    1472. 

  1472. 

    1473. 

  1473. ++ 2000年8月：不再是史前历史了 ++

    1474. 

  1474. 

    1475. 

  1475. : 作者又说：

    1476. 

  1476. “一年以后，那时我完全爱上了SED，于是我将 txt2sgml.sh 脚本重写，变成了一个包含350行的纯粹的SED脚本。一些激动人心的特性被加入进来，比如：subsection、URL识别和子列表（列表嵌套）。我用了将近一整年的时间来使用和改进这个脚本。”

    1477. 

  1477. 

    1478. 

  1478. 

    1479. 

  1479. 

    1480. 

  1480. 一个txt2sgml.sed的示例文件：

    1481. 

  1481. 

    1482. 

  1482. ```

    1483. 

  1483. * Hey, here are the first 3 magic lines

    1484. 

  1484. * The document title / author / date

    1485. 

  1485. * But they required those asterisks at the beginning

    1486. 

  1486. 

    1487. 

  1487. MAIN TITLE

    1488. 

  1488. 

    1489. 

  1489. Titles were made by uppercase-only lines. Subtitles were identified by

    1490. 

  1490. leading spaces. Each space denoted a new sublevel. The beautifiers:

    1491. 

  1491. *bold*, **strong**, "italic" and `typewriter`.

    1492. 

  1492. 

    1493. 

  1493. - lists

    1494. 

  1494.   + sublists

    1495. 

  1495.     = and subsublists (by identifier, not indentation)

    1496. 

  1496. 

    1497. 

  1497. 

    1498. 

  1498. Two blank lines to close lists. Links as www.example.com and e-mails

    1499. 

  1499. were recognized automagically by regular expressions. And there was a

    1500. 

  1500. strange image mark:

    1501. 

  1501. %%image: path/to/image.jpg

    1502. 

  1502. ```

    1503. 

  1503. 

    1504. 

  1504. ++ 2001年5月：Python化和多目标格式的想法 ++

    1505. 

  1505. 

    1506. 

  1506. : 现在是谁在说话呢？

    1507. 

  1507. “那时我开始动笔写《[Regular Expression book http://guia-er.sf.net/]》这本书。我仍然使用txt2sgml.sed的标记文本格式，将文件转换为SGML格式，然后用sgml2html工具转换为HTML，再在浏览器中“快速的”检查结果。因为“快速”与“sgml2html”并不相符，我将自己的SED脚本修改为txt2html.sed工具，用来直接产生HTML文档……可是出版商使用Adobe PageMaker来排版书籍，这可苦了我这样的Linux用户。幸好，我发现PageMaker使用的是一种类似于HTML的标记语言，于是最后我写了三个相似的SED脚本，用来将文本转换为SGML、HTML和PageMaker，此外还用一些Shell脚本来生成目录表，以及进行一些后处理。书写到一半的时候，我产生了将这些单一小工具合并起来的想法，并且选择用Python来完成这一工作。于是，TXT2TAGS诞生了。”

    1508. 

  1508. 

    1509. 

  1509. 

    1510. 

  1510. 

    1511. 

  1511. ++ 2001年7月：0.x系列：txt2tags的处女秀（公开发布） ++

    1512. 

  1512. 

    1513. 

  1513. : 是的，就是他在说：

    1514. 

  1514. “我的那本书的发行时间（7月31日），与txt2tags的第一个版本0.1版的发布时间（7月26日）只相隔几天——其中一个依赖于另一个，却是一起成长的。除了SGML、HTML和PageMaker之外，其他的目标格式也一并实现了：MoinMoin、MagicPoint以及纯文本。接下去的一年多时间里，0.x系列的更多版本发布了，程序也逐渐长大：新的目标格式 UNIX手册页，宏``%%date``，表格支持，基于网页的使用接口，图片智能对齐和生成目录表，这些功能一一实现。在0.2版本中，一个Shell脚本被添加进来作为外包，进行文件操作和命令行选项的处理——这样做的原因无非是因为我是个Shell老手，却是一个Python菜鸟。一直到0.9版本，txt2tags才又回到100%的Python代码。”

    1515. 

  1515. 

    1516. 

  1516. 

    1517. 

  1517. ++ 2002年9月：1.x系列：成长 ++

    1518. 

  1518. 

    1519. 

  1519. : 你是否已经没耐心听下去了？

    1520. 

  1520. “txt2tags的设想被证明是好的，我决定认真的来对待之。需要进行的下一步是散发程序，将它告诉全世界：我需要文档！于是，程序的网站上线了，邮件列表（英语和葡萄牙语）建立起来，用户指南也诞生了。用户群成长起来，并且为项目作出许多贡献。是的，我想，这证明这玩意儿是有用的。1.x版本添加的新特性包括：图形用户接口（GUI），Windows和Mac系统的移植，LaTeX目标格式，``%!style``设定项，``include``命令和强大的Pre/Post过滤器。”

    1521. 

  1521. 

    1522. 

  1522. 

    1523. 

  1523. 

    1524. 

  1524. ++ 2004月7月：2.x系列：成熟 ++

    1525. 

  1525. : 好吧，我也说得口干舌燥了：

    1526. 

  1526. “成长是奇特而又艰难的。我说过我是个Python菜鸟对吧？现在我变强了，然而过往的错误累积起来，于是无可避免的，源代码必须动一次大手术。这一次重写使得一些标记的兼容性变差了，于是我得创建一个升级脚本。这一次耗费了很长的时间，但是2.0版本终于还是发布了，它带来了数不清的新特性，诸如：XHTML目标格式，W3C验证码，i18n，以及RC文件。翻译团队将程序本身以及文档翻译成多种语言。LOUT目标格式被添加进来，此外还有新的宏：``%%mtime``、``%%infile``、``%%outfile``，以及``%%toc``。未完待续……”

    1527. 

  1527. 

    1528. 

  1528. 

    1529. 

  1529. The End

    1530. 

  1530. ([查看源文件 %%infile])

    1531. 

  1531. [IMGPATH/t2tpowered.png]

    1532. 

  1532. 

    1533. 

  1533. ========================================================

    1534. 

  1534. 译文最后一次修订于：%%mtime(%Y-%m-%d %X)

    1535. 

    1536.