.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "LOCALE::PO4A::MAN.3PM 1"
.TH LOCALE::PO4A::MAN.3PM 1 2024-06-26 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH 名称
.IX Header "名称"
Locale::Po4a::Man \- 将手动页面从/转换为 PO 文件
.SH 描述
.IX Header "描述"
Po4a (PO For Anything) 项目的目标是在文档等不需要翻译的领域使用 gettext 工具简化翻译(更有趣的是，简化翻译的维护)。
.PP
Locale::Po4a::Man 是一个模块，用于帮助将 nroff 格式(手册页的语言)的文档翻译成其他 [人类] 语言。
.SH "使用 PO4A::MAN 进行翻译"
.IX Header "使用 PO4A::MAN 进行翻译"
这个模块非常努力地让翻译员的工作变得更容易。因此，呈现给翻译人员的文本不是手册页中的文本的逐字副本。实际上，nroff 格式的粗略部分是隐藏的，这样翻译人员就不会把它们搞砸了。
.SS 文本换行
.IX Subsection "文本换行"
未缩进的段落会自动为翻译器重新换行。这可能会在生成的输出中导致一些细微的差异，因为 groff 使用的重新包装规则不是很清楚。例如，有时保留括号后的两个空格。
.PP
无论如何，不同之处只在于换行段落中额外空格的位置，我认为这是值得的。
.SS 字体规格
.IX Subsection "字体规格"
第一个更改是关于字体更改规范。在 nroff 中，有几种方法可以指定给定的单词应该用小写、粗体还是斜体书写。在要翻译的文本中，只有一种方法，借用 POD (Perl Online Documentation) 格式：
.IP "I<text> \-\- 斜体文本" 4
.IX Item "I<text> -- 斜体文本"
等效于 \efItext\efP 或 ".I text"
.IP "B<text> \-\- 粗体文本" 4
.IX Item "B<text> -- 粗体文本"
等效于 \efBtext\efP 或 ".B text"
.IP "R<text> \-\- 罗马文本" 4
.IX Item "R<text> -- 罗马文本"
等效于 \efRtext\efP
.IP "CW<text> \-\- 等长宽度文本" 4
.IX Item "CW<text> -- 等长宽度文本"
等效于 \ef(CWtext\efP 或 ".CW text"
.PP
备注：并非所有 groff 设备都提供 CW 面。不推荐使用。这是为了您的方便而提供的。
.SS 字符自动音译
.IX Subsection "字符自动音译"
Po4a 会自动音译某些字符，以简化翻译或审核翻译。以下是音译的列表：
.IP 连字符 4
.IX Item "连字符"
手册页中的连字符 (\-) 和减号 (\e\-) 在 PO 文件中都音译为简单的破折号 (\-)。然后，在将翻译插入到输出文档中时，所有破折号都音译为 roff 减号 (\e\-)。
.Sp
翻译人员可以在翻译中使用 roff 字形 '\e[hy]' 强制使用连字符。
.IP 不间断空格 4
.IX Item "不间断空格"
翻译人员可以在翻译中使用不间断空格。这些不间断空格 (latin1 中的 0xA0)将音译为 roff 不间断空格('\e ')。
.IP 引用音译 4
.IX Item "引用音译"
`` 和 '' 分别音译为 \e*(lq 和 \e*(rq.
.Sp
为了避免这些音译，翻译人员可以插入零宽度 roff 字符(即分别使用 '\e&' 或 '\e&')。
.SS "在翻译中放 '<' 和 '>'"
.IX Subsection "在翻译中放 '<' 和 '>'"
由于这些字符用于分隔字体修改后的部分，因此您不能逐字使用它们。改为使用 E<lt> 和 E<gt> (与 POD 中相同)。
.SH 此模块接受的选项
.IX Header "此模块接受的选项"
以下是此模块的特定选项：
.IP \fBdebug\fR 4
.IX Item "debug"
激活此模块某些内部机制的调试。 使用源查看哪些部件可以调试。
.IP \fBverbose\fR 4
.IX Item "verbose"
增加详细程度。
.IP \fBgroff_code\fR 4
.IX Item "groff_code"
此选项控制模块在遇到.de、.ie 或 .if 节时的行为。它可以采用下列值：
.RS 4
.IP \fIfail\fR 4
.IX Item "fail"
这是默认值。遇到 .de、.ie 或 .if 章节时，模块将失败。
.IP \fIverbatim\fR 4
.IX Item "verbatim"
指示必须按原样将 .de、.ie 或 .if 节从原始文档复制到翻译后的文档。
.IP \fItranslate\fR 4
.IX Item "translate"
指示将为翻译建议 .de、.ie 或 .if 章节。仅当这些部分之一中包含可翻译字符串时，才应使用此选项。否则，应该首选 \fIverbatim\fR。
.RE
.RS 4
.RE
.IP \fBgenerated\fR 4
.IX Item "generated"
该选项指定文件是生成的，并且 po4a 不应尝试检测手册页是否由另一种格式生成。要在生成的手册页上使用 po4a，此选项是必需的。请注意，转换生成的页面而不是源页面通常更脆弱，因此不是一个好主意。
.IP \fBmdoc\fR 4
.IX Item "mdoc"
此选项仅对 mdoc 页面有用。
.Sp
它通过告诉 po4a 不翻译 'NAME' 部分来选择更严格的 mdoc 格式支持。翻译了 'NAME' 部分的 mdoc 页面不会生成任何页眉或页脚。
.Sp
根据 groff_mdoc，名称，概要和描述
章节是必填项。
翻译的概要或描述部分没有已知问题，
但您也可以这样指定这些部分：
 \-o mdoc=NAME,SYNOPSIS,DESCRIPTION
.Sp
此 mdoc 问题也可以通过如下附录解决：
 PO4A\-HEADER:mode=before;position=^.Dd
 .TH DOCUMENT_TITLE 1 "月日，年" 操作系统 "章节名"
.PP
The following options specify the behavior of a user-defined macro (with a .de request), or of a classical macro that is not supported by po4a.  They take as argument a comma-separated list of macros.  For example:
.PP
.Vb 1
\& \-o noarg=FO,OB,AR \-o translate_joined=BA,ZQ,UX
.Ve
.PP
注意：如果某个宏不受 po4a 支持，并且您认为它是标准的 roff 宏，那么您应该将其提交给 po4a 开发团队。
.IP \fBuntranslated\fR 4
.IX Item "untranslated"
\&\fBuntranslated\fR 指示不必翻译此宏(在其参数处)。
.IP \fBnoarg\fR 4
.IX Item "noarg"
\&\fBnoarg\fR 类似于 \fBuntransted\fR，不同之处在于 po4a 将验证没有参数添加到此宏。
.IP \fBtranslate_joined\fR 4
.IX Item "translate_joined"
\&\fBtranslate_joined\fR 指示 po4a 必须提议翻译宏的参数。
.IP \fBtranslate_each\fR 4
.IX Item "translate_each"
对于 \fBtranslate_each\fR，除了每个参数将被单独翻译外，还将为翻译建议参数。
.IP \fBno_wrap\fR 4
.IX Item "no_wrap"
该选项将逗号分隔的对列表 \fIbegin\fR:\fIend\fR 作为参数，其中 \fIbegin\fR 和 \fIend\fR 是分隔不应该重新换行的节的开始和结束的命令。
.Sp
注意：不执行任何测试来确保 \fIend\fR 命令与其 \fIbegin\fR 命令匹配；任何结束命令都会停止 no_wrap 模式。如果您有一个没有 \fIend\fR (分别是 \fIbegin\fR )的 \fIbegin\fR  (分别是 \fIend\fR)宏，则可以指定现有的 \fIend\fR (如 fi)或 \fIbegin\fR (如 nf)作为对应宏。这些宏 (及其参数) 不会被翻译。
.IP \fBinline\fR 4
.IX Item "inline"
此选项指定不得拆分当前段落的逗号分隔宏列表。然后，要转换的字符串将包含 \fIfoo <.bar baz qux> quux\fR，其中 \fIbar\fR 是应该内联的命令，\fIbaz qux\fR 是其参数。
.IP \fBunknown_macros\fR 4
.IX Item "unknown_macros"
此选项指示找到未知宏时 po4a 的行为。默认情况下，po4a 失败并显示警告。它可以采用以下值： \fBfailed\fR (默认值)、\fBuntranslated\fR、\fBnoarg\fR、\fBtranslate_joined\fR 或 \fBtranslate_each\fR (有关这些值的解释，请参见上文)。
.SH "创作符合 PO4A::MAN 的手册页"
.IX Header "创作符合 PO4A::MAN 的手册页"
这个模块仍然非常有限，而且将永远如此，因为它不是一个真正的 nroff 解释器。做一个真正的 nroff 解释器是可能的，允许作者使用所有现有的宏，甚至在他们的页面中定义新的宏，但我们不想这样做。这太难了，我们认为没有必要。我们确实认为，如果手册页的作者想要看到他们的作品被翻译，他们可能必须适应，以减轻翻译人员的工作。
.PP
因此，po4a 中实现的 man 解析器有一些我们不太愿意纠正的已知限制，如果您希望看到翻译人员处理您的文档，这些限制将构成您必须避免的一些陷阱。
.SS "不要在 nroff 中编程"
.IX Subsection "不要在 nroff 中编程"
nroff 是一种完整的编程语言，具有宏定义、条件等功能。因为这个解析器不是一个功能齐全的 nroff 解释器，所以它在使用这些工具的页面上将失败 (我框中大约有200个这样的页面)。
.SS 使用普通宏集
.IX Subsection "使用普通宏集"
仍然有一些宏不受 po4a::man 支持。这只是因为我找不到任何关于它们的文档。这是我的计算机上使用的不受支持的宏的列表。请注意，此列表并不详尽，因为程序在第一个遇到的不受支持的宏上失败。如果您有关于这些宏的任何信息，我很乐意添加对它们的支持。由于这些宏，po4a::man 无法访问我框中的大约 250 个页面。
.PP
.Vb 11
\& ..               ."              .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
.Ve
.SS "从 po4a 隐藏文本"
.IX Subsection "从 po4a 隐藏文本"
有时，作者知道有些部分是不可翻译的，不应该用 po4a 提取。例如，选项可能接受 \fIother\fR 参数，并且 \fIother\fR 也可能显示为列表的最后一项。在第一种情况下，\fIother\fR 应该是不可翻译的。在第二种情况下，应该翻译 \fIother\fR。
.PP
在这种情况下，作者可以避免 po4a 提取一些字符串，使用一些特殊的 groff 结构：
.PP
.Vb 1
\& .if !\*(Aqpo4a\*(Aqhide\*(Aq .B other
.Ve
.PP
(这将需要 \fB\-o groff_code=verbatim\fR 选项)
.PP
还可以定义一个新的宏来自动执行：
 .de IR_untranslated
 .    IR \e\e$@
 ..
.PP
.Vb 1
\& .IR_untranslated \e\-q ", " \e\-\e\-quiet
.Ve
.PP
(这将需要选项 \fB\-o groff_code=verbatim\fR 和 \fB\-o untranslated=IR_untranslated\fR；使用此构造，不严格需要 \fB.if !'po4a'hide'\fR 条件，因为 po4a 不会解析宏定义的内部)
.PP
或使用别名：
 .als IR_untranslated IR
.PP
.Vb 1
\& .IR_untranslated \e\-q ", " \e\-\e\-quiet
.Ve
.PP
这将需要 \fB\-o untranslated=als,IR_untranslated\fR 选项。
.SS 结论
.IX Subsection "结论"
总结这一节，请保持简单，在编写手册页时不要试图变得聪明。很多事情在 nroff 中是可能的，并且不被这个解析器支持。例如，不要试图扰乱 \ec 来中断文本处理(就像我框中的 40 页一样)。或者，确保将宏参数与宏本身放在同一行。我知道它在 nroff 中是有效的，但是会使解析器过于复杂而无法处理。
.PP
当然，另一种可能是使用另一种更便于翻译的格式(比如使用 po4a::pod 的 POD，或者像 SGML 这样的 XML 家族之一)，但是多亏了 po4a::man，它不再需要了。也就是说，如果您的文档的源格式是 POD 或 XML，那么转换源格式而不是这个生成的格式可能更聪明。在大多数情况下，po4a::man 将检测生成的页面并发出警告。它甚至会拒绝处理 POD 生成的页面，因为这些页面由 po4a::pod 完美地处理，而且它们的 nroff 对应项定义了许多我不想编写支持的新宏。在我的机器上，4323 个页面中的 1432 个是从 POD 生成的，将被 po4a::man 忽略。
.PP
在大多数情况下， po4a::man 会发现问题并拒绝处理页面，发出一个适应的消息。在一些罕见的情况下，程序将没有警告完成，但输出将是错误的。这种情况称为 "bugs"；如果遇到这种情况，请务必报告此情况，并在可能时进行修复…
.SH 此模块的状态
.IX Header "此模块的状态"
此模块可用于大多数现有手册页。
.PP
一些测试定期在 Linux 机器上运行：
.IP \(bu 4
三分之一的页面被拒绝，因为它们是从 po4a 支持的另一种格式 (例如 POD 或 SGML) 生成的。
.IP \(bu 4
10% 的剩余页面因错误而被拒绝(例如，不支持 groff 宏)。
.IP \(bu 4
然后，只有不到 1% 的页面被 po4a 静默接受，但存在重大问题 (即丢失单词或插入新词)
.IP \(bu 4
处理其他页面时通常没有比间距差异或换行更重要的差异 (只有不到 10% 的已处理页面出现字体问题)。
.SH 参见
.IX Header "参见"
\&\fBLocale::Po4a::Pod\fR\|(3pm), \fBLocale::Po4a::TransTractor\fR\|(3pm), \fBpo4a\fR\|(7)
.SH 作者
.IX Header "作者"
.Vb 3
\& Denis Barbier <barbier@linuxfr.org>
\& Nicolas François <nicolas.francois@centraliens.net>
\& Martin Quinson (mquinson#debian.org)
.Ve
.SH 翻译
.IX Header "翻译"
taotieren <admin@taotieren.com>
.SH 版权和许可
.IX Header "版权和许可"
版权所有 © 2002\-2008 SPI, Inc.
.PP
This program is free software; you may redistribute it and/or modify it under the terms of GPL v2.0 or later (see the COPYING file).