НАЗВА¶

Locale::Po4a::TeX — перетворення документів TeX та похідних документів на файли PO, і навпаки

ОПИС¶

Метою проєкту po4a (PO для усього) є спрощення перекладу (та, що ще цікавіше, супровід перекладів) за допомогою інструментів gettext у областях, де такий переклад спочатку не передбачався, зокрема у документації.

Locale::Po4a::TeX — модуль, який допомагає у перекладі документів TeX іншими мовами (якими розмовляють люди). Модулем можна також скористатися як основою для побудови модулів для заснованих на TeX документів.

Ймовірно, користувачам варто скористатися модулем LaTeX, який є спадкоємцем модулі TeX і містити визначення загальних команд LaTeX.

ПЕРЕКЛАД ЗА ДОПОМОГОЮ PO4A::TEX¶

Цим модулем можна скористатися безпосередньо для обробки типових документів TeX. Він поділить ваш документ на менші блоки (абзаци, середовища verbatim, заголовки і пункти списків).

Передбачено декілька параметрів (які описано у наступному розділі), за допомогою яких можна налаштувати поведінку модуля. Якщо модуль не відповідає формату вашого документа, вам варто написати власний модуль, який походитиме від цього, і у якому ви опишете параметри формату. Опис процедури написання наведено у розділі НАПИСАННЯ ПОХІДНИХ МОДУЛІВ нижче.

Цей модуль також можна налаштувати рядками, які починаються з «% po4a:» у файлі TeX. Процедуру описано у розділі НАЛАШТОВУВАННЯ НА МІСЦІ section.

ПАРАМЕТРИ, ЯКІ МОЖНА ПЕРЕДАВАТИ ЦЬОМУ МОДУЛЮ¶

Ось параметри, які можна передавати цьому модулю:

debug

Задіяти діагностику деяких внутрішніх механізмів цього модуля. Скористайтеся початковим кодом, щоб ознайомитися із частинами, діагностику яких можна виконувати.

no_wrap

Список відокремлених комами середовищ, у яких не слід змінювати перенесення рядків.

Зауважте, що між середовищами verbatim і no_wrap є різниця. У блоках verbatim не виконується аналіз команд та коментарів.

Якщо це середовища ще не було зареєстровано, po4a вважатиме, що у нього немає жодних параметрів.

exclude_include

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

definitions

Назва файла, що містить визначення для po4a, як це визначено у розділі НАЛАШТОВУВАННЯ НА МІСЦІ. Ви можете скористатися цим параметром, якщо вставляння визначень до документа, який ви перекладаєте, є неможливим.

verbatim

Список відокремлених комами назв середовищ, вміст яких слід відтворювати буквально.

Якщо це середовища ще не було зареєстровано, po4a вважатиме, що у нього немає жодних параметрів.

Скористайтеся цими параметрами для перевизначення типової поведінки визначених команд.

НАЛАШТОВУВАННЯ НА МІСЦІ¶

Налаштувати модуль TeX можна рядками, які починаються з % po4a:. Такі рядки вважатимуться командами, які віддаються засобу обробки. Передбачено такі команди:

% po4a: command команда1 alias команда2

Вказує на те, що аргументи команди команда1 слід вважати аргументами команди команда2.

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

Надає змогу докладно описати параметри команди команда1. Ці дані буде використано для перевірки кількості аргументів та їхніх типів.

Ви можете вказати перед командою команда1

% po4a: environment середовище параметри

За допомогою цього рядка можна визначити параметри, які прийматимуться середовищем середовище. Ці дані пізніше буде використано для перевірки кількості аргументів команди \begin і визначення тих параметрів, які слід перекласти. Синтаксис аргументу параметри є тим самим, який описано для інших команд. Першим параметром команди \begin є назва середовища. Цей параметр має бути вказано у списку параметрів. Ось декілька прикладів:
% po4a: environment multicols {}
% po4a: environment equation

Щодо команд, перед записом середовище можна додавати «плюс» (+), щоб вказати, що команду \begin слід перекладати із усіма її аргументами.

% po4a: separator середовище "формальний_вираз"

Вказує, що середовище слід розділити за вказаним формальним виразом.

Формальний вираз у лапках. Не повинен містити зворотних посилань. Якщо потрібна група, слід використовувати (?:). Також може знадобитися екранування деяких символів.

Наприклад, у модулі LaTeX використовується формальний вираз "(?:&|\\\\)" для окремого перекладу усіх комірок таблиці (рядки відокремлюються «\\», а комірки — «&»).

Позначення середовища буде розширено до типу, показаного у файлі PO. Цим можна скористатися для поділу за «\\\\» у першому обов'язковому аргументі команди title. У нашому випадку, середовищем буде title{#1}.

% po4a: verbatim environment середовище

Вказує, що середовище є середовищем буквального цитування типу verbatim. Коментарі і команди у такому середовищі ігноруватимуться.

Якщо це середовища ще не було зареєстровано, po4a вважатиме, що у нього немає жодних параметрів.

НАПИСАННЯ ПОХІДНИХ МОДУЛІВ¶

pre_trans

post_trans

add_comment

Додати рядок як коментар до наступного перекладеного елемента. Здебільшого, корисно для модуля texinfo, оскільки коментарі автоматично обробляються у TeX.

translate

Обгортка навколо translate з Transtractor, з фільтрами попередньої і остаточної обробки.

Коментарі до абзацу буде встановлено як коментар у PO для першого рядка цього абзацу, який можна перекладати.

get_leading_command($buffer)

Ця функція повертає:

get_trailing_command($buffer)

Те саме, що і get_leading_command, але для команд наприкінці буфера.

translate_buffer

Рекурсивно перекласти буфер, відокремивши початкову і кінцеву команди (ті, які має бути перекладено окремо) з буфера.

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

read

Перевантажує read() Transtractor.

read_file

Рекурсивно прочитати файл, дописавши включені файли, яких немає у списку масиву @exclude_include. Пошук включених файлів відбувається за допомогою команди kpsewhich з бібліотеки Kpathsea.

Окрім частини, пов'язаної із включенням файлів, це буквальна копія read з Transtractor.

parse_definition_file

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

parse_definition_line

Обробляє рядок визначення у формі «% po4a: ».

Докладніший опис наведено у розділі НАЛАШТОВУВАННЯ НА МІСЦІ.

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 команда1 параметри

generic_environment використовує інформацію, задану register_generic_environment або додаванням визначення до файла TeX:
% po4a: environment середовище параметри

Обидві функції перекладають лише параметри, які було вказано як придатні до перекладу (за допомогою «_»). generic_environment дописує назву середовища до стосу середовищ, а generic_command дописує назву команди і ідентифікатором параметра (наприклад, {#7} або [#2]).

СТАН ЦЬОГО МОДУЛЯ¶

Цей модуль потребує тестування.

Його було перевірено на одній книзі та документації до Python.

СПИСОК ЗАВДАНЬ¶

Автоматичне виявлення нових команд

Модуль TeX міг би обробляти аргументи newcommand і намагатися вгадати кількість аргументів, їхній тип та те, чи слід їх перекладати.

Переклад роздільника середовищ

Якщо \item використано як роздільник середовищ, аргумент item має долучатися до наступного рядка.

Деякі команди має бути додано до стека середовища

Ці команди має бути вказано парами. Цим можна скористатися для визначення команд, які розпочинають та завершують середовище verbatim.

Інше

Інші корисні нововведення вказано у файлі TODO архіву із початковим кодом.

ВІДОМІ ВАДИ¶

Вади вказано у файлі FIXME архіву із початковим кодом.

ТАКОЖ ПЕРЕГЛЯНЬТЕ¶

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

АВТОРИ¶

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

АВТОРСЬКІ ПРАВА ТА ЛІЦЕНЗУВАННЯ¶

© Nicolas FRANÇOIS <nicolas.francois@centraliens.net>, 2004, 2005.

Ця програма є вільним програмним забезпеченням; ви можете поширювати її і/або вносити до неї зміни за умов дотримання GPL версії 2.0 або пізнішої (див. файл COPYING).