PageRenderTime 89ms CodeModel.GetById 71ms app.highlight 7ms RepoModel.GetById 1ms 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

Large files files are truncated, but you can click here to view the full file

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

Large files files are truncated, but you can click here to view the full file