LOCALE::PO4A::TEX.3PM
Section: User Contributed Perl Documentation (1)Updated: 2024-06-17
Index Return to Main Contents
НАЗВАНИЕ
Locale::Po4a::TeX: преобразование документов TeX и производных форматов из/в PO-файлыОПИСАНИЕ
Целью проекта po4a (PO for anything, PO везде и для всего) является облегчение процесса перевода (и что более важно — поддержки перевода), используя инструменты gettext в тех случаях, когда их применение может выглядеть неожиданным, например для документации.Locale::Po4a::TeX — это модуль, предназначенным для помощи в переводе документов TeX на другие [человеческие] языки. Он также используется другими модулями для документов основанных на TeX.
Конечным пользователям, вероятно, следует использовать модуль LaTeX который наследуется от модуля TeX и содержит определения распространённых LaTeX-команд.
ПЕРЕВОД С ПОМОЩЬЮ PO4A::TEX
Этот модуль можно использовать непосредственно для обработки простых документов TeX. Он разделит ваш документ на более мелкие части (абзацы, дословные блоки или даже меньшие части такие, как заголовки или элементы предметных указателей).Есть несколько параметров (описанных в следующей секции), которые могут изменить поведение данного модуля. Если для вашего формата документации этих параметров недостаточно, то мы рекомендуем вам написать свой собственный модуль производный от данного, дабы лучше описать детали своего формата. Как это сделать, см. в секции СОЗДАНИЕ ПРОИЗВОДНЫХ МОДУЛЕЙ ниже.
Поведение этого модуля можно также изменить с помощью строк в TeX-файле, начинающихся с «% po4a:». Это описано в разделе ВСТРОЕННЫЕ НАСТРОЙКИ ПОВЕДЕНИЯ.
ПАРАМЕТРЫ ПРИНИМАЕМЫЕ ЭТИМ МОДУЛЕМ
Ниже приведены специфические для данного модуля параметры:- debug
- Включение отладки некоторых внутренних механизмов данного модуля. Какие части имеют отладочные закладки смотрите в исходном коде.
- no_wrap
-
Список сред, разделенных запятыми, переносы строк в которых будут сохранены без изменений.
Note that there is a difference between verbatim and no_wrap environments. There is no command and comments analysis in verbatim blocks.
If this environment was not already registered, po4a will consider that this environment does not take any parameters.
- exclude_include
- Colon-separated list of files that should not be included by \input and \include.
- definitions
- Имя файла с po4a-определениями (definitions), которые описаны в разделе ВСТРОЕННЫЕ НАСТРОЙКИ ПОВЕДЕНИЯ. Вы можете использовать этот параметр, если добавить эти определения непосредственно в переводимый документ не является возможным.
- verbatim
-
Comma-separated list of environments which should be taken as verbatim.
If this environment was not already registered, po4a will consider that this environment does not take any parameters.
Use these options to override the default behavior of the defined commands.
ВСТРОЕННЫЕ НАСТРОЙКИ ПОВЕДЕНИЯ
The TeX module can be customized with lines starting by % po4a:. These lines are interpreted as commands to the parser. The following commands are recognized:- % po4a: command команда1 псевдоним команда2
- Indicates that the arguments of the command1 command should be treated as the arguments of the command2 command.
- % po4a: command command1 parameters
-
This describes in detail the parameters of the command1 command. This information will be used to check the number of arguments and their types.
You can precede the command1 command by
-
- an asterisk (*)
- po4a will extract this command from paragraphs (if it is located at the beginning or the end of a paragraph). The translators will then have to translate the parameters that are marked as translatable.
- a plus (+)
-
As for an asterisk, the command will be extracted if it appear at an extremity of a block, but the parameters won't be translated separately. The translator will have to translate the command concatenated to all its parameters. This keeps more context, and is useful for commands with small words in parameter, which can have multiple meanings (and translations).
Note: In this case you don't have to specify which parameters are translatable, but po4a must know the type and number of parameters.
- a minus (-)
- In this case, the command won't be extracted from any block. But if it appears alone on a block, then only the parameters marked as translatable will be presented to the translator. This is useful for font commands. These commands should generally not be separated from their paragraph (to keep the context), but there is no reason to annoy the translator with them if a whole string is enclosed in such a command.
-
The parameters argument is a set of [] (to indicate an optional argument) or {} (to indicate a mandatory argument). You can place an underscore (_) between these brackets to indicate that the parameter must be translated. For example:
% po4a: command *chapter [_]{_}This indicates that the chapter command has two parameters: an optional (short title) and a mandatory one, which must both be translated. If you want to specify that the href command has two mandatory parameters, that you don't want to translate the URL (first parameter), and that you don't want this command to be separated from its paragraph (which allow the translator to move the link in the sentence), you can use:
% po4a: command -href {}{_}In this case, the information indicating which arguments must be translated is only used if a paragraph is only composed of this href command.
-
- % po4a: environment env parameters
-
This defines the parameters accepted by the env environment and specifies the ones to be translated.
This information is later used to check the number of arguments of the
\begin command.
The syntax of the parameters argument is the same as described for the
others commands.
The first parameter of the \begin command is the name of the environment.
This parameter must not be specified in the list of parameters. Here are
some examples:
% po4a: environment multicols {}
% po4a: environment equationAs for the commands, env can be preceded by a plus (+) to indicate that the \begin command must be translated with all its arguments.
- % po4a: separator env "regex"
-
Indicates that an environment should be split according to the given regular expression.
The regular expression is delimited by quotes. It should not create any back-reference. You should use (?:) if you need a group. It may also need some escapes.
For example, the LaTeX module uses the "(?:&|\\\\)" regular expression to translate separately each cell of a table (lines are separated by '\\' and cells by '&').
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
-
Indicate that env is a verbatim environment. Comments and commands will be ignored in this environment.
If this environment was not already registered, po4a will consider that this environment does not take any parameters.
WRITING DERIVATE MODULES
- pre_trans
- post_trans
- add_comment
- Add a string as a comment to be added around the next translated element. This is mostly useful to the texinfo module, as comments are automatically handled in TeX.
- translate
-
Wrapper around Transtractor's translate, with pre- and post-processing filters.
Comments of a paragraph are inserted as a PO comment for the first translated string of this paragraph.
- get_leading_command($buffer)
-
This function returns:
-
- A command name
- If no command is found at the beginning of the given buffer, this string will be empty. Only commands that can be separated are considered. The %separated_command hash contains the list of these commands.
- A variant
- This indicates if a variant is used. For example, an asterisk (*) can be added at the end of sections command to specify that they should not be numbered. In this case, this field will contain "*". If there is no variant, the field is an empty string.
- An array of tuples (type of argument, argument)
- The type of argument can be either '{' (for mandatory arguments) or '[' (for optional arguments).
- The remaining buffer
- The rest of the buffer after the removal of this leading command and its arguments. If no command is found, the original buffer is not touched and returned in this field.
-
- get_trailing_command($buffer)
- The same as get_leading_command, but for commands at the end of a buffer.
- translate_buffer
-
Recursively translate a buffer by separating leading and trailing commands (those which should be translated separately) from the buffer.
If a function is defined in %translate_buffer_env for the current environment, this function will be used to translate the buffer instead of translate_buffer().
- read
- Overloads Transtractor's read().
- read_file
-
Recursively read a file, appending included files which are not listed in the @exclude_include array. Included files are searched using the kpsewhich command from the Kpathsea library.
Except from the file inclusion part, it is a cut and paste from Transtractor's read.
- parse_definition_file
- Subroutine for parsing a file with po4a directives (definitions for new commands).
- parse_definition_line
-
Parse a definition line of the form "% po4a: ".
See the INLINE CUSTOMIZATION section for more details.
- is_closed
- parse
- docheader
ВНУТРЕННИЕ ФУНКЦИИ, используемые при создании производных парсеров
Command and environment functions take the following arguments (in addition to the $self object):- A command name
- A variant
- An array of (type, argument) tuples
- The current environment
The first 3 arguments are extracted by get_leading_command or get_trailing_command.
Command and environment functions return the translation of the command with its arguments and a new environment.
Environment functions are called when a \begin command is found. They are called with the \begin command and its arguments.
The TeX module only proposes one command function and one environment function: generic_command and generic_environment.
generic_command uses the information specified by
register_generic_command or by adding definition to the TeX file:
% po4a: command command1 parameters
generic_environment uses the information specified by
register_generic_environment or by adding definition to the TeX file:
% po4a: environment env parameters
Both functions will only translate the parameters that were specified as translatable (with a '_'). generic_environment will append the name of the environment to the environment stack and generic_command will append the name of the command followed by an identifier of the parameter (like {#7} or [#2]).
СОСТОЯНИЕ ЭТОГО МОДУЛЯ
This module needs more tests.It was tested on a book and with the Python documentation.
Список TODO
- Automatic detection of new commands
- The TeX module could parse the newcommand arguments and try to guess the number of arguments, their type and whether or not they should be translated.
- Translation of the environment separator
- When \item is used as an environment separator, the item argument is attached to the following string.
- Some commands should be added to the environment stack
- These commands should be specified by couples. This can be used to specify commands beginning or ending a verbatim environment.
- Others
- Various other points are tagged TODO in the source.
KNOWN BUGS
Various points are tagged FIXME in the source.СМОТРИТЕ ТАКЖЕ
Locale::Po4a::LaTeX(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)АВТОРЫ
Николя Франсуа (Nicolas François) <nicolas.francois@centraliens.net>
АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИИ
Copyright © 2004, 2005 Николя Франсуа (Nicolas FRANÇOIS) <nicolas.francois@centraliens.net>.Данная программа является свободным программным обеспечением; вы можете распространять и/или изменять её на условиях Универсальной общественной лицензии (GPL) GNU v2.0 или новее (см. файл COPYING).
Index
- НАЗВАНИЕ
- ОПИСАНИЕ
- ПЕРЕВОД С ПОМОЩЬЮ PO4A::TEX
- ПАРАМЕТРЫ ПРИНИМАЕМЫЕ ЭТИМ МОДУЛЕМ
- ВСТРОЕННЫЕ НАСТРОЙКИ ПОВЕДЕНИЯ
- WRITING DERIVATE MODULES
- ВНУТРЕННИЕ ФУНКЦИИ, используемые при создании производных парсеров
- СОСТОЯНИЕ ЭТОГО МОДУЛЯ
- Список TODO
- KNOWN BUGS
- СМОТРИТЕ ТАКЖЕ
- АВТОРЫ
- АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИИ
This document was created by using the manual pages.
Time: 20:30:51 GMT, June 17, 2024