doclifter - 云端在线

程序：

您的姓名

doclifter - 将 troff 请求翻译成 DocBook

概要

文件搬运工 [-e 编码] [-H 提示文件] [-q] [-x] [-v] [-w] [-V] [-D 令牌=类型] [-一世 径]
[-一世 径] 文件...

商品描述

文件搬运工 将使用 troff 宏编写的文档转换为 DocBook。 的结构子集
中的请求 男子（7） doc文件（7） ms（7） me（7） mm（7）， 的troff(1) 支持。

翻译将原始文档的所有结构带入部分，
小节和段落级别。 命令和 C 函数概要被翻译成
DocBook 标记，而不仅仅是逐字显示。 表（TBL 标记）被翻译成
DocBook 表标记。 PIC 图被翻译成 SVG。 特罗夫级信息
XML 注释中保留了可能具有结构性含义。

在可能的情况下，字体更改宏被转换为结构标记。 文件搬运工
识别标记和内容的刻板模式（例如在
FILES 部分来标记文件名）并提升它们。 一种编辑、添加和保存语义的方法
支持高亮提示。

即使没有突出显示，一些陈词滥调也会被识别并提升为结构标记。
识别的模式包括 URL、电子邮件地址、手册页引用和
C 程序列表。

标签 。在 和 .ti 请求与投诉一起传递。 他们指出
表示级标记 文件搬运工 不能转化为结构； 输出将
需要手工固定。

标签 .ta 除非立即通过文本跟随投诉，否则将通过投诉
行包含一个制表符，在这种情况下，包含制表符的行的以下跨度被提升
到桌子上。

在某些情况下， 文件搬运工 甚至可以提升格式化的手册页和文本
产生的输出 猞猁(1) 来自 HTML。 如果在输入中没有找到宏，但确实找到了
NAME 部分标题，它尝试将纯文本解释为手册页（跳过
由生成的样板页眉和页脚 猞猁(1))。 以这种方式产生的翻译
将容易错过结构特征，但这种回退对于简单的人来说已经足够了
页面。

文件搬运工 没有做一件完美的工作，只是一个令人惊讶的好工作。 最后抛光应该
由能够识别对计算机来说过于微妙的模式的人类应用。 但
文件搬运工 几乎总是会产生足够好的翻译以供使用
手工黑客。

有关如何解决文档转换的讨论，请参阅故障排除部分
问题。

配置

如果不带参数调用 文件搬运工 充当过滤器，将 troff 源输入转换为
标准输出上 DocBook 标记的标准输入。 如果用参数调用，每个
参数文件被单独翻译（但提示被保留，见下文）； 后缀
.xml 被赋予翻译的输出。

-h
命名一个文件，分析过程中收集的语义提示信息应存放在该文件中
书面。

-D
这个 -D 允许您发布提示。 这可能很有用，例如，如果 文件搬运工 is
错误解析概要，因为它不将标记识别为命令。 这个提示是
读取输入源中的提示后合并。

-I
这个 -I 选项将其参数添加到 docfilter 搜索时使用的包含路径
夹杂物。 包含路径最初只是当前目录。

-e
这个 -e 允许您设置要在输出 XML 中发出的编码字段。 它
默认为 ISO-8859-1 (Latin-1)。

-q
通常，要求 文件搬运工 无法解释（通常是因为它们是
表示级）被传递到输出中的 XML 注释。 -q 选项
压制这一点。 它还禁止列出宏。 有关请求的消息
无法识别或无法翻译，无论状态如何，都转到标准错误
这个选项。 当您认为自己有一个
彻底删除文档并希望失去 troff 遗产。

-x
-x 选项要求 文件搬运工 生成 DocBook 版本 5 兼容的 xml
内容，而不是其默认的 DocBook 4.4 版输出。 包含物和实体
启用此开关可能无法正确处理。

-v
-v 选项使 文件搬运工 关于它在做什么的噪音更大。 这主要用于
调试。

-w
启用严格的可移植性检查。 -w 的多个实例会增加严格性。
请参阅“便携性检查”一节。

-V
使用此选项，程序会发出版本消息并退出。

翻译 规则

总体而言，您可以预期字体更改将通过 Remap 转换为 Emphasis 宏
取自 troff 字体名称的属性。 基本字体名称为 R、I、B、U、CW 和 SM。

Troff 和宏包特殊字符转义被映射到 ISO 字符实体。

在规划婴儿食品行业的工艺要求时，安全性和可靠性是工艺设计中最重要的方面。 文件搬运工 遇到一个 。所以 指令，它搜索文件。 如果可以阅读
访问文件并打开它，该文件完全由命令行和
评论，然后它被包括在内。 如果这些条件中的任何一个失败，则实体引用
它是生成的。

文件搬运工 当它识别出一个显示时执行特殊解析，例如由
.DS/.DE. 它反复尝试先解析函数概要，然后再解析纯文本
显示器上剩下的东西。 因此，大多数内联 C 函数原型将被提升为
结构化标记。

关于特定翻译的一些注意事项：

男人 翻译
文件搬运工 在大多数手册页上做得很好，它知道扩展 UR/UE/UN 和 网址
Linux 下支持的请求。 如果有的话 .UR 请求存在，它会翻译这些但是
不要用 Ulink 标签将 URL 包装在它们之外。 它也知道扩展 .L （文字）
来自贝尔实验室第 8 版及其朋友的字体标记。

这个 .TH 宏用于生成 RefMeta 部分。 如果存在，日期/来源/手册
参数（见 男子(7)) 包含在具有这些类属性的 RefMiscInfo 标记对中。
需要注意的是 文件搬运工 不会更改日期。

文件搬运工 在识别概要部分时执行特殊解析。 它反复
尝试首先解析函数概要，然后是命令概要，然后关闭纯文本
部分中剩下的内容。

以下 man 宏被转换为具有 remap 属性的强调标记： .B, .I,
.L, 。双, .BR, .BL, .IB, 红外线, .IL, .RB, .RI, .RL, 。磅, .LI, .LR, .SB, .SM. 一些刻板印象
涉及这些宏的模式被识别并转化为语义标记。

以下宏被转换为分段符： .LP, .PP, .P, 。生命值，并
单参数形式 .知识产权.

两个参数的形式 .知识产权 被翻译为 VariableList（通常）或
ItemizedList（如果标签是 troff 项目符号或方形字符）。

以下宏在语义上进行了翻译： .SH,.SS, .TP, .UR, 。欧盟, 。联合国, .IX。 一个 。联合国
之前打电话 .SH or .SS 设置新部分的 ID。

这个 \*R, \*（Tm值, \*(lq和 \*(rq 符号被翻译。

以下（纯表示级）宏将被忽略： .PD,.DT.

这个 .RS/。关于 宏的翻译取决于它们是否在前面
列表标记。 什么时候 .RS 发生在之前 .TP or .知识产权 结果是嵌套列表。 除此以外，
这些因素包括原料奶的可用性以及达到必要粉末质量水平所需的工艺。 .RS/。关于 pair 被翻译成一个 Blockquote 标签对。

.DS/。的 不是记录在案的 man 宏集的一部分，但因为它出现而被识别
在旧 Unix 的遗留手册页上有一些频率。

最初在 Ultrix 下定义的某些扩展宏在结构上进行了翻译，
包括偶尔出现在 Linux 和其他手册页上的那些
开源 Unix。 。前任/.ee （和同义词 。前任/.EE), .Ds/.德,

.NT/.NE, .PN和 。多发性硬化症 在结构上进行翻译。

X 分布使用的以下扩展宏也被识别和
从结构上翻译： .FD, .FN, 。在, .ZN, .hN和 。C{/。C} 这个 .TA 和 。在 请求是
忽略了。

当 man 宏处于活动状态时，任何 .pp 包含请求的宏定义 .PP 将
被忽略。 和所有实例 .pp 替换为 .PP。 同样的， .TP 将被替换
- .TP. 这是处理一些经常遇到的最痛苦的方式
否则会导致严重的解释问题的定型包装器定义

人工翻译的已知问题区域：

· 奇怪的用途 .TP. 这些有时会生成无效的 XML，有时会导致
生成的 XML 中的 FIXME 注释（警告消息也将转到标准错误）。

· man 宏是如何产生的还有待商榷 。生命值 和 .知识产权 没有标签应该被翻译。 我们
将它们视为普通的分段符。 我们可以在视觉上模拟悬挂
带有列表标记的段落，但这不是结构性翻译。

播客 翻译
文件搬运工 识别由产生的扩展宏 豆荚人 (.sh, .Sp, .ip, .vb, .Ve)
并在结构上翻译它们。

提升页面产生的结果 豆荚人 应该用眼球仔细检查，
尤其是命令和功能概要的呈现。 播客 产生而
反常的标记； 文件搬运工试图解开它有时是徒劳的。

如果可能，请从 POD 源生成您的 DocBook。 有一个 pod2docbook 模块
这样做的 CPAN。

特克曼 翻译
文件搬运工 识别 Tcl/Tk 文档系统使用的扩展宏： .AP,
。作为, .BS, 。是, 。CS, .CE, .DS, 。的, 。所以, .SE, .UL, .VS, 。去。 该 .AP, 。CS, .CE, 。所以, .SE,
.UL, .QW 和 .PQ 宏在结构上被翻译。

曼多克 翻译
文件搬运工 应该能够在大多数情况下做得很好 doc文件(7)页，因为这个宏
包表达了很多语义结构。

mandoc 翻译的已知问题：全部 .BD/.ed 显示块被翻译为
LiteralLayout 标签对。

Ms 翻译
文件搬运工 在大多数 ms 页面上做得很好。 需要注意的一个弱点是
Author 和 Affiliation 标签的生成。 用于挖掘此信息的启发式方法
出的 .AU 部分作品适用于以通常的方式格式化姓名的作者
英语（例如“ME Lesk”、“Eric S. Raymond”）但非常脆弱。

对于要被识别为包含 ms 标记的文档，它必须具有扩展名 .ms。
这避免了误报问题。

这个 .TL, .AU, 。有和 .AE 宏以预期的方式变成文章元信息。
这个 .PP, .LP, .SH和 .NH 宏变成段落和节结构。 被标记的
形式 .知识产权 被翻译为 VariableList（通常）或 ItemizedList（如果标签
是 troff 项目符号或方形字符）； 未标记的版本被视为普通版本
断段。

这个 .DS/。的 pair 被转换为 LiteralLayout 标签对。 这 文件系统/.FE 对是
转换为脚注标记对。 这 .QP/.QS/.量化宽松 请求定义 BlockQuotes。

这个 .UL 字体更改映射到 U。 .SM 和 .LG 变成数字加减大小步长
后缀为 Remap 属性。

这个 .B1 和 .B2 框宏被转换为侧边栏标签对。

所有与页脚、多列模式和保留相关的宏都将被忽略（.ND, .DA,
.1度, .2度, .MC, .BX, .KS, .KE, .KF）。 该 .R, .RS和 。关于 宏也被忽略。

Me 翻译
翻译 me 文件往往会产生需要大量资料的粗略结果
手工黑客。 该格式几乎没有可用的结构，用它编写的文档往往
使用大量低级 troff 宏； 这两个属性都容易混淆 文件搬运工.

对于要被识别为包含 me 标记的文档，它必须具有扩展名 .me。
这避免了误报问题。

以下宏被转换为分段符： .lp, .pp。 该 .ip 宏是
转换为 VariableList。 这 .bp 宏被翻译成一个 ItemizedList。 这 .np
宏被翻译成一个 OrderedList。

b、i 和 r 字体映射到具有 B、I 和 R 重映射属性的强调标记。 这
.rb （“真正的粗体”）字体被视为与 .b.

.q(/.q) 从结构上翻译。

大多数其他请求被忽略。

Mm 翻译
备忘录宏文件翻译得很好，因为这些宏带有很多结构
信息。 翻译规则针对备忘录或已发布的论文样式进行了调整；
与外部信件样式相关的信息将保留在注释中。

对于要被识别为包含 mm 标记的文档，它必须具有扩展名 .mm。
这避免了误报问题。

以下高亮宏被翻译为 int Emphasis 标签： .B, .I, .R, 。双, .BR,
.IB, 红外线, .RB, .RI.

以下宏在结构上进行了翻译： .AE, .AF, .AL, .RL, 。应用程序, .APPSK, 。作为,
。在, .AU, .B1, .B2, 。是, .BL, .ML, .BS, .BVL, .VL, 。的, .DL .DS, .FE, 文件系统, .H, .胡, .IA,
。IE, .IND, 。磅, .LC, .LE, .LI, .P, 射频, .SM, .TL, .VERBOFF, .韦尔邦, .WA, 。我们.

以下宏将被忽略：

.)E, .1度, .2度, .AST, .AV, .AVL, 。覆盖, .COVEND, .EF, .EH, .EDP, 。史诗, .FC, .FD, .HC,
.HM, .GETR, .GETST, .HM, .INITI, .initr, .INDP, .ISODATE, 。公吨, .NS, .ND, 。的, 。哦, .OP,
.PGFORM, .PGNH, .PE, .PF, .PH值, .RP, .S, .SA, .SP, .SG, .SK, .TAB, 结核病, .TC, .虚拟机, 。厕所.

以下宏会生成警告： .EC, 。前任, .FG, .GETHN, .GETPN, .GETR, .GETST, .LT,
.LD, .LO, 。移动, .MULB, .穆尔恩, .骡子, .NCOL, .nP, .PIC, .RD, .RS, 。关于, .SETR

.BS/。是 和 .IA/。IE 对通过。 里面的文字可能需要删除
或移动。

的标记论证 .ML 被忽略； 以下列表 id 格式化为正常
分项清单。

内容 .DS/。的 or .DF/。的 变成了屏幕显示。 参数
控制表示级格式将被忽略。

万维网 翻译
mwww 宏是对 man 宏支持的扩展 groff的(1) 用于生产网络
页面。

这个 网址, 则fTP, 邮件, 则fTP, 图像, 行李牌 标签在结构上被翻译。 这 索引,
体色, 背景, HTML和 LINE 标签被忽略。

TBL 翻译
TBL 表的所有结构特征都被翻译，包括水平和
's' 和 '^' 垂直跨越。 支持“l”、“r”和“c”格式； 然后'
列格式呈现为“r”。 正确处理带有 T{ 和 T} 的行延续。
也是 .TH.

这个 扩大, 框, 双箱, 全箱, 中心, 左和 右 支持选项。 GNU
同义词 框架 和 双帧 也被认可。 但是单身和
双重规则和盒子丢失了。

不支持表格延续 (.T&)。

如果紧接在表格之前的第一行非空文本是粗体的，则为
解释为表格的标题，表格是使用表格和标题生成的。
否则，该表将被转换为informaltable。

大多数其他表示级 TBL 命令被忽略。 'b' 格式限定符是
处理，但点大小和宽度限定符不是。

PIC 翻译
PIC 部分被转换为 SVG。 doclifter 呼吁 画图(1) 完成
这个; 您必须安装该实用程序才能使 PIC 翻译工作。

方程 翻译
EQN 部分被过滤到嵌入式 MathML 中 方程 -T数学ML 如果可能，否则
通过包含在 LiteralLayout 标签中。 在看到 delim 语句后，
内联 eqn 分隔符被转换为 XML 处理指令。 例外：内联
由单个字符组成的 eqn 方程被转换为具有角色的 Emphasis
eqn 的属性

特罗夫 翻译
troff 翻译仅用于支持宏集的解释。 它不是
有用的独立。

这个 .nf 和 .fi 宏被解释为文字布局边界。 调用 。所以
宏要么导致包含，要么被转换为 XML 实体包含（见上文）。
调用 .ul 和 .CU 宏会导致以下几行被包裹在 Emphasis 标签中
重映射属性为“U”。 调用 英尺 生成相应的开始或结束强调
标签。 调用 .tr 导致输出的字符转换。 调用 .bp 产生一个
BeginPage 标记（仅在分段文本中）。 调用 .sp 生成一个分段符（在
仅分段文本）。 调用 .ti 将以下行包装在 BlockQuote 中这些是
我们仅将 troff 请求翻译为 DocBook。 troff 仿真的其余部分存在
因为宏包在内部使用它来将宏扩展为可能存在的元素
结构。

与宏定义和字符串相关的请求（.ds, 。如, 。德, 。上午, 。R M, .rn, .em） 是
处理和扩展。 这 .ig 宏也被处理。

条件宏 (。如果, .IE, 。这) 处理。 内置条件 o、n、t、e 和 c
被评估为好像在文档的第一页上的 nroff。 m、d 和 r troff
条件也被解释。 字符串比较由直接文本评估
比较。 所有数值表达式的计算结果为真。

扩展的 groff 请求 cc, c2, ab, 比, do, NOP和 回报 和 转移 旨在
解释。 它的 .PSPIC 扩展名被翻译成一个 MediaObject。

这个 。Tm值 宏将其参数写入标准错误（使用 -t）。 该 。下午 宏观报告
定义的宏和字符串。 这些工具可能有助于调试您的翻译。

一些 troff 转义序列被取消：

1. \e 和 \\ 转义符变成了一个裸反斜杠 \。 一个句号，和 \- 一个空的破折号。

2. troff 转义 \^、\`、\' \&、\0 和 \| 被提升到等效的 ISO 特殊
间距字符。

3. \ 后跟空格被转换为 ISO 不间断空格实体。

4. 一个 \\~ 也被翻译成一个 ISO 不间断空间实体； 正确地这应该是一个
不能用于换行但像普通空格一样伸展的空间
行调整，但没有 ISO 或 Unicode 实体。

5. \u 和 \d 半线运动垂直运动逃逸，配对时，变成
标 or 标 标签。

6. \c 转义符作为一个行继续处理。 在重要的情况下
（例如用于令牌粘贴）。

7. 用于字体更改的 \f 转义符以各种依赖于上下文的方式进行翻译。 第一的，
文件搬运工 寻找涉及具有语义意义的字体更改的陈词滥调，以及
提升到结构标签。 如果它不能这样做，它会生成一个 Emphasis 标签。

8. \m[] 扩展名被翻译成一个短语span，带有remap属性携带
颜色。 注意：样式表通常不会呈现这个！

9. \o 请求的一些用法被翻译为：成对的，后面跟着一个字母
字符 ` ' : ^ o ~ 被翻译成带有锐音变音符号的组合形式，
如果相应的 Latin-1
或 Latin-2 字符作为 ISO 文字存在。

除了这些之外的其他转义将产生警告或错误。

所有其他 troff 请求都被忽略，但会传递到 XML 注释中。 一些（如
。这) 也会触发警告消息。

可移植性 检查

启用可移植性检查时， 文件搬运工 发出有关标记的可移植性警告
它可以处理但会破坏其他各种查看器和解释器。

1. 在第 1 级，它会警告会破坏的建筑 人2html(1), (C
用 Linux 分发的程序 男子(1)、不是旧的、功能更差的Perl
脚本）。 GNOME yelp 中使用了此代码的近似派生。 这应该是
您所追求的最低便携性水平，并符合推荐的
这些因素包括原料奶的可用性以及达到必要粉末质量水平所需的工艺。 格罗夫曼(7) 手册页。

2. 在第 2 级，它会警告会破坏可移植性的结构
Unix 经典工具（包括长宏名称和带有 \[] 的字形引用）。

语义 分析

文件搬运工 保留两个从分析源中获取的语义提示列表
文档（尤其是来自解析命令和函数概要的文档）。 当地名单
包括：

· 函数形式参数的名称

· 命令选项的名称

本地提示用于标记从中收集它们的单个页面。 这
全球名单包括：

· 函数名称

· 命令名称

· 函数返回类型的名称

If 文件搬运工 应用于多个文件，全局列表保留在内存中。 你可以
在运行结束时转储全局提示报告 -h 选项。 的格式
提示如下：

.\" | 标记作为

协调 是一个文本项并且 是应该是的 DocBook 标记文本
每当它出现突出显示或作为一个由空格包围的单词时，都用包裹
在源文本中。

来自早期文件的提示也适用于后来的文件。 这种行为可能是
在提升适用于函数或命令库的文档集合时很有用。
更有用的是一个提示文件转储的事实 -h 可以是其中之一
文件参数 文件搬运工; 代码检测到这种特殊情况并且不编写 XML
这样一个文件的输出。 因此，提升大型库的一个好的过程是生成
第一次运行的提示文件，检查它以删除误报，并将其用作
第一次输入到第二次运行。

也可以直接在 troff 源文件中包含一个提示文件。 这可能是
如果您想在转换为 XML 之前分阶段丰富文件，则非常有用。

故障排除

文件搬运工 试图警告它可以诊断但不能自行修复的问题。
当它说“寻找 FIXME”时，在生成的 XML 中执行此操作； 该令牌周围的标记
可能是错误的。

偶尔（少于 2% 的时间） 文件搬运工 甚至会产生无效的 DocBook 标记
来自正确的 troff 标记。 通常这是由源中的奇怪结构引起的
页，或超出能力范围的宏调用 文件搬运工的宏处理器得到
对。 以下是一些需要注意的事项，以及如何解决这些问题：

格式错误 命令 概要。
如果您收到“命令概要解析失败”的消息，请尝试重写概要
在您的手册页源中。 最常见的失败原因是不平衡的 [] 分组，一个
肉眼很难注意到的错误。 为了帮助解决这个问题，错误
消息在括号中包含一个标记号，指示解析失败的标记。

有关更多信息，请使用 -v 选项。 这将触发一个转储，告诉你什么
预处理后的命令概要看起来像，并指示解析的标记
失败（在概要的转储中插入了令牌号和插入符号
令牌）。 尝试在您的手册页源中重写概要。 最常见的原因
失败是不平衡的 [] 分组，这是一个很难被眼球注意到的错误。
为了帮助解决这个问题，错误令牌转储尝试在最后一个点插入“$”
嵌套深度增加，但执行此操作的代码容易失败。

扑朔迷离 宏 调用。
一些手册页作者替换了标准请求（例如 .PP, .SH 和 .TP) 与版本
做不同的事情 恩罗夫 和 的troff 环境。 尽管 文件搬运工 努力应对
并且通常做得很好，[nt]roff 的怪癖是大量且令人困惑的宏调用
有时会导致生成错误的 XML。 此类问题的一个常见症状是未关闭
强调标签。

格式错误 名单 语法。
手册页解析器可能会被混淆 .TP 具有标头标签但没有标头的构造
跟随身体。 如果生成的 XML 未通过验证，并且问题似乎是
错误放置的 listitem 标签，请尝试使用详细 (-v) 选项。 这将启用行编号
可以帮助您将问题归零的警告。

部分 嵌套 问题 - SS。
“possible section nesting error”消息表示程序已经看到两个相邻的
小节标题。 在手册页中，小节没有深度参数，所以 文件搬运工
无法确定小节应该如何嵌套。 之间的任何小节标题
指示的行和下一个顶级部分的开头可能是错误的，需要
手动修正。

坏 产量 - 没有 文件搬运工 错误 消息
如果您正在翻译使用用户定义宏的页面，并且 doclifter 无法
抱怨它但你得到了糟糕的输出，首先要做的是简化或消除
用户定义的宏。 在可能的情况下用库存请求替换它们。

改善 翻译 品質

有一些结构是翻开一页后用手检查的好主意。

查看 BlockQuote 标签附近。 troff 临时缩进请求 (.ti) 被翻译成
以下行周围的 BlockQuote 包装器。 有时 LiteralLayout 或 ProgramListing
会是一个更好的翻译，但是 文件搬运工 没有办法知道这一点。

不可能明确检测包装在 DocBook 选项标签中的候选者
在运行文本中。 如果您关心，您将不得不检查这些并手动修复它们。

使用 onworks.net 服务在线使用 doclifter