名称

       Locale::Po4a::TeX - 将 TeX 文档和衍生品从/转换为 PO 文件

描述

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

       Locale::Po4a::TeX 是一个帮助将 TeX 文档翻译成其他 [人类] 语言的模块。它还可以用作构建基于
       TeX 文档的模块的基础。

       用户可能应该使用 LaTeX 模块，它继承自 TeX 模块并包含常见 LaTeX 命令的定义。

使用 PO4A::TEX 进行翻译

       此模块可直接用于处理通用 TeX 文档。这将把您的文档拆分成更小的块 (段落、逐字块，甚至更小的
       块，如标题或索引)。

       有一些选项(将在下一节中介绍)可以自定义此行为。如果这不适合您的文档格式，我们鼓励您编写自己
       的派生模块，以描述您的格式的详细信息。有关流程描述，请参阅下面的 WRITING DERIVATIVE
       MODULES 小节。

       该模块还可以通过 TeX 文件中以 "% po4a:" 开头的行进行定制。此过程在 INLINE CUSTOMIZATION 一
       节中介绍。

此模块接受的选项

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

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

       no_wrap
           不应重新封装的环境的逗号分隔列表。

           请注意，逐字和 no_wrap 环境之间存在差异。在逐字逐句的块中没有命令和注释分析。

           如果此环境尚未注册，则 po4a 将考虑此环境不会接受任何参数。

       exclude_include
           不应由 \input 和 \include 包含的文件的冒号分隔列表。

       definitions
           包含 po4a 定义的文件的名称，如 INLINE CUSTOMIZATION 部分中定义。 如果无法将定义放在要
           翻译的文档中，可以使用此选项。

       verbatim
           应逐字处理的环境的逗号分隔列表。

           如果此环境尚未注册，则 po4a 将考虑此环境不会接受任何参数。

       使用这些选项可以替代已定义命令的默认行为。

在线定制

       TeX 模块可以使用以 % po4a: 开头的行进行自定义。这些行被解释为解析器的命令。可以识别以下命
       令：

       % po4a: command command1 alias command2
           指示 command1 命令的参数应作为 command2 命令的参数处理。

       % po4a: command command1 parameters
           这详细描述了 command1 命令的参数。此信息将用于检查参数的数量及其类型。

           您可以在 command1 之前加上

           一个星号 (*)
               po4a 将从段落中提取此命令 (如果它位于段落的开头或结尾)。然后，翻译者必须翻译标记为
               可翻译的参数。

           一个加号 (+)
               对于星号，如果它出现在块的末端，命令将被提取，但参数不会单独转换。翻译器将不得不翻
               译连接到其所有参数的命令。这保留了更多的上下文，并且对于参数中包含较小单词的命令非
               常有用，这些命令可以有多种含义(和翻译)。

               注意：在这种情况下，您不必指定哪些参数是可翻译的，但 po4a 必须知道参数的类型和数
               量。

           一个减号 (-)
               在这种情况下，不会从任何块中提取命令。但是如果它单独出现在块上，那么只有标记为可翻
               译的参数才会显示给翻译器。这对于字体命令很有用。这些命令通常不应该与它们的段落分
               开(以保持上下文)，但是如果整个字符串都包含在这样的命令中，就没有理由用它们来烦扰翻
               译人员。

           参数是一组 [] (表示可选的。 参数) 或 {} (指示强制参数)。 您可以在这些方括号之间加一个
           下划线 (_) 来表示。 必须翻译该参数。例如：
            % po4a: command *chapter [_]{_}

           这表明章节命令有两个参数：可选的。 (简称) 和强制性的，都必须翻译。 如果要指定 href 命
           令有两个必需参数， 您不想转换 URL (第一个参数)，并且您。 我不希望此命令与其段落 (允
           许。 翻译器移动句子中的链接)，您可以使用：
            % po4a: command -href {}{_}

           在这种情况下，仅当段落仅由此 href 命令组成时，才使用指示必须翻译哪些参数的信息。

       % po4a: environment env parameters
           这允许定义 env 环境接受的参数。 此信息稍后将用于检查。 \begin 命令，并允许指定必须翻译
           哪一个。 Parameters 参数的语法与。 其他命令。 \begin 命令的第一个参数是环境的名称。 不
           能在参数列表中指定此参数。以下是。 下面是一些示例：
            % po4a: 环境多层 {}
            % po4a: 环境方程

           至于命令，i<env> 前面可以有一个加号 (+)，表示 \begin 命令必须使用其所有参数进行转换。

       % po4a: separator env "regex"
           指示应根据给定正则表达式拆分环境。

           正则表达式由引号分隔。它不应该创建任何反向引用。如果需要组，应使用 (?:)。它可能还需要
           一些逃脱。

           例如，LaTeX 模块使用 "(?:&|\\\\)" 正则表达式分别翻译表的每个单元格(行用 '\\' 分隔，单
           元格用 '&' 分隔)。

           环境的概念扩展为 PO 文件中显示的类型。这可用于拆分 title 命令的第一个强制参数中的
           "\\\\"。在本例中，环境是 title{#1}。

       % po4a: verbatim environment env
           指示 env 是一个逐字环境。在此环境中将忽略注释和命令。

           如果此环境尚未注册，则 po4a 将考虑此环境不会接受任何参数。

编写衍生模块

       pre_trans
       post_trans
       add_comment
           添加字符串作为要在下一个翻译元素周围添加的注释。 这对于 texinfo 模块非常有用，因为注释
           在 TeX 中自动处理。

       translate
           封装在转换器的翻译上，带有前后处理过滤器。

           段落注释作为此段落第一个翻译字符串的 PO 注释插入。

       get_leading_command($buffer)
           此函数返回：

           命令名称
               如果在给定缓冲区的开头未找到命令，则此字符串将为空。只考虑可以分隔的命
               令。%separated_command 散列包含这些命令的列表。

           变种
               这表明是否使用了变量。例如，可以在 sections 命令的末尾添加星号(*)，以指定不应对其
               进行编号。在本例中，此字段将包含 "*"。如果没有变量，则该字段为空字符串。

           元组数组（参数类型、参数）
               参数类型可以是 '{' (对于强制参数) 或 '[' (对于可选参数)。

           剩余的缓冲区
               删除此前导命令及其参数后缓冲区的其余部分。如果未找到命令，则不会触及原始缓冲区，并
               在此字段中返回。

       get_trailing_command($buffer)
           与 get_leading_command 相同，但适用于缓冲区末尾的命令。

       translate_buffer
           通过将前导命令和尾随命令(应该分别转换的命令)从缓冲区中分离出来，递归地转换缓冲区。

           如果在 %translate_buffer_env 中为当前环境定义了函数，则此函数将用于转换缓冲区，而不是
           translate_buffer()。

       read
           重载翻译器的 read()。

       read_file
           递归读取文件，追加 @exclude_include 数组中未列出的包含文件。包含的文件是使用 KpathSea
           库中的 kpseWhich 命令进行搜索的。

           除了文件包含部分，它是从翻译提取器的读取中剪切并粘贴的。

       parse_definition_file
           用于使用 po4a 指令解析文件的子例程 (新命令的定义)。

       parse_definition_line
           解析格式为 "% po4a: " 的定义行。

           有关更多详细信息，请参阅 INLINE CUSTOMIZATION 部分。

       is_closed
       parse
       docheader

用于编写派生解析器的内部函数

       命令和环境函数接受以下参数(除了 $self 对象之外)：

       命令名称
       变种
       (类型、参数)元组的数组
       当前环境

       前 3 个参数由 get_leading_command 或 get_trailing_command 提取。

       命令和环境函数返回命令及其参数和新环境的转换。

       当找到 \begin 命令时，将调用环境函数。它们由 \begin 命令及其参数调用。

       TeX 模块只提出一个命令函数和一个环境函数：generic_command 和 generic_environment。

       generic_command 使用由指定的信息。 register_generic_command 或通过将定义添加到 TeX 文件：
        % po4a: command command1 parameters

       generic_environment 使用 register_generic_environment 或通过向 TeX 文件添加定义：
        % po4a: environment env parameters

       这两个函数将仅转换指定为可翻译的参数(带 '_')。generic_environment 将把环境的名称附加到环境
       堆栈中，而 generic_command 将在命令的名称后面加上参数的标识符(如 {#7} 或 [#2])。

此模块的状态

       此模块需要更多测试。

       它在一本书上进行了测试，并使用 Python 文档进行了测试。

待办事项清单使用PO4A：：XML进行转换

       自动检测新命令
           Tex 模块可以解析 newcommand 参数，并尝试猜测参数的数量、它们的类型以及是否应该转换它
           们。

       环境分隔符的翻译
           当 \item 用作环境分隔符时，item 参数附加到以下字符串。

       应将某些命令添加到环境堆栈
           These commands should be specified by couples.  This can be used to specify commands
           beginning or ending a verbatim environment.

       其它
           各种其他点在源代码中都标记为 TODO。

已知缺陷

       源代码中的各个点都被标记为 FIXME。

参见

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

作者

        Nicolas François <nicolas.francois@centraliens.net>

版权和许可

       版权所有 © 2004, 2005 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.

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