LOCALE::PO4A::TEX.3PM

Section: User Contributed Perl Documentation (1)
Updated: 2025-08-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. Он разделит ваш документ на более мелкие части (абзацы, дословные блоки или даже меньшие части такие, как заголовки или элементы предметных указателей).

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 DERIVATE MODULES below, for the process description.

Поведение этого модуля можно также изменить с помощью строк в 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 должен знать тип и количество параметров.
минус (-): В этом случае команда не будет извлечена из блока. Но если команда появляется в отдельном блоке, то переводчику будут представлены только параметры, помеченные как доступные для перевода. Это полезно для команд шрифтов. Такие команды, в общем случае, не должны отделяться от абзаца (чтобы сохранить контекст), но нет смысла раздражать ими переводчика, если в такую команду заключена целая строка.

Аргумент параметры может быть заключен в квадратные скобки [] (необязательные параметры) или в фигурные скобки {} (обязательные параметры). Вы можете поместить между скобками символ подчеркивания (_), чтобы указать, что параметры должны быть переведены. Например:
% po4a: command *chapter [_]{_}

Это означает, что команда chapter имеет два параметра: необязательный (короткий заголовок) и обязательный, оба эти параметра доступны для перевода. Если вы хотите для команды href указать два обязательных параметра, но не хотите, чтобы первый параметр (URL) был доступен для перевода, и не хотите отделять команду от абзаца (это позволит переводчику перемещать ссылку внутри предложения), вы можете использовать следующую конструкцию:
% po4a: command -href {}{_}

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

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

Это определяет, какие параметры принимает окружение, и какие из них должны быть переведены. Позднее данная информация используется для проверки количества аргументов команды \begin. Синтаксис |<параметров> такой же как у других команд. Первый параметр команды \begin -- это имя окружения. Он не должен указываться в списке параметров. Вот несколько примеров:
% 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 использует информацию указанную в register_generic_command или в определении из TeX-файла:
% po4a: command команда1 параметры

generic_environment использует информацию указанную в register_generic_environment или в определении из TeX-файла:
% po4a: environment окружение параметры

Обе функции будут переводить только те параметры, которые помечены как переводимые (с символом '_'). 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: 10:51:02 GMT, August 02, 2025