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