LOCALE::PO4A::TEX.3PM(1) | User Contributed Perl Documentation | LOCALE::PO4A::TEX.3PM(1) |
名称
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>
翻译
taotieren <admin@taotieren.com>
版权和许可
版权所有 © 2004, 2005 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.
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).
2024-06-26 | perl v5.38.2 |