DOKK / manpages / debian 12 / po4a / Locale::Po4a::Sgml.3pm.uk
Locale::Po4a::Sgml(3pm) Інструменти Po4a Locale::Po4a::Sgml(3pm)

НАЗВА

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

ОПИС

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

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

Цей модуль використовує для обробки файлів SGML onsgmls(1). Переконайтеся, що цю програму встановлено. Також переконайтеся, що у системі встановлено DTD усіх файлів SGML.

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

Список відокремлених пробілами ключових слів, які вказують, діагностику якої частини ви хочете виконати. Можливі значення: tag, generic, entities і refs.
Надавати більше інформації щодо того, що відбувається.
Список відокремлених пробілами додаткових теґів (окрім визначених у DTD), чий вміст має формувати додаткові msgid.
Список відокремлених пробілами додаткових теґів (окрім визначених у DTD), які містять інші теґи, деякі з яких належать до категорії translate.
Список відокремлених пробілами теґів, які збільшують рівень відступу.
Компонування, у якому не слід змінювати теґи. Рядки у абзаці не переноситимуться, не буде додаватися додатковий відступ або розрив рядка з косметичною метою.
Теґи не обов'язково слід закривати.
Теґи, які po4a має ігнорувати і вважати звичайними символьними даними. Тобто теґи, які можуть бути частиною msgid. Наприклад, <b> є непоганим кандидатом до цієї категорії, оскільки, якщо цей теґ перебуває у розділі translate, програма створюватиме повідомлення для перекладу, які не є цілими реченнями, що є помилкою.
Список відокремлених пробілами атрибутів, які слід перекладати. Ви можете вказати атрибути за назвою (наприклад, «lang»), але можна також дописувати префікси у ієрархії теґів, щоб вказати, що атрибут буде перекладатися, лише якщо він перебуває усередині вказаного теґу. Приклад: <bbb><aaa>lang вказує, що атрибут lang перекладатиметься, лише якщо він перебуває у тезі <aaa>, який перебуває у тезі <bbb>. Назви теґів є формальними виразами, отже ви можете написати щось подібне до <aaa|bbbb>lang, щоб перекладати атрибути lang, які перебувають усередині теґу <aaa> або <bbb>.
Список відокремлених пробілами атрибутів, для яких переклад має бути кваліфіковано назвою атрибуту. Зауважте, що цей параметр автоматично додає вказаний атрибут до списку «attributes».
Продовжувати обробку, навіть якщо DTD є невідомим, а onsgmls виявляє помилки у файлі вхідних даних.
Типово, msgid, у яких міститься лише замінник (наприклад, &version;), пропускаються заради полегшення роботи перекладачів. Використання цього параметра запобігає такій оптимізації. Корисно для документів, у яких містяться конструкції, подібні до «<title>&Aacute;</title>», хоча я і сумніваюся, що таке десь трапляється...
Список відокремлених пробілами замінників, які не вставлятимуться у текст. Будьте обережними із цим параметром: його використання може спричинити додавання onsgmls (програмою, яку використовує модуль) теґів і неправильне формування документа-результату.

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

Відмінний результат, тобто створені документи є ідентичними з оригіналом. Але усе ще є деякі проблеми:

  • Повідомлення про помилки від onsgmls типово переспрямовуються до /dev/null, а це погано. Не знаю, як цього уникнути.

    Проблема полягає у тому, що мені довелося «захистити» умовні включення (тобто конструкції "<! [ %щось [" і "]]>") від onsgmls. Якщо цього не зробити, onsgmls «з'їсть» їх, і я не знаю, як їх відновити у остаточному документі. Щоб запобігти цьому, я перезаписую їх виразами "{PO4A-beg-щось}" та "{PO4A-end}".

    Проблемним у цьому лишається те, що додані мною "{PO4A-end}" і інші подібні речі є некоректними у документі (не перебувають у тезі <p> або подібному).

    Якщо хочете ознайомитися із даними, виведеними onsgmls, просто додайте наведений нижче рядок до рядка команди (або рядка налаштовування po4a):

      -o debug=onsgmls
  • Модуль працює лише для DTD DebianDoc та DocBook. Додавання підтримки нових DTD є доволі простим. Механізм є однаковим для усіх DTD, вам слід вказати лише список наявних теґів та деякі їхні характеристики.

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

  • Попередження: підтримка DTD є доволі експериментальною. Я не читав довідники, щоб знайти визначення для кожного теґу. Я додавав теґи до модуля, аж доки усе не почало працювати для певних документів, які я знайшов у мережі. Якщо у вашому документі більше теґів, модуль не спрацює. Але, як уже було написано вище, виправити цей недолік дуже просто.

    Підтримку DocBook було перевірено лише на SAG (Підручнику системного адміністратора), але цей документ є доволі об'ємним, у ньому має бути використано більшу частину специфікаторів DocBook.

    Підтримку DebianDoc було перевірено на підручниках з DDP, але не на всіх.

  • Якщо до документа включаються додаткові файли, посилання на рядки у повідомленнях файлів PO (тобто записи, подібні до "#: en/titletoc.sgml:9460") будуть помилковими.

    Причиною є те, що попередньо файл обробляється для захисту умовних включень (тобто конструкцій типу "<! [ %щось [" і "]]>") та деяких замінників (наприклад, &version;) від onsgmls, оскільки нам вони у створеному документі потрібні без змін. Для цього створюється тимчасова копію файла вхідних даних, до якої вносяться усі потрібні зміни до передавання даних до onsgmls для обробки.

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

АВТОРИ

Цей модуль є адаптованою версією sgmlspl (обробника SGML для ONSGMLS), автором якої є:

 © David Megginson <dmeggins@aix1.uottawa.ca>, 1995

Авторами адаптації до po4a є:

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)

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

 © David Megginson <dmeggins@aix1.uottawa.ca>, 1995
 © SPI, Inc., 2002—2005

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

2023-01-03 Інструменти Po4a