.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "LOCALE::PO4A::TEX.3PM 1" .TH LOCALE::PO4A::TEX.3PM 1 2025-11-22 "perl v5.42.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH НАЗВАНИЕ .IX Header "НАЗВАНИЕ" Locale::Po4a::TeX: преобразование документов TeX и производных форматов из/в PO\-файлы .SH ОПИСАНИЕ .IX Header "ОПИСАНИЕ" Целью проекта po4a (PO for anything, PO везде и для всего) является облегчение процесса перевода (и что более важно — поддержки перевода), используя инструменты gettext в тех случаях, когда их применение может выглядеть неожиданным, например для документации. .PP Locale::Po4a::TeX — это модуль, предназначенным для помощи в переводе документов TeX на другие [человеческие] языки. Он также используется другими модулями для документов основанных на TeX. .PP Конечным пользователям, вероятно, следует использовать модуль LaTeX который наследуется от модуля TeX и содержит определения распространённых LaTeX\-команд. .SH "ПЕРЕВОД С ПОМОЩЬЮ PO4A::TEX" .IX Header "ПЕРЕВОД С ПОМОЩЬЮ PO4A::TEX" Этот модуль можно использовать непосредственно для обработки простых документов TeX. Он разделит ваш документ на более мелкие части (абзацы, дословные блоки или даже меньшие части такие, как заголовки или элементы предметных указателей). .PP There are some options (described in the next section) that can customize this behavior. If this doesn\*(Aqt fit to your document format you\*(Aqre encouraged to write your own derivative module from this, to describe your format\*(Aqs details. See the section \fBWRITING DERIVATE MODULES\fR below, for the process description. .PP Поведение этого модуля можно также изменить с помощью строк в TeX\-файле, начинающихся с «% po4a:». Это описано в разделе \fBВСТРОЕННЫЕ НАСТРОЙКИ ПОВЕДЕНИЯ\fR. .SH "ПАРАМЕТРЫ ПРИНИМАЕМЫЕ ЭТИМ МОДУЛЕМ" .IX Header "ПАРАМЕТРЫ ПРИНИМАЕМЫЕ ЭТИМ МОДУЛЕМ" Ниже приведены специфические для данного модуля параметры: .IP \fBdebug\fR 4 .IX Item "debug" Включение отладки некоторых внутренних механизмов данного модуля. Какие части имеют отладочные закладки смотрите в исходном коде. .IP \fBno_wrap\fR 4 .IX Item "no_wrap" Список окружений, разделенных запятыми, переносы строк в которых будут сохранены без изменений. .Sp Заметьте, что есть различия между \fIverbatim\fR и \fIno_wrap\fR. В случае использования \fIverbatim\fR не обрабатываются команды и комментарии. .Sp Если это окружение еще не зарегистрировано, po4a будет считать, что это окружение не принимает никаких параметров. .IP \fBexclude_include\fR 4 .IX Item "exclude_include" Список файлов, разделенных символом двоеточия, которые не будут включены командами \einput и \einclude. .IP \fBdefinitions\fR 4 .IX Item "definitions" Имя файла с po4a\-определениями (definitions), которые описаны в разделе \&\fBВСТРОЕННЫЕ НАСТРОЙКИ ПОВЕДЕНИЯ\fR. Вы можете использовать этот параметр, если добавить эти определения непосредственно в переводимый документ не является возможным. .IP \fBverbatim\fR 4 .IX Item "verbatim" Список окружений, разделенных запятыми, содержимое которых должно воспроизводиться буквально. .Sp Если это окружение еще не зарегистрировано, po4a будет считать, что это окружение не принимает никаких параметров. .PP Используйте эти параметры, чтобы переопределить поведение по умолчанию для определенных команд. .SH "ВСТРОЕННЫЕ НАСТРОЙКИ ПОВЕДЕНИЯ" .IX Header "ВСТРОЕННЫЕ НАСТРОЙКИ ПОВЕДЕНИЯ" Модуль TeX может быть настроен с помощью строк, начинающихся с \fB% po4a:\fR. Эти строки интепретируются как команды парсера. Распознаются следующие команды: .IP "\fB% po4a: command\fR \fIкоманда1\fR \fBпсевдоним\fR \fIкоманда2\fR" 4 .IX Item "% po4a: command команда1 псевдоним команда2" Указывает, что аргументы \fIкоманды1\fR должны рассматриваться как аргументы \&\fIкоманды2\fR. .IP "\fB% po4a: command\fR \fIкоманда1\fR \fIпараметры\fR" 4 .IX Item "% po4a: command команда1 параметры" Описывает параметры \fIкоманды1\fR. Эта информация будет использоваться для проверки количества параметров и их типов. .Sp Перед именем \fIкоманды1\fR может стоять один из следующих знаков .RS 4 .IP "звездочка (\fB*\fR)" 4 .IX Item "звездочка (*)" po4a извлечет эту команду из абзаца (при условии, что она находится в начале или в конце абзаца). Для перевода будет доступен только текст параметров команды, если они помечены как переводимые. .IP "плюс (\fB+\fR)" 4 .IX Item "плюс (+)" Так же как при указании звездочки, команда будет извлечена, если она появится в конце блока, но текст параметров нельзя будет перевести отдельно. Для перевода будет доступна команда вместе с параметрами. Это сохраняет контекст и может быть полезно для команд, имеющих в параметрах короткие слова, которые могут иметь несколько значений (и переводов). .Sp Примечание: В этом случае вам не нужно указывать, какие параметры являются переводимыми, но po4a должен знать тип и количество параметров. .IP "минус (\fB\-\fR)" 4 .IX Item "минус (-)" В этом случае команда не будет извлечена из блока. Но если команда появляется в отдельном блоке, то переводчику будут представлены только параметры, помеченные как доступные для перевода. Это полезно для команд шрифтов. Такие команды, в общем случае, не должны отделяться от абзаца (чтобы сохранить контекст), но нет смысла раздражать ими переводчика, если в такую команду заключена целая строка. .RE .RS 4 .Sp Аргумент \fIпараметры\fR может быть заключен в квадратные скобки [] (необязательные параметры) или в фигурные скобки {} (обязательные параметры). Вы можете поместить между скобками символ подчеркивания (_), чтобы указать, что параметры должны быть переведены. Например: % po4a: command *chapter [_]{_} .Sp Это означает, что команда chapter имеет два параметра: необязательный (короткий заголовок) и обязательный, оба эти параметра доступны для перевода. Если вы хотите для команды href указать два обязательных параметра, но не хотите, чтобы первый параметр (URL) был доступен для перевода, и не хотите отделять команду от абзаца (это позволит переводчику перемещать ссылку внутри предложения), вы можете использовать следующую конструкцию: % po4a: command \-href {}{_} .Sp В этом случае информация, указывающая, какие аргументы должны быть переведены, используется, только когда абзац состоит из одной команды href. .RE .IP "\fB% po4a: environment\fR \fIокружение\fR \fIпараметры\fR" 4 .IX Item "% po4a: environment окружение параметры" Это определяет, какие параметры принимает \fIокружение\fR, и какие из них должны быть переведены. Позднее данная информация используется для проверки количества аргументов команды \ebegin. Синтаксис |<параметров> такой же как у других команд. Первый параметр команды \ebegin \-\- это имя окружения. Он не должен указываться в списке параметров. Вот несколько примеров: % po4a: environment multicols {} % po4a: environment equation .Sp Перед именем \fIокружения\fR так же как перед именем команды может стоять знак плюс (+), означающий, что команда \ebegin должна быть переведена со всеми аргументами. .IP "\fB% po4a: separator\fR \fIокружение\fR \fB""\fR\fIрегулярное_выражение\fR\fB""\fR" 4 .IX Item "% po4a: separator окружение ""регулярное_выражение""" Означает, что окружение должно быть разделено в соответствии с заданным регулярным выражением. .Sp Регулярное выражение должно быть заключено в кавычки. Оно не должно создавать никаких обратных ссылок. Вы должны использовать (?:) для группировки. Это может потребовать экранирования некоторых символов. .Sp К примеру, модуль LaTeX использует регулярное выражение "(?:&|\e\e\e\e)" для перевода отдельных ячеек таблицы (строки разделяются символами \*(Aq\e\e\*(Aq, ячейки разделяются символом \*(Aq&\*(Aq). .Sp Понятие окружения расширяется до типа, отображаемого в PO\-файле. Это позволяет рассматривать "\e\e\e\e" как разделитель в первом обязательном аргументе команды title. В этом случае окружением является title{#1}. .IP "\fB% po4a: verbatim environment\fR \fIокружение\fR" 4 .IX Item "% po4a: verbatim environment окружение" Означает, что содержимое \fIокружения\fR воспроизводится буквально. Комментарии и команды будут игнорироваться. .Sp Если это окружение еще не зарегистрировано, po4a будет считать, что это окружение не принимает никаких параметров. .SH "НАПИСАНИЕ ПРОИЗВОДНЫХ МОДУЛЕЙ" .IX Header "НАПИСАНИЕ ПРОИЗВОДНЫХ МОДУЛЕЙ" .IP \fBpre_trans\fR 4 .IX Item "pre_trans" .PD 0 .IP \fBpost_trans\fR 4 .IX Item "post_trans" .IP \fBadd_comment\fR 4 .IX Item "add_comment" .PD Добавить строку в качестве комментария к следующему переведенному элементу. В основном это полезно для модуля texinfo, поскольку комментарии автоматически обрабатываются в TeX. .IP \fBtranslate\fR 4 .IX Item "translate" Функция с фильтрами пред\- и пост\-обработки. Является оберткой для одноименной функции из модуля Transtractor. .Sp Комментарии к абзацу вставляются PO\-комментарии к первой переведенной строке этого абзаца. .IP \fBget_leading_command\fR($buffer) 4 .IX Item "get_leading_command($buffer)" Эта функция возвращает: .RS 4 .IP "Имя команды" 4 .IX Item "Имя команды" Если команда не найдена в начале буфера, эта строка будет пустой. Рассматриваются только те команды, которые могут быть разделены. Хэш \&\f(CW%separated_command\fR содержит список таких команд. .IP "Вариант вызова команды" 4 .IX Item "Вариант вызова команды" Указывает, что используется вариант команды. Например, команда создания раздела section существует в варианте section* (со звездочкой), это означает, что раздел не должен быть пронумерован. В этом случае данное поле будет содержать "*". Если вариант не используется, поле содержит пустую строку. .IP "Массив кортежей (тип аргумента, аргумент)" 4 .IX Item "Массив кортежей (тип аргумента, аргумент)" Тип аргумента может быть \*(Aq{\*(Aq (для обязательных аргументов) или \*(Aq[\*(Aq (для необязательных аргументов). .IP "Остаток буфера" 4 .IX Item "Остаток буфера" Часть буфера, оставшаяся после удаления имени команды и аргументов. Если имя команды не обнаружено, исходный буфер остается нетронутым и возвращается в это поле. .RE .RS 4 .RE .IP \fBget_trailing_command\fR($buffer) 4 .IX Item "get_trailing_command($buffer)" То же самое, что и \fBget_leading_command\fR, но для команд, содержащихся в конце буфера. .IP \fBtranslate_buffer\fR 4 .IX Item "translate_buffer" Рекурсивный перевод содержимого буфера с отделением команд, содержащихся в начале и в конце буфера (те, которые должны быть переведены отдельно). .Sp Если функция определена в \f(CW%translate_buffer_env\fR для текущего окружения, она будет использована вместо \fBtranslate_buffer()\fR. .IP \fBread\fR 4 .IX Item "read" Перегружает функцию \fBread()\fR, содержащуюся в модуле Transtractor. .IP \fBread_file\fR 4 .IX Item "read_file" Рекурсивно читает файл, добавляя содержимое файлов, указанных в командах \&\einput и \einclude, за исключением файлов, перечисленных в \&\f(CW@exclude_include\fR. Поиск включаемых файлов производится с помощью команды \&\fBkpsewhich\fR из библиотеки Kpathsea. .Sp Кроме части кода, отвечающей за включение файла. Эта часть кода взята из функции \fBread()\fR модуля Transtractor. .IP \fBparse_definition_file\fR 4 .IX Item "parse_definition_file" Подпрограмма для разбора файла с инструкциями po4a (определения новых команд). .IP \fBparse_definition_line\fR 4 .IX Item "parse_definition_line" Разбор строки в форме "% po4a: ". .Sp Подробности см. в \fBВСТРОЕННЫЕ НАСТРОЙКИ ПОВЕДЕНИЯ\fR. .IP \fBis_closed\fR 4 .IX Item "is_closed" .PD 0 .IP \fBparse\fR 4 .IX Item "parse" .IP \fBdocheader\fR 4 .IX Item "docheader" .PD .SH "ВНУТРЕННИЕ ФУНКЦИИ, используемые при создании производных парсеров" .IX Header "ВНУТРЕННИЕ ФУНКЦИИ, используемые при создании производных парсеров" Функции command и environment принимают следующие аргументы (в дополнение к \&\f(CW$self\fR object): .IP "Имя команды" 4 .IX Item "Имя команды" .PD 0 .IP "Вариант вызова команды" 4 .IX Item "Вариант вызова команды" .IP "Массив кортежей (тип аргумента, аргумент)" 4 .IX Item "Массив кортежей (тип аргумента, аргумент)" .IP "Текущее окружение" 4 .IX Item "Текущее окружение" .PD .PP Первые три аргумента, извлекаемые функцией get_leading_command или get_trailing_command. .PP Функция command возвращает перевод команды с её аргументами. Функция environment возвращает новое окружение. .PP Функции environment вызываются при обнаружении команды \ebegin. Они вызываются с командой \ebegin и её аргументами. .PP Модуль TeX предлагает только одну функцию command и одну функцию environment: generic_command и generic_environment. .PP generic_command использует информацию указанную в register_generic_command или в определении из TeX\-файла: % po4a: command \fIкоманда1\fR \fIпараметры\fR .PP generic_environment использует информацию указанную в register_generic_environment или в определении из TeX\-файла: % po4a: environment \fIокружение\fR \fIпараметры\fR .PP Обе функции будут переводить только те параметры, которые помечены как переводимые (с символом \*(Aq_\*(Aq). generic_environment добавит имя окружения в стек environment, а generic_command добавит имя команды, за которым следует идентификатор параметра (например {#7} или [#2]). .SH "СОСТОЯНИЕ ЭТОГО МОДУЛЯ" .IX Header "СОСТОЯНИЕ ЭТОГО МОДУЛЯ" Этот модуль нуждается в дополнительном тестировании. .PP Этот модуль тестировался на одной книге и документации Python. .SH "Список TODO" .IX Header "Список TODO" .IP "Автоматическое обнаружение новых команд" 4 .IX Item "Автоматическое обнаружение новых команд" Модуль TeX мог бы разбирать аргументы команды newcommand и пытаться угадать их количество, тип и то, следует ли их переводить. .IP "Перевод разделителей окружения" 4 .IX Item "Перевод разделителей окружения" Когда \eitem используется как разделитель окружения, аргумент item прикрепляется к следующей строке. .IP "Некоторые команды должны быть добавлены в стек environment" 4 .IX Item "Некоторые команды должны быть добавлены в стек environment" Эти команды должны быть указаны парами. Это может использоваться для указания команд, начинающих или заканчивающих verbatim. .IP Другое 4 .IX Item "Другое" В исходном коде различные точки помечены как TODO. .SH "ИЗВЕСТНЫЕ ОШИБКИ" .IX Header "ИЗВЕСТНЫЕ ОШИБКИ" В исходном коде различные точки помечены как FIXME. .SH "СМОТРИТЕ ТАКЖЕ" .IX Header "СМОТРИТЕ ТАКЖЕ" \&\fBLocale::Po4a::LaTeX\fR\|(3pm), \&\fBLocale::Po4a::TransTractor\fR\|(3pm), \&\fBpo4a\fR\|(7) .SH АВТОРЫ .IX Header "АВТОРЫ" .Vb 1 \& Николя Франсуа (Nicolas François) .Ve .SH "АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИИ" .IX Header "АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИИ" Copyright © 2004, 2005 Николя Франсуа (Nicolas FRANÇOIS) . .PP Данная программа является свободным программным обеспечением; вы можете распространять и/или изменять её на условиях Универсальной общественной лицензии (GPL) GNU v2.0 или новее (см. файл COPYING).