名称

       Locale::Po4a::TeX - convert TeX documents and derivatives from/to PO files

描述

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

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

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

使用 PO4A::TEX 进行翻译

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

       There are some options (described in the next section) that can customize this behavior.
       If this doesn't fit to your document format you're encouraged to write your own derivative
       module from this, to describe your format's details.  See the section WRITING DERIVATIVE
       MODULES below, for the process description.

       This module can also be customized by lines starting with "% po4a:" in the TeX file. This
       process is described in the INLINE CUSTOMIZATION section.

此模块接受的选项

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

       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 模块使用 "(?:&|\\\\)" 正则表达式分别翻译表的每个单元格(行用 '\\' 分隔，单
           元格用 '&' 分隔)。

           The notion of environment is expanded to the type displayed in the PO file. This can
           be used to split on "\\\\" in the first mandatory argument of the title command.  In
           this case, the environment is 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 参数附加到以下字符串。

       应将某些命令添加到环境堆栈
           这些命令应该由配对指定。这可以允许指定逐字环境开始或结束的命令。

       其它
           各种其他点在源代码中都标记为 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 条款重新分发和/或修改它(请参阅复制文件)。