НАЗВАНИЕ

Locale::Po4a::SGML: преобразование документов SGML из/в PO-файлы

ОПИСАНИЕ

Целью проекта po4a (PO for anything, PO везде и для всего) является облегчение процесса перевода (и что более важно — поддержки перевода), используя инструменты gettext в тех случаях, когда их применение может выглядеть неожиданным, например для документации.

Locale::Po4a::Sgml — это модуль, предназначенным для помощи в переводе документации в формате SGML на другие [человеческие] языки.

Этот модуль использует onsgmls(1) для разбора файлов SGML. Убедитесь, что он установлен. Также убедитесь, что в системе установлены DTD-файлы SGML.

ПАРАМЕТРЫ ПРИНИМАЕМЫЕ ЭТИМ МОДУЛЕМ

debug: Список ключевых слов, разделенных пробелами, задающий, какие категории отладочных сообщения выводить. Возможные значения: "entities", "generic", "onsgml", "refs" и "tag".
verbose: Выводить больше информации, о том, что сейчас происходит.
translate: Список тегов, разделенных пробелами, (помимо тех, что перечислены в DTD), на основе которых нужно создавать msgid, т.е. содержимое которых нужно переводить.
section: Список тегов, разделенных пробелами, (помимо тех, что перечислены в DTD), которые содержат другие теги. Некоторые из них могут также входить в категорию translate.
indent: Список тегов, разделенных пробелами, которые добавляют дополнительные отступы к своему содержимому. Это повлияет на отступы в итоговом документа.
verbatim: Расположение элементов внутри этих тегов не должно изменяться. Переводы строк в абзацах будут сохранены, никакие дополнительные отступы добавляться не будут.
empty: Теги, которые могут быть не закрытыми.
ignore: Теги, которые игнорируются и рассматриваются po4a просто как часть строки. То есть они могут быть частью msgid. Например, <b> является хорошим примером такого тега, поскольку если бы он был переводимым (translate), то его содержимое извлекалось бы в отдельный msgids, в котором было бы только его содержимое (и обычно оно не представляет из себя законченного предложения), что не есть хорошо.
attributes: Список атрибутов тегов, разделённых пробелами, которые необходимо переводить. Вы можете задавать атрибуты просто по их имени (например, С<lang>), но вы также можете добавить к нему префикс из одного или нескольких тегов, чтобы указать, что этот атрибут должен переводиться только когда он относится к конкретному тегу. Например: "<bbb><aaa>lang" указывает, что "lang" будет переводиться только если он относится к тегу "<aaa>", который в свою очередь находится внутри тега "<bbb>". Имена тегов, на самом деле, являются регулярными выражениями, поэтому вы также можете делать штуки вроде "<aaa|bbb>lang", чтобы переводить атрибут "lang", когда он находятся или в теге "<aaa>" или в "<bbb>".
qualify: Список атрибутов, разделенных пробелами, для которых перевод должен быть дополнен именем атрибута, т.е. текст, извлечённый для перевода, будет включать как имя атрибута, так и его значение. Так например, для тега "<aaa lang_en="foo">" переводчикам для перевода будет доступна строка "lang_en="foo"". Обратите внимание, что этот параметр также автоматически добавляет данный атрибут в список attributes.
force: Не прекращать работу даже, если DTD неизвестен или onsgmls нашёл ошибку во входном файле.
include-all: По умолчанию msgid, содержащие только одну сущность (например, "&version;"), пропускаются (для удобства переводчиков). При задании этого параметра подобные строки будут извлечены для перевода наравне со всеми остальными. Это может быть полезно, если в документе будет что-то вроде "<title>Á</title>", хотя я сомневаюсь, что такое когда-нибудь действительно случится...
ignore-inclusion: Список сущностей, разделенных пробелами, которые не будут встроены. Используйте этот параметр с осторожностью: он может привести к тому, что onsgmls (используемый внутри модуля) будет добавлять лишние теги, и, в следствии этого, к созданию некорректного выходного документа.

СОСТОЯНИЕ ЭТОГО МОДУЛЯ

Результат идеальный. То есть сгенерированные документы получаются абсолютно такими же как и оригинал. Но некоторые проблемы всё ещё остаются:

Поток ошибок onsgmls по умолчанию перенаправляется в /dev/null, что, очевидно, плохо. Я не знаю, как сделать это по-другому.
Проблема в том, что мне нужно «защитить» условные включения (то есть элементы вроде "<! [ %foo [" и "]]>") от onsgmls. В противном случае onsgmls их съедает, и я не знаю, как их восстановить в итоговом документе. Чтобы предотвратить это, я заменяю их на "{PO4A-beg-foo}" и "{PO4A-end}".

И проблема в том, что расположение "{PO4A-end}" и т.п., которые я добавляю,в самом документе (а не в теге <p> или вроде того) на самом деле некорректны.

Если вы хотите увидеть вывод onsgmls, то просто добавьте следующий параметр в командную строку (или в файл настроек po4a):
```
-o debug=onsgmls
```
Этот модуль работает только с DebianDoc и DocBook DTD. Добавить поддержку других новых DTD, скорей всего, будет очень легко. Механизм одинаков для всех DTD, вам просто нужно указать список существующих тегов и некоторые их характеристики.
Я согласен, что это момент мог бы быть задокументирован и по-лучше, но этот модуль, как считается, всё ещё находится на стадии бета-версии, а я ненавижу документировать вещи, которые могут/будут измениться в будущем.
Внимание: поддержка DTD является относительно экспериментальной. Я не поверял определение всех тегов в каких-либо справочных руководствах. Я просто добавлял теги в модуль, пока оно не начало работать на некоторых документах, которые я нашёл в сети. Если в вашей документации используются какие-то ещё теги, которых не было в моей, то этот модуль не будет работать. Но, как я уже сказал выше, поправить это будет довольно легко.
DocBook я тестировал только на Руководстве системного администратора (SAG, System Administrator Guide), но этот документ довольно большой и, скорей всего, использует большую часть того что есть в спецификации DocBook.

Что касается DebianDoc, то я протестировал модуль на некоторых руководствах из DDP, хотя и не всех.
Если файл включает другие файлы, то сноски на номера строк в PO-файлах (т.е. строки типа "#: en/titletoc.sgml:9460") будут некорректными.
Это связано с тем, что я предварительно обрабатываю файл, чтобы защитить условные включения (т.е. элементы вроде "<! [ %foo [" и "]]>") и некоторые объекты (например, "&version;") от onsgmls, потому что я хочу, чтобы они копировались дословно в итоговый документ. Для этого я делаю временную копию входного файла и вношу в него все необходимые изменения, прежде чем передавать его onsgmls.

Чтобы это работало, я заменяю сущности, которые запрашивают включение файла, на содержимое данного файла (чтобы также обработать это содержимое). Но для коррекции сносок (т.е. имени файла и номеров строк) ничего не делается. И я не уверен, каким образом это всё было бы лучше сделать.

АВТОРЫ

Этот модуль является версией кода позаимствованного из sgmlspl (постпроцессора SGML для парсера ONSGMLS), изначальные авторские права на который принадлежали:

Copyright © 1995 Дэвид Меггинсон (David Megginson) <dmeggins@aix1.uottawa.ca>

Адаптация к po4a была выполнена:

Денис Барбье (Denis Barbier) <barbier@linuxfr.org>
Мартин Кенсон (Martin Quinson) (mquinson#debian.org)

АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИИ

Copyright © 1995 Дэвид Меггинсон (David Megginson) <dmeggins@aix1.uottawa.ca>
Copyright © 2002-2005 SPI, Inc.

Данная программа является свободным программным обеспечением; вы можете распространять и/или изменять её на условиях Универсальной общественной лицензии (GPL) GNU v2.0 или новее (см. файл COPYING).