LOCALE::PO4A::TEX.3PM

Section: User Contributed Perl Documentation (1)
Updated: 2025-07-02
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

Список окружений, разделенных запятыми, переносы строк в которых будут сохранены без изменений.

Заметьте, что есть различия между verbatim и no_wrap. В случае использования verbatim не обрабатываются команды и комментарии.

Если это окружение еще не зарегистрировано, po4a будет считать, что это окружение не принимает никаких параметров.

exclude_include

Список файлов, разделенных символом двоеточия, которые не будут включены командами \input и \include.

definitions

Имя файла с po4a-определениями (definitions), которые описаны в разделе ВСТРОЕННЫЕ НАСТРОЙКИ ПОВЕДЕНИЯ. Вы можете использовать этот параметр, если добавить эти определения непосредственно в переводимый документ не является возможным.

verbatim

Список окружений, разделенных запятыми, содержимое которых должно воспроизводиться буквально.

Используйте эти параметры, чтобы переопределить поведение по умолчанию для определенных команд.

ВСТРОЕННЫЕ НАСТРОЙКИ ПОВЕДЕНИЯ

Модуль TeX может быть настроен с помощью строк, начинающихся с % po4a:. Эти строки интепретируются как команды парсера. Распознаются следующие команды:

% po4a: command команда1 псевдоним команда2

Указывает, что аргументы команды1 должны рассматриваться как аргументы команды2.

% po4a: command команда1 параметры

Описывает параметры команды1. Эта информация будет использоваться для проверки количества параметров и их типов.

Перед именем команды1 может стоять один из следующих знаков

звездочка (*): po4a извлечет эту команду из абзаца (при условии, что она находится в начале или в конце абзаца). Для перевода будет доступен только текст параметров команды, если они помечены как переводимые.
плюс (+): Так же как при указании звездочки, команда будет извлечена, если она появится в конце блока, но текст параметров нельзя будет перевести отдельно. Для перевода будет доступна команда вместе с параметрами. Это сохраняет контекст и может быть полезно для команд, имеющих в параметрах короткие слова, которые могут иметь несколько значений (и переводов).
Примечание: В этом случае вам не нужно указывать, какие параметры являются переводимыми, но po4a должен знать тип и количество параметров.
минус (-): В этом случае команда не будет извлечена из блока. Но если команда появляется в отдельном блоке, то переводчику будут представлены только параметры, помеченные как доступные для перевода. Это полезно для команд шрифтов. Такие команды, в общем случае, не должны отделяться от абзаца (чтобы сохранить контекст), но нет смысла раздражать ими переводчика, если в такую команду заключена целая строка.

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 {}{_}

В этом случае информация, указывающая, какие аргументы должны быть переведены, используется, только когда абзац состоит из одной команды href.

% po4a: environment окружение параметры

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 equation

Перед именем окружения так же как перед именем команды может стоять знак плюс (+), означающий, что команда \begin должна быть переведена со всеми аргументами.

% po4a: separator окружение "регулярное_выражение"

Означает, что окружение должно быть разделено в соответствии с заданным регулярным выражением.

Регулярное выражение должно быть заключено в кавычки. Оно не должно создавать никаких обратных ссылок. Вы должны использовать (?:) для группировки. Это может потребовать экранирования некоторых символов.

К примеру, модуль LaTeX использует регулярное выражение "(?:&|\\\\)" для перевода отдельных ячеек таблицы (строки разделяются символами '\\', ячейки разделяются символом '&').

Понятие окружения расширяется до типа, отображаемого в PO-файле. Это позволяет рассматривать "\\\\" как разделитель в первом обязательном аргументе команды title. В этом случае окружением является title{#1}.

% po4a: verbatim environment окружение

Означает, что содержимое окружения воспроизводится буквально. Комментарии и команды будут игнорироваться.

НАПИСАНИЕ ПРОИЗВОДНЫХ МОДУЛЕЙ

pre_trans

post_trans

add_comment

Добавить строку в качестве комментария к следующему переведенному элементу. В основном это полезно для модуля texinfo, поскольку комментарии автоматически обрабатываются в TeX.

translate

Функция с фильтрами пред- и пост-обработки. Является оберткой для одноименной функции из модуля Transtractor.

Комментарии к абзацу вставляются PO-комментарии к первой переведенной строке этого абзаца.

get_leading_command($buffer)

Эта функция возвращает:

Имя команды: Если команда не найдена в начале буфера, эта строка будет пустой. Рассматриваются только те команды, которые могут быть разделены. Хэш %separated_command содержит список таких команд.
Вариант вызова команды: Указывает, что используется вариант команды. Например, команда создания раздела section существует в варианте section* (со звездочкой), это означает, что раздел не должен быть пронумерован. В этом случае данное поле будет содержать "*". Если вариант не используется, поле содержит пустую строку.
Массив кортежей (тип аргумента, аргумент): Тип аргумента может быть '{' (для обязательных аргументов) или '[' (для необязательных аргументов).
Остаток буфера: Часть буфера, оставшаяся после удаления имени команды и аргументов. Если имя команды не обнаружено, исходный буфер остается нетронутым и возвращается в это поле.

get_trailing_command($buffer)

То же самое, что и get_leading_command, но для команд, содержащихся в конце буфера.

translate_buffer

Рекурсивный перевод содержимого буфера с отделением команд, содержащихся в начале и в конце буфера (те, которые должны быть переведены отдельно).

Если функция определена в %translate_buffer_env для текущего окружения, она будет использована вместо translate_buffer().

read

Перегружает функцию read(), содержащуюся в модуле Transtractor.

read_file

Рекурсивно читает файл, добавляя содержимое файлов, указанных в командах \input и \include, за исключением файлов, перечисленных в @exclude_include. Поиск включаемых файлов производится с помощью команды kpsewhich из библиотеки Kpathsea.

Кроме части кода, отвечающей за включение файла. Эта часть кода взята из функции read() модуля Transtractor.

parse_definition_file

Подпрограмма для разбора файла с инструкциями po4a (определения новых команд).

parse_definition_line

Разбор строки в форме "% po4a: ".

Подробности см. в ВСТРОЕННЫЕ НАСТРОЙКИ ПОВЕДЕНИЯ.

is_closed

parse

docheader

ВНУТРЕННИЕ ФУНКЦИИ, используемые при создании производных парсеров

Функции command и environment принимают следующие аргументы (в дополнение к $self object):

Имя команды
Вариант вызова команды
Массив кортежей (тип аргумента, аргумент)
Текущее окружение

Первые три аргумента, извлекаемые функцией get_leading_command или get_trailing_command.

Функция command возвращает перевод команды с её аргументами. Функция environment возвращает новое окружение.

Функции environment вызываются при обнаружении команды \begin. Они вызываются с командой \begin и её аргументами.

Модуль TeX предлагает только одну функцию command и одну функцию environment: generic_command и 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

Обе функции будут переводить только те параметры, которые помечены как переводимые (с символом '_'). generic_environment добавит имя окружения в стек environment, а generic_command добавит имя команды, за которым следует идентификатор параметра (например {#7} или [#2]).

СОСТОЯНИЕ ЭТОГО МОДУЛЯ

Этот модуль нуждается в дополнительном тестировании.

Этот модуль тестировался на одной книге и документации Python.

Список TODO

Автоматическое обнаружение новых команд: Модуль TeX мог бы разбирать аргументы команды newcommand и пытаться угадать их количество, тип и то, следует ли их переводить.
Перевод разделителей окружения: Когда \item используется как разделитель окружения, аргумент item прикрепляется к следующей строке.
Некоторые команды должны быть добавлены в стек environment: Эти команды должны быть указаны парами. Это может использоваться для указания команд, начинающих или заканчивающих verbatim.
Другое: В исходном коде различные точки помечены как TODO.

ИЗВЕСТНЫЕ ОШИБКИ

В исходном коде различные точки помечены как FIXME.

СМОТРИТЕ ТАКЖЕ

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

АВТОРЫ

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

АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИИ

Данная программа является свободным программным обеспечением; вы можете распространять и/или изменять её на условиях Универсальной общественной лицензии (GPL) GNU v2.0 или новее (см. файл COPYING).

Index

НАЗВАНИЕ
ОПИСАНИЕ
ПЕРЕВОД С ПОМОЩЬЮ PO4A::TEX
ПАРАМЕТРЫ ПРИНИМАЕМЫЕ ЭТИМ МОДУЛЕМ
ВСТРОЕННЫЕ НАСТРОЙКИ ПОВЕДЕНИЯ
НАПИСАНИЕ ПРОИЗВОДНЫХ МОДУЛЕЙ
ВНУТРЕННИЕ ФУНКЦИИ, используемые при создании производных парсеров
СОСТОЯНИЕ ЭТОГО МОДУЛЯ
Список TODO
ИЗВЕСТНЫЕ ОШИБКИ
СМОТРИТЕ ТАКЖЕ
АВТОРЫ
АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИИ

This document was created by using the manual pages.
Time: 01:03:48 GMT, July 02, 2025