TXT2TAGS 2010年8月 %!target: man %!encoding: UTF-8 %!postproc(man): ' \(#\w+\)' '' %!options(html): --mask-email --toc %!postproc(html): '\n' = 名称 =[name] txt2tags - 文本格式化及转换工具 = 总览 =[synopsis] **txt2tags** [//选项//] [//文件//...] = 描述 =[description] **txt2tags** 读入含少量标记的文本,并将其转换为多种格式的文档: //ASCII Art//, //AsciiDoc//, //Creole//, //DocBook//, //DokuWiki//, //Google Code Wiki//, //HTML//, //LaTeX//, //Lout//, //MagicPoint//, //Man page//, //MoinMoin//, //PageMaker//, //Plain Text//, //PmWiki//, //SGML//, //Wikipedia// 和 //XHTML//. % TRANSLATOR: please keep the alphabetical order of this list. 此手册页是由**txt2tags**转换一个示例文本文件生成。并且该示例文本文件同时被转换成HTML,作为此手册页的在线版本。 单个源文件,多种格式的目标文件 - http://txt2tags.org = 标记 =[markup] ``` 头部 源文件的前3行 标题 = 文字 = 带数字编号的标题 + 文字 + 注释 % 注释内容 隔离行 -----------------------... 粗隔离行 =======================... 图片 [filename.jpg] 链接 [标签 url地址] 粗体 **文字** 斜体 //文字// 下划线 __文字__ 删除线 --文字-- 等宽 ``文字`` 原始文本 ""文字"" 标记文本 ''文字'' 段落 文字 引用 文字 列表 - 文字 带编号的列表 + 文字 定义式列表 : 文字 表格 | 单元格1 | 单元格2 | 单元格3... 完全引用行 ``` 文字 原文引用行 """ 文字 标记引用行 ''' 文字 完全引用块 ``` 多行文本 ``` 原文引用块 """ 多行文本 """ 标记引用块 ''' 多行文本 ''' ``` = 选项 =[options] : **--art-chars**=//PATTERN// 定义//PATTERN//为组成ASCII艺术字的字符模板,按以下顺序指定: 拐角,边框,侧面,一级块,二级块,二级水平线,三级水平线,四级水平线,五级水平线。 默认的模板是 +-|-==-^"。此选项只在输出目标格式为艺术ASCII时可用。 : **-C**, **--config-file**=//FILE// 从外部文件//FILE//中读入配置。配置项格式为//%!关键字:取值//,详情请见 [配置 #settings] 小节。 : **--css-sugar** 优化生成的嵌入CSS样式HTML/XHTML内容。移除标签属性,禁用样式属性,头部内容由H1、H2和H3组成,新建以下DIV: //#header//, //#body//, //.toc//。 : **--css-inside** 在HTML/XHTML头部嵌入CSS文件的内容。使用``--style``指定读入的CSS文件。 : **--dump-config** 输出所有配置项后退出。 : **--dump-source** 输出文档源文件,并展开 (``%!include``) 中的内容。 : **--encoding**=//CODE// 设置源文件转换成目标//CODE//时采用的字符集。例如 UTF-8 and iso-8859-1。 : **--gui** 启动TK图形界面。 : **-h**, **--help** 输出帮助信息后退出。 : **-H**, **--no-headers** 输出内容时不显示头部、尾部信息,只显示主体内容。 : **--headers** 输出内容时显示头部、尾部信息。此选项默认打开。 : **--height**=//NUM// 设置输出内容为//NUM//行。此选项只在目标文档格式为艺术ASCII、且指定``--slides``时可用。 : **-i**, **--infile**=//FILE// 指定//FILE//为输入的源文件名。如果指定为'-',则从STDIN读入源文本。 : **--mask-email** 隐藏邮件地址,以防止垃圾邮件地址收割。移除@和.。邮件地址 ""foo@bar.com"" 被转换为 。 : **-n**, **--enum-title** 对所有标题行进行自动编号。显示的前缀为 1, 1.1, 1.1.1, ... : **--no-dump-config** 取消``--dump-config``动作。 : **--no-dump-source** 取消``--dump-source``动作。 : **--no-encoding** 清除encoding设置。 : **--no-enum-title** 关闭标题自动编号的设置。 : **--no-infile** 清除之前所有infile的声明。 : **--no-targets** 取消``--targets``动作。 : **--no-mask-email** 关闭隐藏邮件地址的特性。 : **--no-outfile** 清除之前所有outfile的声明。 : **--no-quiet** 输出消息,关闭--quiet选项。 : **--no-rc** 不读入用户配置文件~/.txt2tagsrc。 : **--no-slides** 关闭演示文档特性。 : **--no-style** 清除所有样式设置。 : **--no-toc** 不输出目录。 : **--no-toc-only** 关闭``--toc-only``动作。 : **-o**, **--outfile**=//FILE// 指定输出的文件名为//FILE//。指定'-'则将结果输出到STDOUT。 : **-q**, **--quiet** 安静模式。关闭除了错误之外的所有其他消息输出。 : **--rc** 读入用户配置文件~/.txt2tagsrc。此选项默认打开。 : **--slides** 指定输出格式为演示文档,此选项只在输出目标格式为艺术ASCII时可用。 : **--style**=//FILE// 指定//FILE//作为目标文档的样式文件。用于指定HTML/XHTML文档使用的CSS文件,LaTeX文档使用的样式包。此选项可以多次使用,以指定多个样式文件。 : **-t**, **--target**=//TYPE// 指定输出目标文档的类型为//TYPE//。一些常用的类型为://html//, //xhtml//, //tex//, //man//, //txt//。使用``--targets``选项查看所有支持的目标文档类型。 : **--targets** 输出所有可用的目标文档类型后退出。 : **--toc** 在输出内容中包含自动生成的目录信息,置于头部内容和主体内容之间。也可以 通过`%%TOC``宏显示指定目录输出位置。 : **--toc-level**=//NUM// 指定目录最大深度为//NUM//。所有比//NUM//深的标题不会在目录中显示。 : **--toc-only** 输出目录后退出。 : **-v**, **--verbose** 在文档转换过程中输出详细的信息。此选项可以多次使用,以提高输出的消息量。 : **-V**, **--version** 输出程序版本后退出。 : **--width**=//NUM// 设置输出的宽度为//NUM//,此选项只在输出目标格式为艺术ASCII时可用。 : = 源文件 =[source] 源文件扩展名一般为//.t2t// (例如 ``myfile.t2t``)。可以在以下三个区域指定源文件: : **头部** (可选) 源文件的前三行。如果不需要头部信息,则源文件首行留空。 用于指定文档标题、作者、版本和日期信息。 : **配置** (可选) 紧接在头部信息之后(第4行或第2行),在主体内容之前结束。 用于指定各种配置项,格式为``%!关键字:取值``。 : **主体** 从头部区域之后的第一个有效文本行开始(非注释或配置),直至源文件结束。 用于指定文档内容。 : = 配置 =[settings] 配置用于定制**txt2tags**,与选项类似。配置项可以在源文件的配置区域,``~/.txt2tagsrc``文件,``--config-file``指定的外部文件中指定。 : **%!target** 配置输出目标文档类型,功能与``--target``相同。举例: ``` %!target: html : **%!options(target)** 设置该目标类型(target)文档的默认选项。必须以命令行的形式调用。举例: ``` %!options(html): --toc --toc-level 3 --css-sugar : **%!includeconf** 指定读入外部文件中包含的配置项,功能与``--config-file``相同。举例: ``` %!includeconf: myconfig.t2t : **%!style** 为目标文档指定样式文件,功能与``--style``相同。可以多次使用。举例: ``` %!style: colors.css : **%!encoding** 指定目标文档使用的字符集,功能与``--encoding``相同。举例: ``` %!encoding: UTF-8 : **%!preproc** 指定查找/替换的过滤器,在txt2tags解析源文档之前,改变源文档的内容。格式采用Python正则表达式。举例: ``` %!preproc: "JJS" "John J. Smith" : **%!postproc** 指定查找/替换的过滤器,在txt2tags转换源文档之后,改变目标文档的内容。格式采用Python正则表达式。举例: ``` %!postproc(html): "" "" : 如果同一个关键字多次出现,则以最后的取值为准(options, preproc and postproc是累计的除外)。异常关键字被忽略。解析顺序为:``~/.txt2tagsrc``,源文档的配置区域,``--config-file``命令行选项。 = 指令 =[commands] 指令在文本转换过程中生效。指令必须在源文件主体内容中指定。 : **%!csv: file.csv** 读入一个外部的CSV文件,作为表格。 : **%!include: file.t2t** 读入一个txt2tags文件。 : **%!include: ""``file.txt``""** 读入一个文本文件的内容,作为源文件的“原文引用块”。 : **%!include: ""''file.html''""** 读入一个标签文件内容到目标文档。 : = 宏 =[macros] 使用宏很容易在文档中插入动态内容。宏必须在源文件的主体内容中指定。 除了``%%toc``,所有宏都能够用修饰符指定格式,例如``%Y``和``%f``。详情请查看txt2tags用户指南。 : **""%%date""** 插入当前日期。默认格式是``%%date(%Y%m%d)``,输出YYYYMMDD。 : **""%%infile""** 插入源文件所在路径。默认格式是``%%infile(%f)``。常用尾部链接举例:``[查看源文件 %%infile]``。 : **""%%mtime""** 插入源文件修改时间。默认格式是``%%date(%Y%m%d)``,输出YYYYMMDD。 : **""%%outfile""** 输出目标文档所在路径。默认格式是``%%outfile(%f)``。常用的自引用形式举例:"这是 %%outfile 文件"。 : **""%%toc""** 指定目录信息所在位置。可以多次使用。注意同时指定``--toc``选项。 : = 示例 =[examples] : ``txt2tags -t html file.t2t`` 转换成HTML,将转换的结果输出到文件file.html。 : ``txt2tags -t html -o - file.t2t`` 转换成HTML,将转换的结果输出到STDOUT。 : ``txt2tags -t html --toc file.t2t`` 转换成HTML,包含自动生成的目录。 : ``txt2tags -t html --toc --toc-level 2 -n file.t2t`` 转换成HTML,并生成目录,目录深度为2,各项标题采用数字编号。 : ``txt2tags --toc-only file.t2t`` 只输出目录,不进行实际的转换。 : ``txt2tags -t html --css-sugar --style base.css --style ui.css file.t2t`` 转换成HTML,并预先设置采用CSS,同时指定引用两个外部CSS文件。 : ``txt2tags -t art --slides --width 80 --height 25 -o - file.t2t | more`` 生成艺术ASCII演示文档,用于在80x25的屏幕或窗口上演示。 : ``(echo ; echo "**bold**") | txt2tags -t html -H -`` 易用的单行指令,从STDIN读取内容做快速的测试。 : ``txt2tags -t html -o - file.t2t | tidy > file.html`` 将转换的结果输出到STDOUT,然后调用外部程序优化结果代码,最终保存到文件。 : = 文件 =[files] : ~/.txt2tagsrc 用户默认配置文件。 : = 环境 =[environment] : T2TCONFIG 该值设置用户默认配置文件的绝对路径。 : = 作者 =[author] 原文由Aurelio Jargas 编写。 中文版由Abby Pan 翻译。 = 缺陷 =[bugs] http://bugs.txt2tags.org = 版权 =[copyright] Copyright (C) 2001-%%date(%Y) Aurelio Jargas, GNU GPL v2