Txt2tags用户指南 摘录

原著：Aurelio Marinho Jargas <verde@aurelio.net>
摘录：Abby Pan <abbypan@mail.ustc.edu.cn>

第一部分 - 介绍 Txt2tags

txt2tags的总览，介绍该程序用途及特性。

它是干嘛的？

Txt2tags是一个文本格式化和转换工具，写文档时可以专注于内容不怎么去折腾格式，跨平台。Txt2tags用很少的标记就能把纯文本文件转换成其支持的各种类型的目标文档。

支持的文本格式

下面把txt2tags支持的文本格式全列出来了：

支持的目标类型

HTML
没有用到javascript，或框架啥的，不过可以指定CSS样式。

XHTML
生成的XHTML代码比HTML严格。

SGML
sgml是一种很悍的格式，[sgmltools http://www.sgmltools.org]这里有sgml转换成html, pdf, ps, info, latex, lyx, rtf 和xml格式的文档的应用。(如sgml2html).

Txt2tags生成的SGML文件不要求更多其他的配置。

LATEX
Txt2tags生成可以直接编译的LaTex文档，省的你自己再写一堆标签。

LOUT
用途跟LaTeX差不多，不过语法比LaTeX简单点。 Txt2tags生成可以直接转换为PS或PDF文档的LOUT文件。

MAN
可以把手册内容做成其他格式的文档保存。

MGP
MagicPoint是用来作演示文稿的。

MOIN
MoinMoin是一种wiki啦。

PM6
Adobe PageMaker 6.0的标签格式。

TXT
格式化过的纯文本。

三种用户界面

支持三种界面：web页界面，图形界面，命令行界面。

前两种是傻瓜式的，命令行例子(假设源文件是file.t2t)：

转成html $ txt2tags -t html file.t2t
生成目录 $ txt2tags -t html --toc file.t2t
标题编号 $ txt2tags -t html --toc --enum-title file.t2t
从标准输入中读入 $ echo -e "\n**bold**" | txt2tags -t html --no-headers -

第二部分 - 下载安装

安装Python

系统要装有Python，版本>=1.5。

Windows版本

是编译过的，在这里：http://txt2tags-win.sf.net

设置文本编辑器中语法高亮

已有语法高亮文件的编辑器：

第三部分 - 撰写首份文档

写个文件test.txt，内容如下： 

  My First Document
  A txt2tags test
  Sunday, 2004
  
  Well, let's try this txt2tags thing.
  I don't know what to write.
  
  Mmmmmm, I know what I need to do now:
  - Take a shower
  - Eat a pizza
  - Sleep

命令行转换： 

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

然后在浏览器打开test.html看结果好了，注意前三行是头部信息。

第四部分 - 掌握Txt2tags建构

源文件按顺序分成三部分：

头部域 源文件头三行，或首行置空代表无头部信息。主要是该文件标题、作者、版本、时间等信息。
设置域 头部域结束，设置域就开始(第四或第二行)，一直到主体域开始的地方才结束。一些转换时的选项设置，比如使用什么css文件之类的。
主体域 从头部域后首个可用的文本行(不是注释或设置行)开始。放的是该文件的具体内容。

完整的例子

  My nice doc Title
  Mr. John Doe
  Last Updated: %%mtime(%c)
  
  %! Target  : html
  %! Style   : fancy.css
  %! Encoding: iso-8859-1
  %! Options : --toc --enum-title
  
  Hi! This is my test document.
  Its content will end here.

头部域

如果首行为空就是没有头部信息了。不然的话，头三行一般是这么放的啦：

设置域

位置：

主体域

在首个可用的文本行处开始，直到文件结束。 使用命令行选项--no-headers可以只转换文档主体，忽略头部信息。此时你可以在别的文件设置头部信息，等主体转换完毕再加进来。

设置

设置行放在源文档设置域中，在文档转换时起作用。语法格式如下： 

  %! 关键字 : 取值

可用关键字列表：

关键字 描述
Target 设置默认目标文档类型。
Options 设置转换时的默认选项，格式同命令行选项。
Style 指定文档样式。用于为HTML/XHTML指定CSS文件，或在LaTex中载入包。
Encoding 设置文档字符集。
PreProc 输入过滤器。对源文档进行“查找和替换”。
PostProc 输出过滤器。对目标文档进行“查找和替换”。

例子： 

  %! Target  : html
  %! Options : --toc --toc-level 3
  %! Style   : fancy.css
  %! Encoding: iso-8859-1
  %! PreProc : "AMJ"        "Aurelio Marinho Jargas"
  %! PostProc: '<BODY.*?>'  '<BODY bgcolor="yellow">'

命令行选项

-t或--target指定目标文档类型，这是转换时唯一必需指定的选项，其他都是可选的。

常用的还有：--outfile指定输出文件名，--toc指定自动生成目录， --encoding设置文档字符集。

如果该选项加上"no-"前缀，则表示关闭，比如：--no-encoding 和 --no-toc。

在源文档设置域中使用%!options指定该选项，效果相同。 例子：%!options: --toc -o mydoc.html。

但指定目标文档类型的选项有例外，是这么写的：%!target: html。

使用--help选项查看所有txt2tags可用的选项。

用户配置文件(RC文件)

用户配置文件(也叫RC文件)里的配置在每次转换的时候均起作用。

在各系统中默认存放位置可以通过指定环境变量进行修改。

RC文件位置
Windows %HOMEPATH%\_t2trc
Linux和其他操作系统 $HOME/.txt2tagsrc
用户指定 T2TCONFIG 环境变量

格式与.t2t文件中的设置域相同。 下面是安装包里面的示例RC文件doc/txt2tagsrc。例子： 

  % my configs
  
  %%% Always use CSS-friendly tags in HTML
  %!options(html): --css-sugar
  
  %%% Change the default TOC depth for all targets
  %!options: --toc-level 4
  
  %%% Set the default encoding for all documents
  %!options: --encoding iso-8859-1

该文件中任一个非空、非注释、不可用的设置行都会导致txt2tags在运行时出错。

Txt2tags运行时将自动读入RC文件中的设置。如果希望当前转换关闭RC文件的选项，则必须使用 命令行选项--no-rc。

载入设置的顺序及优先级

共有三种方法可以对txt2tags进行设置，其读入及应用顺序如下：

  1. 用户设置(RC)文件
  2. 源文档中的设置域中的设置
  3. 命令行选项

越晚读入则优先级越高，即，命令行选项优先级最高。 后面读入的选项将覆盖前面读入的相同关键字的选项。也就是说，如果在上面三个地方指定了三中不同的文档encoding，最后使用的只会是命令行里指定的那一种encoding。

%!include命令

include命令可以把外部文件内容加到源文件的主体中。这个不是一个配置项，而是一个命令，在文档主体域内有效。

用include命令可以把一个大文件的内容分解成好几个小文件单独存放，例子： 

  My first book
  Dr. John Doe
  1st Edition
  
  %!include: intro.t2t
  %!include: chapter1.t2t
  %!include: chapter2.t2t
  ...
  %!include: chapter9.t2t
  %!include: ending.t2t

只需在%!include之后指定文件名。

也可以顺便指定目标文档类型： 

  %!include(html): file.t2t

注意只是读入该文档的主体域，而忽略其头部域和设置域。

总共有三种不同的方法可以读入文件：

Verbatim型include保留文本中原始的空格和格式，效果与完全引用域(```)相同，格式如下： 

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

Raw型include不解析文本中的标记，效果与纯文本域(""")相同，格式如下： 

  %!include: ""nice_text.txt""

Tagged型include把文本内容直接加到转换后的文档中，可以用来添加头部或尾部信息，或txt2tags不能生成的一些标签，格式如下： 

  %!include(html): ''footer.html''

%!includeconf命令

includeconf命令用于从外部文件读入对当前文档的设置，仅在源文档设置域中有效。

多个文件使用相同设置时有效，把所有设置写入一个文件中，再使用includeconf调用该设置文件。例子： 

  My First Document
  John Doe
  July, 2004
  
  %!includeconf: config.t2t
  
  Hi, this is my first document.

语法格式与RC文件相同。

第五部分 - 掌握标记

基础 美化
头部 头3行 粗体 **文字**
标题 = 文字 = 斜体 //文字//
编号式标题 + 文字 + 下划线 __文字__
段落 文字 等宽 ``文字``
文本块 其他
引用 <TAB>文字 隔离行 --------...
列表 - 文字 粗隔离行 ============...
编号式列表 + 文字 链接 [标签 url地址]
定义式列表 : 文字 图片 [filename.jpg]
完全引用行 ``` 文字 注释 % 注释
完全引用域 ```\n 文字 \n``` 原文 ""文字""
原文行 """ 文字 表格 | 单元1 | 单元2 | 单元3...
原文域 """\n 文字 \n""" 锚 = 标题 =[锚标]

规则：

头部域

标题，编号式标题

段落

注释

粗体、斜体、下划线

等宽文本

完全引用行、完全引用域

隔离行，粗隔离行

链接，命名链接

引用

列表，编号式列表，定义式列表

图片

表格

纯文本，纯文本行，纯文本域

第六部分 - 掌握宏

宏用于插入当前日期等动态信息，在转换时被展开。

一个宏以%%标识，然后是宏名，如%%date。一些宏格式是可定制的，格式串放在宏名之后，以%标识，如%%date(%Y-%m-%d)。未定制时自动采用默认格式。

宏名 展开为... 默认格式
%%date 当前时间 %Y%m%d
%%mtime 源文件更新时间 %Y%m%d
%%infile 源文件路径 %f
%%outfile 输出文件路径 %f
%%toc 文档目录 -

规则：

例子(粗体部分是展开的宏):

This is the Txt2tags User Guide, converted to html by txt2tags from the t2t-guide-note.t2t source file. The conversion was done at 2013-06-22 19:17:35, but the last change on the source document was made on 2013-06-15 16:26:35. Both source and converted file reside on the t2t_guide_note directory.

%%date

%%date宏展开当前日期和时间，可用于得到源文档最后更新时间，参见%%mtime macro。

该宏支持的格式列表可以在Python站点找到。

下面列一些常用的：

指令 描述
%a 本地简写的星期名
%A 本地完整的星期名
%b 本地简写的月份名
%B 本地完整的月份名
%c 本地对应的日期和时间表示
%d 一个月中的第几天[01,31]
%H 24小时制的小时数[00,23]
%I 12小时制的小时数[01,12]
%m 一年中的第几个月[01,12]
%M 分钟数[00,59]
%p 本地的AM或PM时间
%S 秒钟数[00,61]. (1)
%x 本地日期简写
%X 本地时间简写
%y 两位数的年份表示[00,99]
%Y 四位数的年份表示
%% "%"字符

例子:

宏 --> 展开效果 2013-06-22 19:17
%%date(Converted on: %c) --> Converted on: Sat Jun 22 19:17:35 2013
%%date(%Y-%m-%d) --> 2013-06-22
%%date(%I:%M %p) --> 07:17 PM
%%date(Today is %A, on %B.) --> Today is Saturday, on June.

%%mtime

%%mtime宏展开为源文档最后更新时间，其格式指令与%%date macro相同。

比如，源文档最近的更新是在Sat Jun 15 16:26:35 2013，这个时间是用%%mtime(%c)展开得到的。

%%infile

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

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

指令 描述 宏表示
%f 文件名 t2t-guide-note.t2t
%F 文件名(不含扩展名) t2t-guide-note
%e 文件扩展名 t2t
%p 文件绝对路径 /home/panll/Dropbox/github/abbypan.github.com/doc/txt2tags/t2t_guide_note/t2t-guide-note.t2t
%d 文件目录路径 /home/panll/Dropbox/github/abbypan.github.com/doc/txt2tags/t2t_guide_note
%D 文件父目录路径 t2t_guide_note
%% "%"字符 %

例子:

源 --> 展开
This Guide parent dir is %%infile(%D). --> This Guide parent dir is t2t_guide_note.
I do use the %%infile(%e) file extension. --> I do use the t2t file extension.
[See the source %%infile] --> See the source
Converted to XHTML, I'll be %%infile(%F).xhtml --> Converted to XHTML, I'll be t2t-guide-note.xhtml
注: 若源为标准输入STDIN，则宏展开为"-"。

%%outfile

%%outfile宏展开为转换后的文件在系统中的路径信息，其格式指令与%%infile macro相同。

例子:

源 --> 展开
You are reading the %%outfile file. --> You are reading the t2t-guide-note.html file.
txt2tags -t %%outfile(%e) -i %%infile -o %%outfile --> txt2tags -t html -i t2t-guide-note.t2t -o t2t-guide-note.html
注: 若输出到为标准输出STDOUT，则宏展开为"-"。

%%toc

%%toc宏展开为文档的目录，想放哪就放哪。

该宏没有格式字串，使用规则如下：

第七部分 - 掌握设置

设置项置于源文档设置域中，在文档转换的时候生效。 所有的设置均是可选的。

设置项格式如下：

%! key : value

语法细节：

规则:

%!Target

使用target设置默认目标文档格式： 

  %!target: html

此时用户只需调用命令 

  $ txt2tags file.t2t

源文档将自动转换为预设的文件格式。

注意：%!target(tex): html无效。

%!Options

例如，用户在命令行这样进行转换： 

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

如果把这些选项写入源文档： 

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

现在命令行只要用"txt2tags file.t2t"就可以有同样的效果。 在Vi里边可以这样调命令： 

  :!txt2tags %

%!Encoding

设置目标文档字符集，参见所有的字符集列表。

LateX使用encoding别名，对此txt2tags内部会自动进行转换，所以还是可以用。 例子：

txt2tags/HTML > LaTeX
windows-1250 >>> cp1250
windows-1252 >>> cp1252
ibm850 >>> cp850
ibm852 >>> cp852
iso-8859-1 >>> latin1
iso-8859-2 >>> latin2
koi8-r >>> koi8-r

就算txt2tags无法识别，也可以通过，反正用户可以自己订encoding。

%!PreProc

PreProc在源文档被解析之前，对其按行进行“查找和替换”。

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

  %!preproc JJS          "John J. Smith"
  %!preproc RELEASE_DATE "2003-05-01"
  %!preproc BULLET       "[images/tiny/bullet_blue.png]"

源文档中的一行： 

  Hi, I'm JJS. Today is RELEASE_DATE.

txt2tags转换时，将此行视为： 

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

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

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

txt2tags在PreProc替换结束后开始解析。

%!PostProc

PostProc对转换后生成的文档按行进行“查找和替换”。

可以用于对转换生成文档做进一步加工。 例子： 

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

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

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

%!Style

对特定的目标类型定义设置

比如定义样式： 

  %!style(html): fancy.css
  %!style(tex) : amssymb

有针对性的进行微调： 

  %!target: sgml
  %!options(sgml): --toc
  %!options(html): --style foo.css
  %!options(txt ): --toc-only --toc-level 2

关于PreProc和PostProc过滤器的几点说明

第八部分 - 黑匣子

本章介绍一些进阶应用，要小心使用，不然很容易出错。

使用%!PostProc插入多行文本 (比如CSS规则)

使用换行符\n可以指定匹配时跨行。

在目标HTML中直接插入几行CSS规则： 

  %!postproc: <HEAD>      '<HEAD>\n<STYLE TYPE="text/css">\n</STYLE>'
  %!postproc: (</STYLE>)  'body     { margin:3em               ;} \n\1'
  %!postproc: (</STYLE>)  'a        { text-decoration:none     ;} \n\1'
  %!postproc: (</STYLE>)  'pre,code { background-color:#ffffcc ;} \n\1'
  %!postproc: (</STYLE>)  'th       { background-color:yellow  ;} \n\1'

现在"<HEAD>"变成这样： 

  <HEAD>
  <STYLE TYPE="text/css">
  body     { margin:3em               ;}
  a        { text-decoration:none     ;}
  pre,code { background-color:#ffffcc ;}
  th       { background-color:yellow  ;}
  </STYLE>

使用%!PreProc建立“指定目标类型”的内容

在这种情况下使用：你想在某种类型的目标文档中插入一些内容，而其他类型的目标文档不动。

例子： 

  %html% This HTML page is Powered by [txt2tags http://txt2tags.sf.net].
  %html% See the source TXT file [here source.t2t].

然后只有在指定目标类型为HTML时，这两行前面的注释符才会被PreProc提前去掉： 

  %preproc(html): '^%html% ' ''

使用%!PreProc转换txt2tags标记

可以利用正则表达式把txt2tags默认的标记换成自己比较顺手的符号，不过这个用起来也比较危险。

比如，设定>>>为制表符\t的标记： 

  %!PreProc: '>>> ' '\t'

此时，源文档中引用型文本可以写成： 

  >>> This is a quoted text.
  >>> The user defined this strange mark.
  >>> But they will be converted to TABs by PreProc.

在解析源文件之前，>>>就会被自动换成制表符，然后txt2tags就知道这个是引用型文本的标记。

最后更新时间：2013-06-15 16:26