НАЗВА

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 видобуде цю команду з абзаців (якщо її розташовано на початку або наприкінці абзацу). Перекладачам слід буде перекласти параметри, які позначено як придатні до перекладу.
плюс (+): Як і для зірочки, команду буде видобуто, якщо вона стоятиме на початку або наприкінці блоку, але параметри не перекладатимуться окремо. Перекладачеві слід буде перекласти команду, об'єднану із усіма її параметрами. Це надає змогу зберегти більше контексту і корисно для команд із параметрами, які є короткими словами із багатьма значеннями (і перекладами).
Зауваження: у цьому випадку вам не потрібно вказувати, які параметри можна перекладати, але po4a має знати тип і кількість параметрів.
мінус (-): У цьому випадку команда не видобуватиметься з будь-якого блоку. Але якщо вона цілком формуватиме блок, перекладачеві буде надано можливість перекласти лише параметри, які позначено як придатні до перекладу. Корисно для команд зміни шрифту. Такі команди, зазвичай, не слід відокремлювати від абзацу (щоб зберегти контекст), але немає ніякого сенсу показувати їх перекладачеві, якщо усередині такої команди залишається цілий рядок.

Аргумент параметри є набором [] (щоб вказати необов'язковий аргумент) або {} (щоб вказати обов'язковий аргумент). Ви можете вказати символи підкреслювання (_) між дужками, щоб позначити, що параметр слід перекладати. Приклад:
% po4a: command *chapter [_]{_}

Це вказує на те, що у команди chapter є два параметри: необов'язковий (скорочений заголовок) і обов'язковий, обидва має бути перекладено. Якщо ви хочете вказати, що команда href має два обов'язкові параметри, які ви не хочете перекладати, адресу (перший параметр), і що ви не хочете, щоб цю команду було відокремлено від її абзацу (щоб перекладач міг пересунути посилання у реченні), ви можете зробити так:
% 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 середовище

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

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

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

pre_trans
post_trans
add_comment: Додати рядок як коментар до наступного перекладеного елемента. Здебільшого, корисно для модуля texinfo, оскільки коментарі автоматично обробляються у TeX.
translate: Обгортка навколо translate з Transtractor, з фільтрами попередньої і остаточної обробки.
Коментарі до абзацу буде встановлено як коментар у PO для першого рядка цього абзацу, який можна перекладати.
get_leading_command($buffer): Ця функція повертає:

Назву команди: Якщо на початку вказаного буфера не буде знайдено команди, цей рядок буде порожнім. Беруться до уваги лише команди, які можна відокремити. Список таких команд міститься у хеші %separated_command.
Варіант: Вказує, чи використано варіант. Наприклад, наприкінці команди section може бути додано зірочку (*) з метою вказати, що відповідний розділ не слід нумерувати. У цьому випадку у цьому полі буде міститися «*». Якщо варіантів немає, у полі міститиметься порожній рядок.
Масив кортежів (тип аргументу, аргумент): Типом аргументу може бути або «{» (для обов'язкових аргументів), або «[» (для необов'язкових аргументів).
Решту буфера: Решта буфера після вилучення цієї початкової команди і її аргументів. Якщо команди не буде знайдено, модуль не змінюватиме вмісту початкового буфера і поверне його у це поле.

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>

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

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