名称

       Locale::Po4a::Man - 将手动页面从/转换为 PO 文件

描述

       Po4a (PO For Anything) 项目的目标是在文档等不需要翻译的领域使用 gettext 工具简化翻译(更有
       趣的是，简化翻译的维护)。

       Locale::Po4a::Man 是一个模块，用于帮助将 nroff 格式(手册页的语言)的文档翻译成其他 [人类]
       语言。

使用 PO4A::MAN 进行翻译

       这个模块非常努力地让翻译员的工作变得更容易。因此，呈现给翻译人员的文本不是手册页中的文本的
       逐字副本。实际上，nroff 格式的粗略部分是隐藏的，这样翻译人员就不会把它们搞砸了。

   文本换行
       未缩进的段落会自动为翻译器重新换行。这可能会在生成的输出中导致一些细微的差异，因为 groff
       使用的重新包装规则不是很清楚。例如，有时保留括号后的两个空格。

       无论如何，不同之处只在于换行段落中额外空格的位置，我认为这是值得的。

   字体规格
       第一个更改是关于字体更改规范。在 nroff 中，有几种方法可以指定给定的单词应该用小写、粗体还
       是斜体书写。在要翻译的文本中，只有一种方法，借用 POD (Perl Online Documentation) 格式：

       I<text> -- 斜体文本
           等效于 \fItext\fP 或 ".I text"

       B<text> -- 粗体文本
           等效于 \fBtext\fP 或 ".B text"

       R<text> -- 罗马文本
           等效于 \fRtext\fP

       CW<text> -- 等长宽度文本
           等效于 \f(CWtext\fP 或 ".CW text"

       备注：并非所有 groff 设备都提供 CW 面。不推荐使用。这是为了您的方便而提供的。

   字符自动音译
       Po4a 会自动音译某些字符，以简化翻译或审核翻译。以下是音译的列表：

       连字符
           手册页中的连字符 (-) 和减号 (\-) 在 PO 文件中都音译为简单的破折号 (-)。然后，在将翻译
           插入到输出文档中时，所有破折号都音译为 roff 减号 (\-)。

           翻译人员可以在翻译中使用 roff 字形 '\[hy]' 强制使用连字符。

       不间断空格
           翻译人员可以在翻译中使用不间断空格。这些不间断空格 (latin1 中的 0xA0)将音译为 roff 不
           间断空格('\ ')。

       引用音译
           `` 和 '' 分别音译为 \*(lq 和 \*(rq.

           为了避免这些音译，翻译人员可以插入零宽度 roff 字符(即分别使用 '\&' 或 '\&')。

   在翻译中放 '<' 和 '>'
       由于这些字符用于分隔字体修改后的部分，因此您不能逐字使用它们。改为使用 E<lt> 和 E<gt> (与
       POD 中相同)。

此模块接受的选项

       以下是此模块的特定选项：

       debug
           激活此模块某些内部机制的调试。 使用源查看哪些部件可以调试。

       verbose
           增加详细程度。

       groff_code
           此选项控制模块在遇到.de、.ie 或 .if 节时的行为。它可以采用下列值：

           fail
               这是默认值。遇到 .de、.ie 或 .if 章节时，模块将失败。

           verbatim
               指示必须按原样将 .de、.ie 或 .if 节从原始文档复制到翻译后的文档。

           translate
               指示将为翻译建议 .de、.ie 或 .if 章节。仅当这些部分之一中包含可翻译字符串时，才应
               使用此选项。否则，应该首选 verbatim。

       generated
           该选项指定文件是生成的，并且 po4a 不应尝试检测手册页是否由另一种格式生成。要在生成的手
           册页上使用 po4a，此选项是必需的。请注意，转换生成的页面而不是源页面通常更脆弱，因此不
           是一个好主意。

       mdoc
           此选项仅对 mdoc 页面有用。

           它通过告诉 po4a 不翻译 'NAME' 部分来选择更严格的 mdoc 格式支持。翻译了 'NAME' 部分的
           mdoc 页面不会生成任何页眉或页脚。

           根据 groff_mdoc，名称，概要和描述 章节是必填项。 翻译的概要或描述部分没有已知问题， 但
           您也可以这样指定这些部分：
            -o mdoc=NAME,SYNOPSIS,DESCRIPTION

           此 mdoc 问题也可以通过如下附录解决：
            PO4A-HEADER:mode=before;position=^.Dd
            .TH DOCUMENT_TITLE 1 "月日，年" 操作系统 "章节名"

       以下选项允许指定新宏（使用 .de 请求定义）或 po4a 不支持的宏的行为。 它们将逗号分隔的宏列表
       作为参数。 例如：

        -o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX

       注意：如果某个宏不受 po4a 支持，并且您认为它是标准的 roff 宏，那么您应该将其提交给 po4a 开
       发团队。

       untranslated
           untranslated 指示不必翻译此宏(在其参数处)。

       noarg
           noarg 类似于 untransted，不同之处在于 po4a 将验证没有参数添加到此宏。

       translate_joined
           translate_joined 指示 po4a 必须提议翻译宏的参数。

       translate_each
           对于 translate_each，除了每个参数将被单独翻译外，还将为翻译建议参数。

       no_wrap
           该选项将逗号分隔的对列表 begin:end 作为参数，其中 begin 和 end 是分隔不应该重新换行的
           节的开始和结束的命令。

           注意：不执行任何测试来确保 end 命令与其 begin 命令匹配；任何结束命令都会停止 no_wrap
           模式。如果您有一个没有 end (分别是 begin )的 begin  (分别是 end)宏，则可以指定现有的
           end (如 fi)或 begin (如 nf)作为对应宏。这些宏 (及其参数) 不会被翻译。

       inline
           此选项指定不得拆分当前段落的逗号分隔宏列表。然后，要转换的字符串将包含 foo <.bar baz
           qux> quux，其中 bar 是应该内联的命令，baz qux 是其参数。

       unknown_macros
           此选项指示找到未知宏时 po4a 的行为。默认情况下，po4a 失败并显示警告。它可以采用以下
           值： failed (默认值)、untranslated、noarg、translate_joined 或 translate_each (有关这
           些值的解释，请参见上文)。

创作符合 PO4A::MAN 的手册页

       这个模块仍然非常有限，而且将永远如此，因为它不是一个真正的 nroff 解释器。做一个真正的
       nroff 解释器是可能的，允许作者使用所有现有的宏，甚至在他们的页面中定义新的宏，但我们不想这
       样做。这太难了，我们认为没有必要。我们确实认为，如果手册页的作者想要看到他们的作品被翻
       译，他们可能必须适应，以减轻翻译人员的工作。

       因此，po4a 中实现的 man 解析器有一些我们不太愿意纠正的已知限制，如果您希望看到翻译人员处理
       您的文档，这些限制将构成您必须避免的一些陷阱。

   不要在 nroff 中编程
       nroff 是一种完整的编程语言，具有宏定义、条件等功能。因为这个解析器不是一个功能齐全的 nroff
       解释器，所以它在使用这些工具的页面上将失败 (我框中大约有200个这样的页面)。

   使用普通宏集
       仍然有一些宏不受 po4a::man 支持。这只是因为我找不到任何关于它们的文档。这是我的计算机上使
       用的不受支持的宏的列表。请注意，此列表并不详尽，因为程序在第一个遇到的不受支持的宏上失
       败。如果您有关于这些宏的任何信息，我很乐意添加对它们的支持。由于这些宏，po4a::man 无法访问
       我框中的大约 250 个页面。

        ..               ."              .AT             .b              .bank
        .BE              ..br            .Bu             .BUGS           .BY
        .ce              .dbmmanage      .do                             .En
        .EP              .EX             .Fi             .hw             .i
        .Id              .l              .LO             .mf
        .N               .na             .NF             .nh             .nl
        .Nm              .ns             .NXR            .OPTIONS        .PB
        .pp              .PR             .PRE            .PU             .REq
        .RH              .rn             .S<             .sh             .SI
        .splitfont       .Sx             .T              .TF             .The
        .TT              .UC             .ul             .Vb             .zZ

   从 po4a 隐藏文本
       有时，作者知道有些部分是不可翻译的，不应该用 po4a 提取。例如，选项可能接受 other 参数，并
       且 other 也可能显示为列表的最后一项。在第一种情况下，other 应该是不可翻译的。在第二种情况
       下，应该翻译 other。

       在这种情况下，作者可以避免 po4a 提取一些字符串，使用一些特殊的 groff 结构：

        .if !'po4a'hide' .B other

       (这将需要 -o groff_code=verbatim 选项)

       还可以定义一个新的宏来自动执行：
        .de IR_untranslated
        .    IR \\$@
        ..

        .IR_untranslated \-q ", " \-\-quiet

       (这将需要选项 -o groff_code=verbatim 和 -o untranslated=IR_untranslated；使用此构造，不严
       格需要 .if !'po4a'hide' 条件，因为 po4a 不会解析宏定义的内部)

       或使用别名：
        .als IR_untranslated IR

        .IR_untranslated \-q ", " \-\-quiet

       这将需要 -o untranslated=als,IR_untranslated 选项。

   结论
       总结这一节，请保持简单，在编写手册页时不要试图变得聪明。很多事情在 nroff 中是可能的，并且
       不被这个解析器支持。例如，不要试图扰乱 \c 来中断文本处理(就像我框中的 40 页一样)。或者，确
       保将宏参数与宏本身放在同一行。我知道它在 nroff 中是有效的，但是会使解析器过于复杂而无法处
       理。

       当然，另一种可能是使用另一种更便于翻译的格式(比如使用 po4a::pod 的 POD，或者像 SGML 这样的
       XML 家族之一)，但是多亏了 po4a::man，它不再需要了。也就是说，如果您的文档的源格式是 POD 或
       XML，那么转换源格式而不是这个生成的格式可能更聪明。在大多数情况下，po4a::man 将检测生成的
       页面并发出警告。它甚至会拒绝处理 POD 生成的页面，因为这些页面由 po4a::pod 完美地处理，而且
       它们的 nroff 对应项定义了许多我不想编写支持的新宏。在我的机器上，4323 个页面中的 1432 个是
       从 POD 生成的，将被 po4a::man 忽略。

       在大多数情况下， po4a::man 会发现问题并拒绝处理页面，发出一个适应的消息。在一些罕见的情况
       下，程序将没有警告完成，但输出将是错误的。这种情况称为 "bugs"；如果遇到这种情况，请务必报
       告此情况，并在可能时进行修复…

此模块的状态

       此模块可用于大多数现有手册页。

       一些测试定期在 Linux 机器上运行：

       •   三分之一的页面被拒绝，因为它们是从 po4a 支持的另一种格式 (例如 POD 或 SGML) 生成的。

       •   10% 的剩余页面因错误而被拒绝(例如，不支持 groff 宏)。

       •   然后，只有不到 1% 的页面被 po4a 静默接受，但存在重大问题 (即丢失单词或插入新词)

       •   处理其他页面时通常没有比间距差异或换行更重要的差异 (只有不到 10% 的已处理页面出现字体
           问题)。

参见

       Locale::Po4a::Pod(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)

作者

        Denis Barbier <barbier@linuxfr.org>
        Nicolas Francois <nicolas.francois@centraliens.net>
        Martin Quinson (mquinson#debian.org)

版权和许可

       版权所有 © 2002-2008 SPI, Inc.

       此程序是自由软件；您可以根据 GPL 条款重新分发和/或修改它(请参阅复制文件)。