/doc/Chinese/manpage-zh.man

  1.TH "TXT2TAGS" 1 "2010年8月" ""
  2
  3
  4.SH 名称
  5
  6.P
  7txt2tags \- 文本格式化及转换工具 
  8
  9.SH 总览
 10
 11.P
 12\fBtxt2tags\fR [\fI选项\fR] [\fI文件\fR...]
 13
 14.SH 描述
 15
 16.P
 17\fBtxt2tags\fR 读入含少量标记的文本，并将其转换为多种格式的文档：
 18\fIASCII Art\fR,
 19\fIAsciiDoc\fR,
 20\fICreole\fR,
 21\fIDocBook\fR,
 22\fIDokuWiki\fR,
 23\fIGoogle Code Wiki\fR,
 24\fIHTML\fR,
 25\fILaTeX\fR,
 26\fILout\fR,
 27\fIMagicPoint\fR,
 28\fIMan page\fR,
 29\fIMoinMoin\fR,
 30\fIPageMaker\fR,
 31\fIPlain Text\fR,
 32\fIPmWiki\fR,
 33\fISGML\fR,
 34\fIWikipedia\fR 和
 35\fIXHTML\fR.
 36
 37.P
 38此手册页是由\fBtxt2tags\fR转换一个示例文本文件生成。并且该示例文本文件同时被转换成HTML，作为此手册页的在线版本。
 39
 40.P
 41单个源文件，多种格式的目标文件 \- http://txt2tags.org
 42
 43.SH 标记
 44
 45.nf
 46头部                源文件的前3行
 47标题                = 文字 =
 48带数字编号的标题    + 文字 +
 49注释                % 注释内容
 50隔离行              -----------------------...
 51粗隔离行            =======================...
 52图片                [filename.jpg]
 53链接                [标签 url地址]
 54
 55粗体                **文字**
 56斜体                //文字//
 57下划线              __文字__
 58删除线              --文字--
 59等宽                ``文字``
 60原始文本            ""文字""
 61标记文本            ''文字''
 62
 63段落                文字
 64引用                <TAB>文字
 65列表                 - 文字
 66带编号的列表        + 文字
 67定义式列表          : 文字
 68表格                | 单元格1 | 单元格2 | 单元格3...
 69
 70完全引用行          ``` 文字
 71原文引用行          """ 文字
 72标记引用行          ''' 文字
 73
 74完全引用块          ```
 75                    多行文本
 76                    ```
 77原文引用块          """
 78                    多行文本
 79                    """
 80标记引用块          '''
 81                    多行文本
 82                    '''
 83.fi
 84
 85
 86.SH 选项
 87
 88.TP
 89    \fB\-\-art\-chars\fR=\fIPATTERN\fR
 90定义\fIPATTERN\fR为组成ASCII艺术字的字符模板，按以下顺序指定：
 91拐角，边框，侧面，一级块，二级块，二级水平线，三级水平线，四级水平线，五级水平线。
 92默认的模板是 +\-|\-==\-^"。此选项只在输出目标格式为艺术ASCII时可用。
 93
 94.TP
 95\fB\-C\fR, \fB\-\-config\-file\fR=\fIFILE\fR
 96从外部文件\fIFILE\fR中读入配置。配置项格式为\fI%!关键字:取值\fR，详情请见
 97配置 小节。
 98
 99.TP
100    \fB\-\-css\-sugar\fR
101优化生成的嵌入CSS样式HTML/XHTML内容。移除标签属性，禁用样式属性，头部内容由H1、H2和H3组成，新建以下DIV：
102\fI#header\fR, \fI#body\fR, \fI.toc\fR。
103
104.TP
105    \fB\-\-css\-inside\fR
106在HTML/XHTML头部嵌入CSS文件的内容。使用\-\-style指定读入的CSS文件。
107
108.TP
109    \fB\-\-dump\-config\fR
110输出所有配置项后退出。
111
112.TP
113    \fB\-\-dump\-source\fR
114输出文档源文件，并展开 (%!include) 中的内容。
115
116.TP
117    \fB\-\-encoding\fR=\fICODE\fR
118设置源文件转换成目标\fICODE\fR时采用的字符集。例如 UTF\-8 and iso\-8859\-1。
119
120.TP
121    \fB\-\-gui\fR
122启动TK图形界面。
123
124.TP
125\fB\-h\fR, \fB\-\-help\fR
126输出帮助信息后退出。
127
128.TP
129\fB\-H\fR, \fB\-\-no\-headers\fR
130输出内容时不显示头部、尾部信息，只显示主体内容。
131
132.TP
133    \fB\-\-headers\fR
134输出内容时显示头部、尾部信息。此选项默认打开。
135
136.TP
137    \fB\-\-height\fR=\fINUM\fR
138设置输出内容为\fINUM\fR行。此选项只在目标文档格式为艺术ASCII、且指定\-\-slides时可用。
139
140.TP
141\fB\-i\fR, \fB\-\-infile\fR=\fIFILE\fR
142指定\fIFILE\fR为输入的源文件名。如果指定为'\-'，则从STDIN读入源文本。
143
144.TP
145    \fB\-\-mask\-email\fR
146隐藏邮件地址，以防止垃圾邮件地址收割。移除@和.。邮件地址
147foo@bar.com 被转换为 <foo (a) bar com>。
148
149.TP
150\fB\-n\fR, \fB\-\-enum\-title\fR
151对所有标题行进行自动编号。显示的前缀为 1, 1.1, 1.1.1, ... 
152
153.TP
154    \fB\-\-no\-dump\-config\fR
155取消\-\-dump\-config动作。
156
157.TP
158    \fB\-\-no\-dump\-source\fR
159取消\-\-dump\-source动作。
160
161.TP
162    \fB\-\-no\-encoding\fR
163清除encoding设置。
164
165.TP
166    \fB\-\-no\-enum\-title\fR
167关闭标题自动编号的设置。
168
169.TP
170    \fB\-\-no\-infile\fR
171清除之前所有infile的声明。
172
173.TP
174    \fB\-\-no\-targets\fR
175取消\-\-targets动作。
176
177.TP
178    \fB\-\-no\-mask\-email\fR
179关闭隐藏邮件地址的特性。
180
181.TP
182    \fB\-\-no\-outfile\fR
183清除之前所有outfile的声明。
184
185.TP
186    \fB\-\-no\-quiet\fR
187输出消息，关闭\-\-quiet选项。
188
189.TP
190    \fB\-\-no\-rc\fR
191不读入用户配置文件~/.txt2tagsrc。
192
193.TP
194    \fB\-\-no\-slides\fR
195关闭演示文档特性。
196
197.TP
198    \fB\-\-no\-style\fR
199清除所有样式设置。
200
201.TP
202    \fB\-\-no\-toc\fR
203不输出目录。
204
205.TP
206    \fB\-\-no\-toc\-only\fR
207关闭\-\-toc\-only动作。
208
209.TP
210\fB\-o\fR, \fB\-\-outfile\fR=\fIFILE\fR
211指定输出的文件名为\fIFILE\fR。指定'\-'则将结果输出到STDOUT。
212
213.TP
214\fB\-q\fR, \fB\-\-quiet\fR
215安静模式。关闭除了错误之外的所有其他消息输出。
216
217.TP
218    \fB\-\-rc\fR
219读入用户配置文件~/.txt2tagsrc。此选项默认打开。
220
221.TP
222    \fB\-\-slides\fR
223指定输出格式为演示文档，此选项只在输出目标格式为艺术ASCII时可用。
224
225.TP
226    \fB\-\-style\fR=\fIFILE\fR
227指定\fIFILE\fR作为目标文档的样式文件。用于指定HTML/XHTML文档使用的CSS文件，LaTeX文档使用的样式包。此选项可以多次使用，以指定多个样式文件。
228
229.TP
230\fB\-t\fR, \fB\-\-target\fR=\fITYPE\fR
231指定输出目标文档的类型为\fITYPE\fR。一些常用的类型为：\fIhtml\fR, \fIxhtml\fR, \fItex\fR, \fIman\fR, \fItxt\fR。使用\-\-targets选项查看所有支持的目标文档类型。
232
233.TP
234    \fB\-\-targets\fR
235输出所有可用的目标文档类型后退出。
236
237.TP
238    \fB\-\-toc\fR
239在输出内容中包含自动生成的目录信息，置于头部内容和主体内容之间。也可以
240通过`%%TOC``宏显示指定目录输出位置。 
241
242.TP
243    \fB\-\-toc\-level\fR=\fINUM\fR
244指定目录最大深度为\fINUM\fR。所有比\fINUM\fR深的标题不会在目录中显示。
245
246.TP
247    \fB\-\-toc\-only\fR
248输出目录后退出。
249
250.TP
251\fB\-v\fR, \fB\-\-verbose\fR
252在文档转换过程中输出详细的信息。此选项可以多次使用，以提高输出的消息量。
253
254.TP
255\fB\-V\fR, \fB\-\-version\fR
256输出程序版本后退出。
257
258.TP
259    \fB\-\-width\fR=\fINUM\fR
260设置输出的宽度为\fINUM\fR，此选项只在输出目标格式为艺术ASCII时可用。
261
262.SH 源文件
263
264.P
265源文件扩展名一般为\fI.t2t\fR (例如 myfile.t2t)。可以在以下三个区域指定源文件：
266
267.TP
268\fB头部\fR (可选)
269源文件的前三行。如果不需要头部信息，则源文件首行留空。
270用于指定文档标题、作者、版本和日期信息。
271
272.TP
273\fB配置\fR (可选)
274紧接在头部信息之后（第4行或第2行），在主体内容之前结束。
275用于指定各种配置项，格式为%!关键字:取值。
276
277.TP
278\fB主体\fR
279从头部区域之后的第一个有效文本行开始（非注释或配置），直至源文件结束。
280用于指定文档内容。
281
282.SH 配置
283
284.P
285配置用于定制\fBtxt2tags\fR，与选项类似。配置项可以在源文件的配置区域，~/.txt2tagsrc文件，\-\-config\-file指定的外部文件中指定。
286
287.TP
288\fB%!target\fR
289配置输出目标文档类型，功能与\-\-target相同。举例：
290.nf
291%!target: html
292.fi
293
294
295
296.TP
297\fB%!options(target)\fR
298设置该目标类型（target）文档的默认选项。必须以命令行的形式调用。举例：
299.nf
300%!options(html): --toc --toc-level 3 --css-sugar
301.fi
302
303
304
305.TP
306\fB%!includeconf\fR
307指定读入外部文件中包含的配置项，功能与\-\-config\-file相同。举例：
308.nf
309%!includeconf: myconfig.t2t
310.fi
311
312
313
314.TP
315\fB%!style\fR
316为目标文档指定样式文件，功能与\-\-style相同。可以多次使用。举例：
317.nf
318%!style: colors.css
319.fi
320
321
322
323.TP
324\fB%!encoding\fR
325指定目标文档使用的字符集，功能与\-\-encoding相同。举例：
326.nf
327%!encoding: UTF-8
328.fi
329
330
331
332.TP
333\fB%!preproc\fR
334指定查找/替换的过滤器，在txt2tags解析源文档之前，改变源文档的内容。格式采用Python正则表达式。举例：
335.nf
336%!preproc:  "JJS"  "John J. Smith"
337.fi
338
339
340
341.TP
342\fB%!postproc\fR
343指定查找/替换的过滤器，在txt2tags转换源文档之后，改变目标文档的内容。格式采用Python正则表达式。举例：
344.nf
345%!postproc(html):  "<B>"  "<STRONG>"
346.fi
347
348
349
350.P
351如果同一个关键字多次出现，则以最后的取值为准（options, preproc and postproc是累计的除外）。异常关键字被忽略。解析顺序为：~/.txt2tagsrc，源文档的配置区域，\-\-config\-file命令行选项。
352
353.SH 指令
354
355.P
356指令在文本转换过程中生效。指令必须在源文件主体内容中指定。
357
358.TP
359\fB%!csv: file.csv\fR
360读入一个外部的CSV文件，作为表格。
361
362.TP
363\fB%!include: file.t2t\fR
364读入一个txt2tags文件。
365
366.TP
367\fB%!include: ``file.txt``\fR
368读入一个文本文件的内容，作为源文件的“原文引用块”。
369
370.TP
371\fB%!include: \&''file.html''\fR
372读入一个标签文件内容到目标文档。
373
374.SH 宏
375
376.P
377使用宏很容易在文档中插入动态内容。宏必须在源文件的主体内容中指定。
378除了%%toc，所有宏都能够用修饰符指定格式，例如%Y和%f。详情请查看txt2tags用户指南。
379
380.TP
381\fB%%date\fR
382插入当前日期。默认格式是%%date(%Y%m%d)，输出YYYYMMDD。
383
384.TP
385\fB%%infile\fR
386插入源文件所在路径。默认格式是%%infile(%f)。常用尾部链接举例：[查看源文件 %%infile]。
387
388.TP
389\fB%%mtime\fR
390插入源文件修改时间。默认格式是%%date(%Y%m%d)，输出YYYYMMDD。
391
392.TP
393\fB%%outfile\fR
394输出目标文档所在路径。默认格式是%%outfile(%f)。常用的自引用形式举例："这是 manpage\-zh.man 文件"。
395
396.TP
397\fB%%toc\fR
398指定目录信息所在位置。可以多次使用。注意同时指定\-\-toc选项。
399
400.SH 示例
401
402.TP
403txt2tags \-t html file.t2t
404
405转换成HTML，将转换的结果输出到文件file.html。
406
407.TP
408txt2tags \-t html \-o \- file.t2t
409
410转换成HTML，将转换的结果输出到STDOUT。
411
412.TP
413txt2tags \-t html \-\-toc file.t2t
414
415转换成HTML，包含自动生成的目录。
416
417.TP
418txt2tags \-t html \-\-toc \-\-toc\-level 2 \-n file.t2t
419
420转换成HTML，并生成目录，目录深度为2，各项标题采用数字编号。
421
422.TP
423txt2tags \-\-toc\-only file.t2t
424
425只输出目录，不进行实际的转换。
426
427.TP
428txt2tags \-t html \-\-css\-sugar \-\-style base.css \-\-style ui.css file.t2t
429
430转换成HTML，并预先设置采用CSS，同时指定引用两个外部CSS文件。
431
432.TP
433txt2tags \-t art \-\-slides \-\-width 80 \-\-height 25 \-o \- file.t2t | more
434
435生成艺术ASCII演示文档，用于在80x25的屏幕或窗口上演示。
436
437.TP
438(echo ; echo "**bold**") | txt2tags \-t html \-H \-
439
440易用的单行指令，从STDIN读取内容做快速的测试。
441
442.TP
443txt2tags \-t html \-o \- file.t2t | tidy > file.html
444
445将转换的结果输出到STDOUT，然后调用外部程序优化结果代码，最终保存到文件。
446
447.SH 文件
448
449.TP
450~/.txt2tagsrc
451用户默认配置文件。
452
453.SH 环境
454
455.TP
456T2TCONFIG
457该值设置用户默认配置文件的绝对路径。
458
459.SH 作者
460
461.P
462原文由Aurelio Jargas <verde@aurelio.net>编写。
463
464.P
465中文版由Abby Pan <abbypan@gmail.com>翻译。
466
467.SH 缺陷
468
469.P
470http://bugs.txt2tags.org
471
472.SH 版权
473
474.P
475Copyright (C) 2001\-2010 Aurelio Jargas, GNU GPL v2
476
477.\" man code generated by txt2tags 2.6 (http://txt2tags.org)
478.\" cmdline: txt2tags -t man doc/Chinese/manpage-zh.t2t