/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

Large files are truncated click here to view the full file

  1. Txt2tags用户指南
  2. %%date(%Y-%m-%d)
  3. %!target:html
  4. %%!target: tex
  5. %!encoding: UTF-8
  6. %!options(html): --toc --toc-level 2 --css-sugar
  7. %!options(tex): --toc --toc-level 2
  8. %!options(html): --style userguide.css
  9. %!preproc: IMGPATH ./img
  10. %!preproc(tex): '^ *--------*' ''
  11. %!preproc(tex): '^ *========*' ''
  12. ========================================================
  13. %%toc
  14. ========================================================
  15. = 关于本文 =[about]
  16. 本文根据[txt2tags http://txt2tags.org/](当前版本为2.5)的**用户指南**英文版翻译而来,读者可通过以下途径获得用户指南的英文原版:
  17. - 用户指南官方网址http://txt2tags.org/userguide
  18. - 用户指南的PDF版本http://txt2tags.org/userguide/userguide.pdf
  19. 本译文依照[创作共用约定署名-非商业性使用-相同方式共享3.0 http://creativecommons.org/licenses/by-nc-sa/3.0]发布。
  20. ========================================================
  21. + 第一部分 初识txt2tags +[chap1-intro]
  22. 本章为概述介绍txt2tags程序的用途和特色
  23. ++ 第一个可能的问题 ++[1st-question]
  24. +++ txt2tags是什么 +++
  25. txt2tags是一个文本格式化和转换工具能够将带有特定标记的纯文本文件转换为支持的任意一种目标格式包括
  26. - HTML文档
  27. - XHTML文档
  28. - SGML文档
  29. - LaTeX源文件
  30. - Unix手册页man page
  31. - MagicPoint演示文稿
  32. - Wikipedia维基百科页面
  33. - Google Wiki 页面
  34. - DokuWiki页面
  35. - MoinMoin页面
  36. - PageMaker 6.0 文档
  37. - 纯文本文件
  38. +++ 为什么使用txt2tags +++
  39. 你会发现txt2tags十分有用如果你
  40. - 需要将文档以不同格式发布
  41. - 需要以不同格式维护文档的更新
  42. - 撰写技术文档或者手册
  43. - 需要用你不熟悉的某种格式撰写文档
  44. - 对于某种文档格式缺少一个专门的编辑器
  45. - 想用一个简单的文本编辑器维护和更新你的文档
  46. 而最大的诱人之处在于
  47. - 节省时间专注于 **内容**抛开 **格式**
  48. +++ 相较于其他工具txt2tags有哪些优点 +++
  49. | **源文件可读性好** | txt2tags的标记非常简单使得源文件几乎是自然语言
  50. | **目标文件可读性好** | 与源文件一样生成的目标文件带有缩进和较短的行长度可读性好
  51. | **一致的标记** | txt2tags的标记是独特的足以适应各种文档而不至于与文档内容产生混淆
  52. | **一致的规则** | 每种标记与其对应的规则是一一对应的不存在例外特殊情形
  53. | **结构简单** | 所有支持的格式都是**简单的**不带有附加选项或者复杂的修饰标记只是标记而已没有任何选项
  54. | **易于学习** | 由于简单的标记和可读的源文件txt2tags的学习曲线非常的用户友好
  55. | **漂亮的示例** | 无论用txt2tags编写简单还是复杂的文档包含在软件包中的**示例文件**都给出了生动实用的例子
  56. | **有用的工具** | 包含于软件包中的**语法规则文件**帮助你写出没有语法错误的文档适用于vim, emacs, nano和kate
  57. | **三种用户接口** | //Tk//编写的**图形接口**,可供远程和内部网使用的**网页接口**,以及共高级用户和脚本使用的**命令行接口**。
  58. | **脚本** | 有经验的用户能够通过完全的命令行模式进行**自动任务**以及对转换后的文件进行**后编辑**
  59. | **下载运行和跨平台** | txt2tags只是一个简单的**Python 脚本**毋需编译或下载额外的模块因此在各种*NIXLinuxWindows和Macintosh主机上均能完美运行
  60. | **时常更新** | 活跃的邮件列表有用户提供修正和改进作者本人在工作和业余也在使用txt2tags因此开发不会无故终止
  61. +++ 我需要为此付费吗 +++
  62. || 当然不需要 |
  63. txt2tags在GPL许可证下发布并且完全免费
  64. ++ 支持的文档结构 ++[formats]
  65. 以下列出了txt2tags支持的文档结构
  66. - 头部文档标题作者日期
  67. - 章节标题带有/不带编号
  68. - 段落
  69. - 字体美化
  70. - 粗体
  71. - 斜体
  72. - 下划线
  73. - 删除线
  74. - 等宽字体完全引用
  75. - 段落内的等宽字体
  76. - 等宽的行
  77. - 等宽的区域多行
  78. - 引用
  79. - 链接
  80. - URL/Internet链接
  81. - e-mail链接
  82. - 本地链接
  83. - 命名的链接
  84. - 列表
  85. - 以符号引导的列表
  86. - 编号的列表
  87. - 定义列表
  88. - 水平分隔线
  89. - 图片智能对齐
  90. - 表格/不带边框智能对齐列贯穿
  91. - 针对原文域的特殊标记不解析
  92. - 对当前日期的特殊宏定义能灵活的改变格式
  93. - 注释作者备注TODOFIXME
  94. ++ 支持的目标文件格式 ++[targets]
  95. : **HTML**
  96. HTML是众所周知的格式提示Internet
  97. Txt2tags能生成干净漂亮源文件可读的HTML文档不使用JavaScript框架或是其他无效的简洁的技术文档所不需要的格式化技术但是可以使用独立的CSS文件txt2tags生成的代码符合//HTML 4.0 Transitional//”标准。
  98. 自2.0版起txt2tags生成的HTML代码100%通过[w3c validator validator.w3.org]的校验
  99. : **XHTML**
  100. 新一代的HTML具有更严格的语法所有的标记都必须闭合这使得代码更易理解和解析大体上来说可以将其看做HTMLTxt2tags生成的代码符合//XHTML 1.0 Transitional//”标准。
  101. 自2.0版起txt2tags生成的XHTML代码100%通过[w3c validator validator.w3.org]的校验
  102. : **SGML**
  103. 格式转换软件[SGML工具 www.sgmltools.org]的通用格式单一的SGML文件能转换为HTMLPDFPSinfoLaTeXLyxrtf以及XML格式的文档SGML2* 工具还能自动生成目录表以及按照章节将文件分割为子页sgml2html
  104. Txt2tags生成的SGML文件为Linux系统文档格式通过SGML2*工具能够直接转换而毋需任何额外的目录文件或是SGML那些恼人的要求
  105. : **LATEX**
  106. 超出你想象的强大格式学术论文的通用格式用它能生成整本的书复杂的公式以及任何复杂的文字格式然而如果你打算手写那些标记就准备掉头发吧
  107. Txt2tags将为你处理所有的细节和例外情形完成能够直接使用的LaTeX文档你只需考虑文字内容
  108. : **LOUT**
  109. 与LaTeX非常相似但是以@代替\作为命令引导符同时尽量避免使用括号一切皆对象的处理方式使得标记更加健壮
  110. Txt2tags能生成可以直接使用的文件通过lout命令即可转换为PDF或PS文件
  111. : **MAN**
  112. UNIX手册页
  113. 文档格式产生消亡来来去去UNIX手册页却存活多年始终坚挺
  114. 有各种工具可以生成手册页文档但是txt2tags自有其优势一个源文件多种产出物因此手册页的内容还能转换为HTMLMagicPoint演示文稿等等
  115. : **MGP**
  116. [MagicPoint www.mew.org/mgp]是一个非常方便的幻灯片工具就如同Microsoft PowerPoint它使用标记语言来定义每一屏显示因此你可以使用 vi/emacs/记事本 这样的文本编辑器来完成复杂的幻灯片
  117. Txt2tags为你完成所有被ISO-8859标准所支持的字体和外观的定义生成的.mgp文件能够直接使用
  118. **HOTSPOT 1:** txt2tags在生成的.mgp文件中使用XFree86 Type1字体因此你的幻灯片毋需额外配合TrueType字体
  119. **HOTSPOT 2:** 字体颜色的定义简洁即使在只有简陋调色板的系统中比如``startx -- -bpp 8``幻灯片依然美观
  120. 你需要做的只是转换然后使用毋需任何修复或是其他额外的工作
  121. : **WIKI**
  122. 想必你一定听说过[维基百科(Wikipedia) wikipedia.org]现在你不必另外学习一种新的标记语法txt2tags将为你把标记文本转换为维基百科的格式
  123. : **GWIKI**
  124. 使你能轻松的将项目文档粘贴到[Google Code code.google.com] Wiki
  125. : **DOKU**
  126. [DokuWiki http://wiki.splitbrain.org/wiki:dokuwiki]是一种遵从标准并且易于使用的Wiki,被设计来创建各种类型的文档,其目标群体包括开发团队、工作组以及小型公司。其语法简洁而强大,确保数据文件脱离Wiki仍然保有可读性,同时简化结构化文本的创建,所有的数据都以纯文本文件格式存储——毋需数据库。
  127. : **MOIN**
  128. [MoinMoin moinmo.in]是什么它是一种[WikiWiki www.c2.com/cgi/wiki]
  129. Moin的语法是有些乏味儿的你必须不断的``{{{'''''adding braces and quotes'''''}}}``Txt2tags为你带来简单的标记和统一的解决方案一个源文件多种产出物
  130. : **PM6**
  131. 我估猜你不会知道这是 Adobe PageMaker 6.0 独有的标记语言它包含了样式颜色表美化以及绝大部分PageMaker中的鼠标点击特性你可以通过Import Tagged text菜单项来使用它从记录上来看它具有类HTML的标记格式
  132. Txt2tags能生成所有的标记并且定义好丰富而有效的导言以设置段落样式和格式这个部分通常是让人头疼的**特别提醒**不能有断行每个段落必须是单独一行
  133. 作者按//笔者的《[regular expression's book http://guia-er.sf.net]》这本书的葡萄牙语版就是用VI编辑,再用txt2tags转换为PageMaker格式然后付印的。//)
  134. : **TXT**
  135. 纯文本唯一的真实格式
  136. 尽管txt2tags的标记非常直观而且不显眼你仍然可以选择移除它们只需将文件转换为纯文本即可
  137. 在源文件中标题添加下划线而文本则是左对齐的
  138. ++ 目标文件结构支持一览 ++[struct-support]
  139. || 结构 | html | xhtml | sgml | tex | lout | man | mgp | wiki | gwiki | doku | moin | pm6 | txt |
  140. | 头部 | Y | Y | Y | Y | Y | Y | Y | - | - | - | - | N | Y |
  141. | 章节标题 | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
  142. | 段落 | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
  143. | 粗体字 | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - |
  144. | 斜体字 | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - |
  145. | 下划线字体 | Y | Y | - | Y | Y | - | Y | Y | - | Y | Y | Y | - |
  146. | 删除线字体 | Y | Y | N | Y | - | - | - | Y | Y | Y | Y | N | - |
  147. | 等宽字体 | Y | Y | Y | Y | Y | - | Y | Y | Y | Y | Y | Y | - |
  148. | 未格式化行 | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - |
  149. | 未格式化区域 | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - |
  150. | 引用区域 | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
  151. | 超链接 | Y | Y | Y | - | - | - | - | Y | Y | Y | Y | - | - |
  152. | e-mail链接 | Y | Y | Y | - | - | - | - | Y | Y | Y | Y | - | - |
  153. | 本机链接 | Y | Y | Y | N | N | - | - | N | N | Y | Y | - | - |
  154. | 命名链接 | Y | Y | Y | - | - | - | - | Y | Y | Y | Y | - | - |
  155. | 列表 | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
  156. | 计数列表 | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
  157. | 定义列表 | Y | Y | Y | Y | Y | Y | N | Y | - | - | Y | N | Y |
  158. | 水平线 | Y | Y | - | Y | Y | - | Y | Y | - | Y | Y | N | Y |
  159. | 图片 | Y | Y | Y | Y | Y | - | Y | Y | Y | Y | Y | N | - |
  160. | 表格 | Y | Y | Y | Y | N | Y | N | Y | Y | Y | Y | N | N |
  161. || 附加结构 | html | xhtml | sgml | tex | lout | man | mgp | wiki | gwiki | doku | moin | pm6 | txt |
  162. | 图片对齐 | Y | Y | N | N | Y | - | Y | Y | - | Y | N | N | - |
  163. | 单元格对齐 | Y | Y | Y | Y | N | Y | N | N | - | - | Y | N | N |
  164. | 跨列单元格 | Y | Y | N | N | N | N | N | N | - | - | N | N | N |
  165. || | 图例
  166. | **Y** | 支持
  167. | **N** | 不支持后续版本可能会支持
  168. | **-** | 不支持在该目标格式中不存在
  169. ++ 三种用户接口GUI网页和命令行 ++[interfaces]
  170. 不同用户的需求和使用环境不同txt2tags相应的也具有灵活的执行方式
  171. 程序有三种用户接口每一种各有其目标和特性
  172. - **图形用户接口GUI**使用Tk写成支持窗口环境和鼠标点击
  173. - **网页**使用PHP开发支持通过浏览器运行txt2tags而毋需安装任何客户端程序
  174. - **命令行**程序的核心使用Python开发所有的特性都包含于命令行选项之中
  175. +++ 基于Tk的图形用户接口 +++[tk-interface]
  176. 自1.0版本开始txt2tags就有一个能工作于LinuxWindowsMac以及其他操作系统之上的图形用户接口
  177. 程序能自动检测你的系统能否显示图形如果可以则不带任何参数的命令调用时运行图形接口你也可以通过命令行参数 ``--gui`` 强制运行图形接口当某些资源缺失时程序给出错误信息
  178. 提示Tkinter是必须的因为Python的标准发布总是包含它实际上
  179. 你的系统中应该已经有了
  180. 图形界面的使用相当的简洁和直观
  181. [IMGPATH/gui.png]
  182. + 加载本机的.t2t文件其内部定义的选项将自动识别
  183. + 如果目标格式为空必须在此处指定
  184. + 此外还有一些选项可以附加选择但并非必须
  185. + 最后点击Convert!按钮
  186. 一个有用的选项是//Dump to screen//”,输出结果不会写到文件,而是显示于屏幕上,以便检查,确认无误之后再输出到文件存储。
  187. 界面的默认颜色可以通过修改 ``~/.txt2tagsrc`` 文件的 ``%!guicolors`` 设定来更改比如
  188. ```
  189. % set my own colors for the graphical interface (bg1, fg1, bg2, fg2)
  190. %!guicolors: blue white brown yellow
  191. ```
  192. +++ 在线方式 +++
  193. 基于Web的界面可以通过互联网地址http://txt2tags.org/online.php来访问,你可以在下载之前先试用txt2tags。
  194. [IMGPATH/web.png]
  195. Web接口也可以部署于本地局域网intranet免去在每台机器上安装txt2tags的麻烦
  196. +++ 命令行 +++
  197. 对于有经验的命令行用户来说``--help`` 选项提供的帮助信息应该足够了
  198. ```
  199. Usage: txt2tags [OPTIONS] [infile.t2t ...]
  200. -t, --target=TYPE set target document type. currently supported:
  201. html, xhtml, sgml, tex, lout, man, mgp, wiki,
  202. gwiki, doku, moin, pm6, txt
  203. -i, --infile=FILE set FILE as the input file name ('-' for STDIN)
  204. -o, --outfile=FILE set FILE as the output file name ('-' for STDOUT)
  205. -n, --enum-title enumerate all title lines as 1, 1.1, 1.1.1, etc
  206. -H, --no-headers suppress header, title and footer contents
  207. --headers show header, title and footer contents (default ON)
  208. --encoding set target file encoding (utf-8, iso-8859-1, etc)
  209. --style=FILE use FILE as the document style (like HTML CSS)
  210. --css-sugar insert CSS-friendly tags for HTML and XHTML targets
  211. --css-inside insert CSS file contents inside HTML/XHTML headers
  212. --mask-email hide email from spam robots. x@y.z turns <x (a) y z>
  213. --toc add TOC (Table of Contents) to target document
  214. --toc-only print document TOC and exit
  215. --toc-level=N set maximum TOC level (depth) to N
  216. --rc read user config file ~/.txt2tagsrc (default ON)
  217. --gui invoke Graphical Tk Interface
  218. -q, --quiet quiet mode, suppress all output (except errors)
  219. -v, --verbose print informative messages during conversion
  220. -h, --help print this help information and exit
  221. -V, --version print program version and exit
  222. --dump-config print all the config found and exit
  223. Turn OFF options:
  224. --no-outfile, --no-infile, --no-style, --no-encoding, --no-headers
  225. --no-toc, --no-toc-only, --no-mask-email, --no-enum-title, --no-rc
  226. --no-css-sugar, --no-css-inside, --no-quiet
  227. Example:
  228. txt2tags -t html --toc myfile.t2t
  229. By default, converted output is saved to 'infile.<target>'.
  230. Use --outfile to force an output file name.
  231. If input file is '-', reads from STDIN.
  232. If output file is '-', dumps output to STDOUT.
  233. ```
  234. ++++ 示例 ++++
  235. 假设你已经编写好一个正确标记的文件 ``file.t2t``现在我们来尝试一些转换
  236. | **转换为HTML** | ``$ txt2tags -t html file.t2t``
  237. | **转换为HTML使用输出重定向** | ``$ txt2tags -t html -o - file.t2t > file.html``
  238. | | .
  239. | **包含目录表** | ``$ txt2tags -t html --toc file.t2t``
  240. | **带数字编号的目录表** | ``$ txt2tags -t html --toc --enum-title file.t2t``
  241. | | .
  242. | **内容概览** | ``$ txt2tags --toc-only file.t2t``
  243. | **编号的概览** | ``$ txt2tags --toc-only --enum-title file.t2t``
  244. | | .
  245. | **从标准输入读取一行** | ``$ echo -e "\n**bold**" | txt2tags -t html --no-headers -``
  246. | **Email地址识别测试** | ``$ echo -e "\njohn.wayne@farwest.com" | txt2tags -t txt --mask-email --no-headers -``
  247. | **转换后编辑** | ``$ txt2tags -t html -o- file.t2t | sed "s/<BODY .*/<BODY BGCOLOR=green>/" > file.html``
  248. 提示从1.6版本起前处理和后处理可以通过 ``%!preproc``
  249. ``%!postproc`` 宏来完成
  250. --------------------------------------------------------
  251. + 第二部分 如何开始 +[install]
  252. 下载然后运行一切就是这么简单
  253. ++ 下载安装Python ++[download-python]
  254. 首先你必须下载安装Python解释器如果你的系统已经安装过Python请跳过本节
  255. Python是一种极好的编程语言能够跨平台的在WindowsLinuxUNIXMacintosh以及其他的操作系统上运行你可以从[Python主页 http://www.python.org/]找到安装文件以及安装指南。Txt2tags运行要求Python 2.0以后的版本。
  256. 如果你不确定是否已经安装过Python请打开一个控制台ttyxtermMSDOS输入命令 ``python``如果Python并未安装系统会给出错误信息
  257. ++ 下载txt2tags ++[download-txt2tags]
  258. Txt2tags的项目主页是http://txt2tags.org。全部程序文件打包成一个tarball压缩文件(.tgz 文件),你可以使用大多数的压缩工具来提取(包括WinZip)。请下载**最新**的版本,早期版本仅仅作为历史存档之用。
  259. ++ 安装txt2tags ++[install-txt2tags]
  260. 事实上txt2tags只是一个单文件的Python脚本毋需安装
  261. 运行程序需要的唯一一个文件是脚本 ``txt2tags``压缩包内的其他文件是软件的文档示例以及一些工具
  262. 最低级的使用txt2tags的方法是直接通过Python来调用
  263. ``` prompt$ python txt2tags
  264. 如果想将 txt2tags 作为一个能够直接运行的程序“安装”到系统,请将 txt2tags 脚本复制(或者创建一个链接)到系统 PATH 变量定义的目录,并且确认系统能够运行它。
  265. : UNIX/Linux/Mac
  266. 将脚本文件赋予执行权限(``chmod +x txt2tags``),然后复制到 $PATH 变量定义的目录下(比如:``cp txt2tags /usr/local/bin``)。
  267. : Windows
  268. 重命名脚本文件,添加 .py 作为扩展名(命令行下执行:``ren txt2tags txt2tags.py``),然后复制到系统 PATH 环境变量定义的路径下(比如:``copy txt2tags.py C:\WINNT``)
  269. 如果想要使用图形用户接口,你可以创建一个桌面启动器(快捷方式)。
  270. +++ 为Windows用户专门打包的安装程序 +++
  271. 对于Windows用户,txt2tags还有两个打包好的安装程序,你只需点击鼠标即可完成安装:
  272. - 单独的txt2tags脚本,针对已经安装过Python解释器的系统。
  273. - 独立运行的版本,毋需另外安装Python解释器(包含一个嵌入的版本)。
  274. 你可以访问 //Txt2tags-Win// 主页下载安装包:http://txt2tags-win.sf.net/
  275. ++ 安装编辑器的语法高亮文件 ++
  276. Txt2tags提供适合以下编辑器使用的语法高亮文件:
  277. - Vim (www.vim.org)
  278. - Emacs (www.emacs.org)
  279. - Nano (www.nano-editor.org)
  280. - Kate (http://kate.kde.org)
  281. - gedit ( http://www.gnome.org/projects/gedit/)
  282. - TextMate (http://macromates.com/ )
  283. 语法高亮文件包含全部txt2tags标记和规则,以帮助用户编写出无误的文档——正确书写的标记将以彩色显示。
  284. | [IMGPATH/vim.png]
  285. | 用Vim打开示例文件
  286. 语法文件对于不同的编辑器有不同的安装过程,请参考语法文件的头部说明和编辑器的文档。
  287. --------------------------------------------------------
  288. + 第三部分 第一个文档 +[your-1st-doc]
  289. ++ 先利其器 ++
  290. 你需要三件工具来完成你的第一次转换尝试:txt2tags,一个文本编辑器和一个网络浏览器。
  291. + 确认一下txt2tags是否已经安装并且能够正确运行。
  292. - **命令行方式**:执行“``txt2tags``”命令,程序会返回一个“缺少输入文件(Missing input file)”的信息。如果不能正确运行,尝试使用“``python /path/to/txt2tags``”,甚至“``/path/to/python /path/to/txt2tags``”以防止Python不在环境变量定义的路径中。
  293. - **图形化操作**:点击程序图标启动图形界面。
  294. + 开启你喜欢的文本编辑器——任何一个都行,无论是古老的 VI,还是 M$ Word,乃至 OpenOffice.org。用编辑器创建一个空文档作为你的第一个txt2tags源文件。
  295. + 启动你偏爱的浏览器,用来查看转换得到的HTML网页。
  296. ++ 编写文档头部 ++
  297. + 在编辑器中,在第一行写上文档的主标题://我的第一个文档//
  298. + 在第二行写上子标题://txt2tags测试//
  299. + 然后在第三行写上时间,比如://星期日,2009//
  300. 如果一切正常,现在你可以看到一个包含三行内容的文档:
  301. ```
  302. 我的第一个文档
  303. txt2tags测试
  304. 星期日2009
  305. ```
  306. 这只是一般文档的一部分,但是我们已经可以用它来尝试一下转换工作了。
  307. 将文档以文件名 ``test.txt`` 保存,记得要记住保存的路径,因为一会儿你要用到它。
  308. ++ 第一次转换——图形界面操作 ++
  309. 如果你使用命令行,请跳过本节,直接阅读下一节。
  310. 如果你使用图形界面,请跟着我做:
  311. [IMGPATH/firstdoc.png]
  312. + 点击“Browse”按钮,选择你刚才保存的 ``test.txt`` 文件。
  313. + 回到第一个窗口,在“Target document type”下拉菜单中选择“HTML page”。
  314. + 点击“Convert!”按钮。
  315. [IMGPATH/firstdoc-done.png]
  316. 这时会弹出一个对话框,告诉你文件已经成功的转换了。生成的HTML文件与源文件在同一个文件夹下,以“html”为扩展名。
  317. ++ 第一次转换——命令行方式 ++
  318. 如果你使用图形界面,请跳过本节直接阅读下一节。
  319. 如果你使用命令行方式,请切换到源文件所在的目录,执行:
  320. ``` txt2tags --target html test.txt
  321. 请注意在命令的各部分中间以空格分隔但是在选项字符串``--target``内部不能有空格这个选项后面紧跟着字符串``html``告诉程序你想要的目标文件格式最后一部分是源文件的文件名
  322. 如果转换正常完成结果会存储到文件 ``test.html`` 同时给出//txt2tags wrote test.html//”的信息。如果不是这样,程序会报错,提示你可能出错了,请仔细检查一下。
  323. 一个示例
  324. ```
  325. prompt$ txt2tags --target html test.txt
  326. txt2tags wrote test.html
  327. prompt$
  328. ```
  329. ++ 查看结果 ++
  330. 用浏览器打开文件 ``test.html`` 以检查是否正常
  331. [IMGPATH/firstdoc-html.png]
  332. 看见结果了吗你只是简单的输入了三行文字txt2tags则为你完成了所有设置HTML文件头部信息的工作对齐方式大小间隔以及外观文档的主标题同时也出现在了浏览器的标题栏中
  333. || 你只需输入文本txt2tags帮你搞定一切 ;) |
  334. 提示txt2tags生成的HTML页还能使用外部CSS以实现对页面外观100%的定制
  335. ++ 编写文档体 ++
  336. 现在返回文本编辑器进行下一步撰写文档的内容你可以像平日里撰写电子邮件一样的输入文字毋需特别的标记txt2tags会自动识别出段落和列表
  337. 然后再一次保存转换再查看结果这就是txt2tags文档的编写流程你可以把精力放在内容上更快的完成文件的编写毋需点鼠标毋需菜单没有窗口没有什么来分散你的注意力
  338. 假设文件 ``test.txt`` 中写上了如下的内容完全的纯文本将它们跟生成的HTML文件做一个对比
  339. ```
  340. 我的第一个文档
  341. txt2tags测试
  342. 星期日,2009
  343. 现在我们来试一试txt2tags好了。我也不晓得该写点啥……
  344. 唔……好吧,列一下我马上该去做的事情:
  345. - 洗个澡
  346. - 吃块批萨
  347. - 去睡觉
  348. ```
  349. [IMGPATH/firstdoc-fullhtml.png]
  350. 你毋需任何HTML语言的准备知识就能够编写出完整的主页不必插入任何标记进一步同一个源文件还可以转换为其他任何txt2tags所支持的格式
  351. 除了纯文本之外txt2tags有一些非常简单的标记来实现其他的格式和文档结构比如**粗体**//斜体//、标题、图片、表格,等等。举个简单的例子,``**产生粗体**``,``== 得到标题 ==``。详情请参阅[标记示例(Txt2tags Markup Demo) http://txt2tags.sourceforge.net/zh/markup-zh.html]。
  352. --------------------------------------------------------
  353. + 第四部分 掌握txt2tags的结构 +[concepts]
  354. ++ 文档的各个部分 ++[areas]
  355. Txt2tags的标记文本可以分为三个部分每个部分各自的规则实现不同的功能包括
  356. : //头部域(Header Area)//
  357. 放置文档标题作者版本号以及日期信息可选区域
  358. : //设置域(Config Area)//
  359. 定义全局设定修改解析时行为Place for general Document Settings and Parser behavior modifiers.可选区域
  360. : //主体域(Body Area)//
  361. 文件内容必须的区域
  362. 前两个区域是可选的只有 //主体域// 是必须的。
  363. 各个区域之间的分隔方式比较特别下一章会详细描述现在我们给出一个直观的图形化的描述
  364. ```
  365. ____________
  366. | |
  367. | HEADERS | 1. First, the Headers
  368. | |
  369. | CONFIG | 2. Then the Settings
  370. | |
  371. | BODY | 3. And finally the Document Body,
  372. | |
  373. | ... | which goes until the end
  374. | ... |
  375. |____________|
  376. ```
  377. 简单的说各个部分是这样定义的
  378. | **头部域** | 文件内容的前三行或者第一行是空白行表示没有头部
  379. | **设置域** | 紧接着头部第四行或者第二行开始结束于//主体域//的开始。
  380. | **主体域** | //头部//区域之后的第一个有效的行(非注释或设置)开始。
  381. +++ 完整的示例 +++
  382. ```
  383. My nice doc Title
  384. Mr. John Doe
  385. Last Updated: %%mtime(%c)
  386. %! Target : html
  387. %! Style : fancy.css
  388. %! Encoding: iso-8859-1
  389. %! Options : --toc --enum-title
  390. Hi! This is my test document.
  391. Its content will end here.
  392. ```
  393. ++ 头部域 ++[headers-area]
  394. 位置
  395. - 固定位置文件的**头三行**
  396. - 固定位置文件的**第一行**并且为空白行这意味着没有头部
  397. 头部是唯一固定位置和行数的区域总是出现在源文件的头三行各行的内容可以随意并没有特别的要求不过对于大多数的文档推荐以下的内容作为头部
  398. - //第一行//:文档标题
  399. - //第二行//:作者姓名和(或)邮件地址
  400. - //第三行//:文档的编写日期和(或)版本号(推荐使用宏 ``%%date``)
  401. 请记住源文件的头三行将会是目标文件的头三行在目标文件中会以高的对比与文档内容相区分比如大号字体粗体如果允许分页头部将会单独的在第一页居中显示
  402. ==== 较少或无头部 ====
  403. 有些时候作者会希望少于三行的头部仅仅给出文档标题和日期信息这时只需将第二行和第三行留为空行这部份就不会在目标文件中显示但是请切记即使是留为空白这些行仍然是头部的一部分主体域总是在这三行之后开始
  404. 只有标题第一行是必须的但是你也可以把它留白这意味着文档**没有头部**而主体域就紧接着从第二行开始如果你打算在完成转换之后再来定制头部信息那么没有头部的选择是很有用的命令行选项 ``--no-headers`` 通常用来完成这一操作
  405. ==== 总结 ====
  406. 简而言之**头部只是__位置__而非内容**
  407. 源文件的第一行会出现在目标文件的第一行二三行同样
  408. ++ 设置域 ++[config-area]
  409. 位置
  410. - 紧接着头部区域之后开始
  411. - 如果定义了**头部**则从**第四行**开始
  412. - 如果**无头部**则从**第二行**开始
  413. - 结束于主体域开始
  414. - 结束于一个非属性设定空白或者注释行
  415. 设置域是可选的普通用户甚至可以编写出许多txt2tags文档却不知道这个区域的存在但是有经验的用户往往受益于它提供的有效的控制功能设置域用来记录具体文档的设置这样就省略了转换时繁杂的命令行选项比如说你可以设定好缺省的目标文件类型和字符编码[设定 #settings]一节中对此有详细的叙述
  416. ++ 主体域 ++[body-area]
  417. 位置
  418. - 开始于第一个有效行
  419. - 头部设置域以及注释都**不是**有效的行
  420. - 结束于文件的末尾EOF
  421. 除了头部和设置域以外的所有内容都是主体域主体域包含来了文件的内容以及txt2tags支持的所有格式和文档结构的信息在主体域内你也可以放置注释作为 //TODOs// 和自提示。
  422. 命令行选项 ``--no-headers`` 会忽略头部只转换主体域的内容这是很有用的你可以用单独的文件来定义头部然后与转换后的主体域连接起来
  423. ++ 设定 ++[settings-overview]
  424. 设定Settings是特殊的配置选项位于文档的设置域内用以控制转换的过程设定的语法如
  425. ``` $! 关键词 : 设定值
  426. 以下是有效的关键词列表:
  427. || 关键词 | 描述 |
  428. | target | 设定缺省的目标文件格式。 |
  429. | options | 设定缺省的转换选项,格式与命令行选项相同。 |
  430. | style | 设定文档样式。主要用作为HTML/XHTML文档定义外联的CSS样式表,以及为LaTeX文档加载宏包。 |
  431. | encoding | 设定字符编码。当文档包含国际化字符和非ASCII字符时需要指定编码。 |
  432. | preproc | 输入文件处理。设定应用于源文件的主体域中的“查找/替换”规则。 |
  433. | postproc | 输出文件处理。设定应用与输出文件中的“查找/替换”规则。 |
  434. 示例:
  435. ```
  436. %! Target : html
  437. %! Options : --toc --toc-level 3
  438. %! Style : fancy.css
  439. %! Encoding: iso-8859-1
  440. %! PreProc : "AMJ" "Aurelio Marinho Jargas"
  441. %! PostProc: '<BODY.*?>' '<BODY bgcolor="yellow">'
  442. ```
  443. ++ 命令行选项 ++[cmd-options]
  444. 改变txt2tags默认行为最快捷的方式是使用命令行选项。顾名思义,这些选项只能应用于命令行方式,不适用于GUI和Web界面。
  445. 与其他工具一样,程序接受一串预定义的选项,每个选项都是由一个单连字符引导的字母,或者两个连续的连字符引导的一个或多个单词,比如 ``-t`` 和 ``--target``。“target”选项是唯一的一个必须的选项,其他的都是可省略的选项。
  446. 常用的选项包括:``--outfile``,指定输出文件名;``--toc``,自动生成目录表;``--encoding``,设定文档的字符编码。大多数的选项可以通过前缀一个“``no-``”来关闭,比如:``--no-encoding`` 和 ``--no-toc``。
  447. 使用 ``%!options`` 的格式,你可以在源文件的设置域设定需要的选项,这样在命令行中就可以省略掉这些选项了。比如:``%!options: --toc -o mydoc.html``。目标文件格式的指定是个例外,它有自己的格式:``%!target: html``。
  448. 使用 ``--help`` 选项能获得完整的选项列表。
  449. ++ 用户配置文件(RC文件) ++[rc]
  450. 通用的设定存储于用户配置文件(又称为RC文件)中。对于在每一个源文件中反复使用的设定,你可以把它们写到RC文件中,以便于所有的源文件使用。这个文件的缺省位置取决于你使用的操作系统,你也可以通过定义环境变量来指定其位置。
  451. || RC 文件的位置 ||
  452. | Windows | ``%HOMEPATH%\_t2trc``
  453. | Linux and other | ``$HOME/.txt2tagsrc``
  454. | User defined | ``T2TCONFIG`` 环境变量
  455. 设定的格式与源文件设置域中使用的选项格式完全相同。以下是包含在程序包的 ``doc/txt2tagsrc`` 的示例文件:
  456. ```
  457. % my configs
  458. %%% Always use CSS-friendly tags in HTML
  459. %!options(html): --css-sugar
  460. %%% Change the default TOC depth for all targets
  461. %!options: --toc-level 4
  462. %%% Set the default encoding for all documents
  463. %!options: --encoding iso-8859-1
  464. ```
  465. 除去空白行、注释行和有效配置行之外的任何一个多余的行,都会使得txt2tags在运行时产生错误,因此编辑这个文件时请尽量小心。
  466. 在执行转换时,程序自动将RC文件的内容应用于源文件,如果你想要关闭这一行为,则可使用命令行选项 ``--no-rc``。
  467. ++ 配置的优先级和加载顺序 ++[config-loading]
  468. 有三种方式告诉txt2tags需要使用的选项和设定,其读取和应用的顺序是:
  469. + 用户配置文件的设定
  470. + 源文件设置域的设定
  471. + 命令行选项
  472. 程序首先读取RC文件的内容(如果存在的话),并将相应的设置应用于当前源文件。然后它检查源文件的设置域的设定,如果找到,应用之并且覆盖掉RC文件的设定以壁面冲突。最后是命令行选项,它的效力比前两者都高。
  473. 这即是说,如果文档的字符编码同时用三种方式来设定,最终被应用的是命令行选项的设定。
  474. ++ %!include 指令 ++[include]
  475. ``include`` 命令用于将外部文件的内容包含进源文件中。它不是一个配置选项而是一个命令,对于主体域区域来说,则是一个有效的行。
  476. ``include`` 命令可用来将大型的文档分割为较小的片段(比如整本书中的章节),或者是将外部文件的全部内容包含进源文件中。比如:
  477. ```
  478. My first book
  479. Dr. John Doe
  480. 1st Edition
  481. %!include: intro.t2t
  482. %!include: chapter1.t2t
  483. %!include: chapter2.t2t
  484. ...
  485. %!include: chapter9.t2t
  486. %!include: ending.t2t
  487. ```
  488. 文件名接在字符串 ``%!include`` 后面。支持可选的“target”选项,因此下面的格式也是合法的:
  489. ``` %!include(html): file.t2t
  490. 注意include 命令将被包含文件的主体域区域读入源文件中而头部和设置域则被忽略所以你可以单独转换这个文件或者将它包含进主文档中一同转换
  491. 此外还有另外三种形式的包含
  492. - 完全引用Verbatim包含
  493. - 原文Raw包含
  494. - 带标记Tagged包含
  495. **完全引用Verbatim**包含会保留读入文件原始的空格和格式就像是txt2tags文件的完全引用VERB域一样要实现这种类型的包含请将文件名置于反引号中
  496. ``` %!include: ``/etc/fstab``
  497. **原文(Raw)**包含会照原样包含读入文件,不会寻找和解析其中的任何标记,就像之余原文(RAW)域中一样。要实现这种类型的包含,请将文件名置于双引号中:
  498. ``` %!include: ""nice_text.txt""
  499. **带标记Tagged**包含会将读入文件内容直接传递给目标文件txt2tags不会进行任何解析和控制这种方式适用于在文档中包含额外的带标记的内容对于缺省的头部或脚注信息以及txt2tags不支持的复杂标记十分有用
  500. ``` %!include: ''footer.html''
  501. 注意:请将文件名置于两个单引号中间。由于插入的内容是已经格式化的,你必须确认目标文件格式以防止出错。
  502. ++ %!includeconf 指令 ++[includeconf]
  503. ``includeconf`` 命令用于将外部配置文件读入当前文件中。这个命令仅在源文件的设置域内出现才是合法而有效的。
  504. 当多个文件共享同样的配置时,你可以将这些配置集中放置,然后用这个指令来读入。请在每个需要读入外部集中配置的文件中使用 ``includeconf`` 命令。比如:
  505. ```
  506. My First Document
  507. John Doe
  508. July, 2004
  509. %!includeconf: config.t2t
  510. Hi, this is my first document.
  511. ```
  512. 外部配置文件使用的格式与RC文件相同。
  513. --------------------------------------------------------
  514. + 第五部分 掌握标记 +[marks]
  515. txt2tags的全部标记概览:
  516. || 基本 || 美化 ||
  517. | //头部// | First 3 lines | //粗体// | ""**words**""
  518. | //标题// | = words = | //斜体// | ""//words//""
  519. | //带编号的标题// | + words + | //下划线// | ""__words__""
  520. | //段落// | words | //删除线// | ""--words--""
  521. | //链接// | ""[label url]"" | //等宽// | ""``words``""
  522. | //图片// | ""[filename.jpg]"" | //原始文字// | """"words""""
  523. || 其他 ||||
  524. | //引用// | <TAB>words | //分隔线// | ------------...
  525. | //列表// | - words | //粗分隔线// | ============...
  526. | //编号列表// | + words | //表格// | ""| cell1 | cell2 | cell3...""
  527. | //定义列表// | : words | //锚点(标签)// | = title =[anchor]
  528. | //注释行// | % comments | //注释域// | %%%\n comments \n%%%
  529. | //完全引用行// | ""```"" word | //完全引用域// | ""```\n lines \n```""
  530. | //原文行// | """"""" words | //原文域// | """""""\n lines \n"""""""
  531. 通用规则
  532. - **头部**是文档的头三行其中的标记不会解析
  533. - **标题**是包围标题文字的对称的=+字符字符越多标题级数越深
  534. - **美化符**会忽略标记与其中的内容之间的空格
  535. - **注释**符号%必须位于每一行的开头第一列
  536. - **图片**文件名必须以GIFJPGPNG或者类似的扩展名结束
  537. - 完全引用Verbatim和原文Raw中的标记不会被解析
  538. - **分隔线/粗分隔线**必须是连续20个字符以上
  539. - 引用和列表的**嵌套/解嵌套**通过缩进来定义
  540. - **表格标题**行通过位于行首的双管道符||来定义
  541. ++ 头部 ++[mark-headers]
  542. - **描述**确定文档头部
  543. - **属性**多行空格自由可自由包含空格下同原文FreeSpace无对齐无嵌套
  544. - **可包含**
  545. - **语法**
  546. - 源文件的头三行
  547. - 第一行留空则表示无头部适合于用户定制的头部原文Nice for command line oneliners or customized headers
  548. - 第二行和/或第三行留空将忽略头部的部分内容
  549. - **细节**
  550. - 头部域的标记**不会**被解析
  551. - 源文件的头三行也是目标文件的头三行在目标文件中与主体域以高对比来显示或者置于单独的第一页上如果允许分页的话
  552. - 头部的内容可以随意没有硬性规定的信息然而推荐使用下面的写法
  553. - 第一行文件标题
  554. - 第二行作者姓名和/或电子邮件
  555. - 第三行文档日期和/或版本号建议使用 ``%%mtime``
  556. ++ 标题与编号的标题 ++[mark-title]
  557. - **描述**确定一个编号或者不编号的章节标题
  558. - **属性**非多行空格自由无对齐无嵌套
  559. - **可包含**原始文本Raw
  560. - **语法**
  561. - 对于所有的规则+替代=可得到编号的标题
  562. - 包围文字的符号数目保持对称``=像这样=``
  563. - 符号数目增加章节深度随之增加``=title=, ==subtitle==, ===subsubtitle===, ...``
  564. - 最大深度为5级标题``=====像这样=====``
  565. - 数目不对称的标记不构成标题``=像这样===``
  566. - 标记包围的内部可以自由添加空格``= =``
  567. - 标题可以有锚点anchor``=像这样=[anchor]``可以创建一个到此锚点的链接形如 ``[本地链接 #anchor]``
  568. - 锚点名称只能由字母数字下划线和连字符构成A-Za-z0-9_-
  569. - **细节**
  570. - 标题中的其他标记不会解析
  571. - 标题中的宏不会解析
  572. ++ 段落 ++[mark-par]
  573. - **描述**确定一个自然段
  574. - **属性**多行空格自由无对齐无嵌套
  575. - **可包含**美化符原始文Raw链接图片注释
  576. - **语法**
  577. - 由空行分隔的多行文本构成段落
  578. - 其他的块如列表引用域表格或完全引用域等也可作为段落的结束
  579. ++ 注释 ++[mark-comment]
  580. - **描述**用于插入不会写入目标文件的文本
  581. - **属性**非多行非空格自由无对齐无嵌套
  582. - **可包含**
  583. - **语法**
  584. - 以一个百分号 % 起始的行%位于第一列构成一个注释行``%像这样``
  585. - **不能**有前导空格这就是所谓非空格自由
  586. - **细节**
  587. - 注释文本不会写入转换后的文件
  588. - 注释是非块状的因此每一个注释行都必须以 % 作为前导
  589. - 可用于 TODO FIXME 提示以及作者自提示
  590. ++ 粗体斜体下划线和删除线 ++[mark-beautifiers]
  591. - **描述**用于在段落表格列表和引用域内插入 粗体/斜体/下划线/删除线 字体
  592. - **属性**非多行非空格自由无对齐可嵌套
  593. - **可包含**美化符原始文Raw链接图片
  594. - **语法**
  595. - 双星号包围的文字产生**粗体**``**像这样**``
  596. - 双斜杠包围的文字产生//斜体//,``//像这样//``
  597. - 双下划线包围的文字产生__下划线__字体``__像这样__``
  598. - 双连字符包围的文字产生--删除线--字体``--像这样--``
  599. - 标记必须与内部的文字紧密贴合不能有空格``** 像这样 ** 是非法的``
  600. - **细节**
  601. - 源文件中每一对美化符都必须位于同一行中间不能有换行符
  602. - 美化符内可以包含宏比如``**%%date**``
  603. - 美化符可以混合使用``""**__like__ //this//**""``
  604. ++ 等宽字体 ++[mark-monospaced]
  605. - **描述**用于在段落表格列表和引用域内插入等宽字体的文本
  606. - **属性**非多行非空格自由无对齐无嵌套
  607. - **可包含**
  608. - **语法**
  609. - 用双反引号包围文字````像这样````
  610. - 标记必须与内部文字紧密贴合不能有空格```` 像这样 `` 是非法的``
  611. - **细节**
  612. - 内部的标记不会解析
  613. - 内部的宏不会解析
  614. - 所有的等宽文字必须位于单一行内不能有换行符
  615. - 在部分目标文件中内部的空格会被保留下来在其他的目标格式中连续的空格则被压缩为一个
  616. - 还可以得到粗体的等宽字体只需放置于粗体标记内部""``**monobold**``""这一规则对其他的美化符同样适用比如""``//italic//``"",""``__underline__``""。
  617. ++ 完全引用行和完全引用域 ++[mark-verbatim]
  618. - **描述**用于插入程序源代码或者其他预格式化的文本保留空格和换行符并以等宽字体显示
  619. - **属性**多行非空格自由无对齐无嵌套
  620. - **可包含**
  621. - **语法 - 完全引用行**
  622. - 以三个相继的反引号加一个空格引导后接文字""``` 像这样""
  623. - 反引号必须位于每行的第一列,不能有前导空格
  624. - **语法 - 完全引用域**:
  625. - 第一行为三个相继的反引号 ""```""从下一行开始为单行或多行文本最后一行为三个相继的反引号 ""```""
  626. - 标记不能有前导空格,也不能有后随的空格
  627. - **细节**:
  628. - 内部的标记不会解析
  629. - 内部的宏不会解析
  630. - 如果到达源文件末尾(EOF),尚未闭合的完全引用域将自动关闭
  631. ++ 隔离行和粗隔离行 ++[mark-seperator]
  632. - **描述**:生成水平线隔离行或者粗隔离行
  633. - **属性**:非多行,空格自由,无对齐,无嵌套
  634. - **可包含**:无
  635. - **语法**:
  636. - 隔离行由多个虚线“-”或者下划线“_”构成
  637. - 粗隔离行由多个等号“=”组成
  638. - 至少包括20个相应的字符
  639. - 线可以有前导和后随的空格
  640. - 在同一行的任何其他字符将破坏标记
  641. - **细节**:
  642. - 如果目标格式不支持水平线,自动转化为一个注释行
  643. - 粗隔离行在某些目标格式中可能有不同的作用:
  644. - 更粗的隔离行
  645. - 放映暂停,比如在 MagicPoint 中
  646. - 分页,比如在 LaTeX 中
  647. ++ 链接和命名链接 ++[mark-link]
  648. - **描述**:确定一个指向互联网或本地的链接
  649. - **属性**:非多行,非空格自由,无对齐,无嵌套
  650. - **可包含**:宏,原始文(Raw),图片
  651. - **语法**:
  652. - 合法的URL、ftp、新闻组或电子邮件地址能被程序自动识别并转换为超链接
  653. - 协议(http,https,ftp等)可省略,如:``www.likethis.com``
  654. - 可以为链接命名,如:``[click here www.url.com]``
  655. - 可以创建图片链接:``[[image.jpg] www.url.com]``
  656. - 链接地址允许宏替换:``[see source %%infile]``
  657. - 链接名字允许宏替换:``[mirror of %%outfile www.url.com]``
  658. - 全部链接标识符必须位于源文件的同一行内,不能有换行符
  659. - **细节**:
  660. - 如果目标格式不支持链接,则链接文字仅仅加上下划线
  661. ++ 引用 ++[mark-quote]
  662. - **描述**:确定一个引用(缩进)行
  663. - **属性**:多行,非空格自由,无对齐,可嵌套
  664. - **可包含**:宏,美化符,引用,原始文,Bars,链接,图片,注释
  665. - **语法**:
  666. - 以一个制表符(TAB)开始的一行
  667. - 更多的制表符则增加引用缩进的深度
  668. - 引用行能不允许列表和表格
  669. - **细节**:
  670. - 如果到达文件末尾(EOF),尚未闭合的引用自动关闭
  671. - 某些目标格式不支持引用嵌套,则子嵌套自动外移到与外层嵌套同级
  672. - 引用深度原则上没有限制,但某些目标格式可能会有限制,则超过最大深度的子嵌套自动外移。
  673. ++ 列表,编号列表和定义列表 ++[mark-list]
  674. - **描述**:确定列表项开始
  675. - **属性**:多行,非空格自由,无对齐,可嵌套
  676. - **可包含**:宏,美化符,列表,表格,完全引用,原始文,Bars,链接,图片,注释
  677. - **语法**:
  678. - 以单个 虚线“-”/加号“+”/冒号“:” 紧接单个空格开始一行
  679. - 列表项的第一个字符不能是空格(定义列表除外)
  680. - 可选的前导空格(普通空格,非制表符)将开始一个子列表(列表嵌套)
  681. - 子列表以较少深度的表项或者空表项结束
  682. - 所有开放的列表以两个相继的空行结束
  683. - **细节**:
  684. - 如果到达文件末尾(EOF),所有尚未闭合的列表自动关闭
  685. - 列表可以混合使用,比如编号列表内部可以嵌套定义列表
  686. - 某些目标格式可能不支持列表嵌套,则子列表自动外移到与外层列表同级
  687. - 嵌套深度原则上没有限制,但是某些目标格式可能会有限制,则超过最大深度的子列表自动外移
  688. ++ 图片 ++[…