НАЗВА

Locale::Po4a::Man — перетворення сторінок підручника на файли PO, і навпаки

ОПИС

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

Locale::Po4a::Man — модуль, який допомагає у перекладі документації у форматі nroff (мовою сторінок підручника) іншими мовами (якими розмовляють люди).

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

Цей модуль намагається зробити завдання перекладача якомога простішим. Для цього текст, який отримає перекладач, не є буквальною копією тексту із сторінки підручника. Найнеоковирніші частини коду nroff приховано так, щоб перекладачі не мали з ними справи.

Перенесення рядків

Абзаци без відступів автоматично розбиваються для перекладачів на рядки. Це може призвести до незначних відмінностей у результатах, оскільки правила розбиття на рядки, які використовує groff, не є доволі чіткими. Наприклад, два пробіли після дужки іноді зберігаються.

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

Специфікація шрифту

Перша зміна стосується специфікації зміни шрифту. У nroff передбачено декілька способів вказати, як має бути написано певне слово, — малим шрифтом, напівжирним шрифтом або курсивом. У тексті для перекладу передбачено лише один з цих способів, для якого використано формат POD (інтернет-документації Perl):

I<текст> — курсивний текст: еквівалент \fIтекст\fP або ".I текст"
B<текст> — напівжирний текст: еквівалент \fBтекст\fP або ".B текст"
R<текст> — текст прямим шрифтом: еквівалент \fRtext\fP
CW<текст> — текст моноширинним шрифтом: еквівалент \f(CWтекст\fP або ".CW текст"

Зауваження: гарнітурою CW можна скористатися на на всіх пристроях groff. Не рекомендуємо користуватися нею. Її реалізовано лише для зручності.

Автоматична транслітерація символів

Po4a автоматично транслітерує деякі символи з метою спрощення перекладу або рецензування перекладу. Ось список цих транслітерацій:

дефіси: Дефіси (-) і символи «мінус» (\-) на сторінках підручника усі транслітеруються у прості риски (-) у файлі PO. Далі, усі риски знову транслітеруються у символ «мінус» roff (\-) під час вставляння перекладу до документа-результату.
Перекладачі можуть примусово наказати вставити дефіс за допомогою гліфу roff «\[hy]», який вписано у переклад.
нерозривні пробіли: Перекладачі можуть використовувати у перекладах нерозривні пробіли. Нерозривний пробіл (0xA0 у latin1) буде транслітеровано у нерозривний пробіл roff («\ »).
транслітерація лапок: `` і '' буде, відповідно, транслітеровано у \*(lq та \*(rq.
Щоб уникнути таких транслітерацій, перекладачі можуть вставляти символ нульової ширини roff (тобто користуватися `\&` або '\&', відповідно).

Вставляння «<» і «>» у переклади

Оскільки ці символи використовуються для позначення частин у записах модифікації шрифтів, ви не можете використовувати їх буквально. Скористайтеся замість буквальних записами E<lt> та E<gt> (знову ж таки, як у POD).

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

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

debug: Задіяти діагностику деяких внутрішніх механізмів цього модуля. Скористайтеся початковим кодом, щоб ознайомитися із частинами, діагностику яких можна виконувати.
verbose: Збільшити рівень докладності повідомлень.
groff_code: Цей параметр надає зомгу зміни поведінку модуля, якщо у даних трапиться розділ .de, .ie або .if. Може приймати такі значення:

fail: Це типове значення. Модуль завершує роботу і повідомляє про помилку, якщо трапиться розділ .de, .ie або .if.
verbatim: Вказує на те, що розділи .de, .ie і .if має бути скопійовано без змін з оригіналу до перекладеного документа.
translate: Вказує на те, що розділи .de, .ie і .if буде запропоновано для перекладу. Користуйтеся цим варіантом, лише якщо у цих розділах містяться придатні до перекладу рядки. Якщо таких рядків там немає, варто скористатися варіантом verbatim.

generated

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

mdoc

Цей параметр корисний лише для сторінок mdoc.

Вибирає строгіший варіант підтримки формату mdoc, вказуючи po4a, що не слід перекладати розділ «NAME». Для сторінок mdoc, де перекладається розділ «NAME», не створюються верхні і нижні колонтитули.

Відповідно до сторінки groff_mdoc, розділи NAME, SYNOPSIS та DESCRIPTION є обов'язковими. Переклад розділів SYNOPSIS і DESCRIPTION не пов'язано із жодними відомими вадами, але і ці розділи можна вказати у подібний же спосіб:
-o mdoc=NAME,SYNOPSIS,DESCRIPTION

Цю ваду mdoc також можна усунути за допомогою додатка такого вмісту:
PO4A-HEADER:mode=before;position=^.Dd
.TH DOCUMENT_TITLE 1 "День місяця, рік" OS "Назва розділу"

Вказані нижче параметр надають змогу вказати поведінку для нового макросу (визначеного за допомогою запиту .de) або для макросу, підтримку якого не передбачено у po4a. Аргументом цих параметрів є список назв макросів, відокремлених комами. Приклад:

 -o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX

Зауваження: якщо підтримку макросу не передбачено у po4a, а ви вважаєте, що це стандартний макрос roff, вам слід повідомити про це команду розробників po4a.

untranslated: untranslated вказує на так, що цей макрос (і його аргументи) не слід перекладати.
noarg: noarg подібний до untranslated, але вказує на те, що po4a слід перевіряти, чи не було додано аргумент до цього макросу.
translate_joined: translate_joined вказує на те, що po4a має запропонувати перекласти аргументи макросу.
translate_each: Якщо вказано translate_each, аргументи також буде запропоновано для перекладу, але кожен із них перекладатиметься окремо.
no_wrap: Цьому параметру передається список відокремлених комами пар початок:кінець, де початок і кінець є командами, які відповідають початку і кінцю розділу, у якому не слід переносити рядки.
Зауваження: програма не виконуватиме ніяких перевірок щодо того, чи є відповідність між командами кінець і початок — будь яка команда завершення розділу зупинятиме дію режиму no_wrap. Якщо у тексті є макрос початок (відповідно, кінець) без відповідника кінець (відповідно, початок), ви можете вказати наявний у тексті кінець (наприклад, fi) або початок (наприклад, nf) як відповідник обмежувача розділу. Ці макроси (та їхні аргументи) не перекладатимуться.
inline: За допомогою цього параметра можна задати список відокремлених комами макросів, за якими не слід ділити на частини поточний абзац. Після цього у рядку для перекладу буде щось подібне до щось <.команда аргументи_команди> далі, де команда — команда, яку слід залишити у ряду, а аргументи_комнади — її аргументи.
unknown_macros: За допомогою цього параметра можна вказати, як po4a має поводитися зі знайденими невідомими макросами. Типово, po4a завершує роботу із попередженням. Параметр може приймати такі значення: failed (типове значення), untranslated, noarg, translate_joined і translate_each (пояснення щодо цих значень наведено вище).

НАПИСАННЯ СУМІСНИХ ІЗ PO4A::MAN СТОРІНОК ПІДРУЧНИКА

Можливості цього модуля дуже обмежено, і так буде завжди, оскільки він не є повноцінним інтерпретатором nroff. Можна було б створити справжній інтерпретатор nroff, щоб надати авторам змогу використовувати усі наявні макроси або навіть визначати нові макроси на власних сторінках, але нам не хотілося цього робити. Це надто ускладнило б справу, і нам здається, що у цьому немає потреби. Нам здається, що якщо автори сторінок підручника хочуть, щоб їхню роботу було перекладено, їм буде неважко зробити синтаксис сторінки простішим, щоб спростити роботу перекладачам.

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

Не програмуйте на nroff

nroff є повноцінною мовою програмування із визначенням макросів, умов тощо. Оскільки цей обробник не є повноцінним інтерпретатором nroff, він не зможе працювати зі сторінками, де використовуються можливості nroff з програмування (у моїй системі таких сторінок близько 200).

Використовуйте простий набір макросів

Підтримку деяких макросів у po4a::man ще не передбачено. Причиною є те, що авторові не вдалося знайти жодної документації щодо них. Нижче наведено список непідтримуваних макросів, які вдалося знайти у системі. Зауважте, що список є неповним, оскільки програма зупиняла роботу на першому ж непідтримуваному макросі. Якщо у вас є відомості щодо якогось з наведених макросів, автор із задоволенням додасть його підтримку. Через ці макроси близько 250 сторінок із операційної системи автора не може бути оброблено за допомогою po4a::man.

 ..               ."              .AT             .b              .bank
 .BE              ..br            .Bu             .BUGS           .BY
 .ce              .dbmmanage      .do                             .En
 .EP              .EX             .Fi             .hw             .i
 .Id              .l              .LO             .mf
 .N               .na             .NF             .nh             .nl
 .Nm              .ns             .NXR            .OPTIONS        .PB
 .pp              .PR             .PRE            .PU             .REq
 .RH              .rn             .S<             .sh             .SI
 .splitfont       .Sx             .T              .TF             .The
 .TT              .UC             .ul             .Vb             .zZ

Приховування тексту від po4a

Іноді, авторові сторінки відомо, що певні частини непридатні до перекладу, отже, їх не слід видобувати за допомогою po4a. Наприклад, параметр може приймати аргумент other, а other може бути також останнім записом у списку. У першому випадку other не слід перекладати, а у другому — слід.

У такому разі, автор може заборонити po4a видобувати певні рядки за допомогою спеціальних конструкцій у groff:

 .if !'po4a'hide' .B other

(це потребуватиме параметра -o groff_code=verbatim)

Також мона визначити новий макрос для автоматизації цього:
.de IR_untranslated
. IR \\$@
..

 .IR_untranslated \-q ", " \-\-quiet

(Це потребує параметрів -o groff_code=verbatim та -o untranslated=IR_untranslated. Якщо використано цю конструкцію, умова .if !'po4a'hide' не є обов'язковою, оскільки po4a не оброблятиме внутрішньої частини визначення макросу.)

або за допомогою альтернативи:
.als IR_untranslated IR

 .IR_untranslated \-q ", " \-\-quiet

Це потребуватиме параметра -o untranslated=als,IR_untranslated.

Висновки

Підсумовуючи написане у цьому розділі, намагайтеся бути простішими, не ускладнюйте речі при написанні ваших сторінок підручника. У nroff багато можливостей, але підтримки деяких з них не передбачено у цьому засобі обробки. Наприклад, не намагайтеся використовувати \c для переривання обробки тексту (як це зроблено на 40 сторінках у моїй системі). Також розміщуйте аргументи макросу у тому самому рядку, що і макрос. Я знаю, що так можна робити у nroff, але це надто ускладнює роботу засобу обробки даних.

Звичайно ж, можна скористатися іншим форматом, який є зручнішим для перекладу (зокрема POD із використанням po4a::pod або один із форматів сімейства XML, зокрема SGML), але завдяки po4a::man у цьому більше немає потреби. Втім, якщо початковим форматом вашої документації є POD або XML, ймовірно, варто перекладати її у початковому форматі, а не у автоматично обробленому. У більшості випадків po4a::man виявить автоматично створені сторінки і попередить про це. Модуль навіть відмовиться обробляти створені за допомогою POD сторінки, оскільки ці сторінки чудово обробляються модулем po4a::pod і оскільки відповідник nroff визначає багато нових макросів, підтримку яких у модулі man автор не хотів би реалізовувати. У системі автора модуля 1432 із 4323 сторінок створено на основі POD. Такі сторінки ігноруватимуться модулем po4a::man.

Здебільшого, po4a::man виявлятиме проблеми і відмовлятимуться обробляти сторінку, видаючи відповідне повідомлення. У деяких рідкісних випадках програма завершить роботу без повідомлення про помилку, але виведені дані будуть помилковими. Такі випадки ми називаємо «вади» ;) Якщо вам трапиться такий випадок, звичайно ж, повідомте про нього розробникам, бажано, із виправленням…

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

Цим модулем можна скористатися для більшості наявних сторінок підручника.

Ось результати регулярного тестування у системах Linux:

причиною помилок під час перетворення однієї третини зі сторінок є те, що їх було автоматично створено на основі іншого формату, підтримку якого передбачено у po4a (наприклад POD або SGML).
перетворення 10% решти сторінок завершується помилкою (наприклад, через те, що не передбачено підтримки макросу groff).
Крім того, менше за 1% сторінок вдається обробити за допомогою po4a без помилок, але результати мають суттєві вади (пропущені слова або вставлені нові слова)
Решту сторінок зазвичай вдається обробити без відмінностей, окрім відмінностей у пробілах або перенесенні рядків (проблеми зі шрифтами виникають на менш ніж 10% оброблених сторінок).

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

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

АВТОРИ

 Denis Barbier <barbier@linuxfr.org>
 Nicolas François <nicolas.francois@centraliens.net>
 Martin Quinson (mquinson#debian.org)

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

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