DOKK / manpages / debian 13 / po4a / Locale::Po4a::Sgml.3pm.ru
LOCALE::PO4A::SGML.3PM(1) User Contributed Perl Documentation LOCALE::PO4A::SGML.3PM(1)

НАЗВАНИЕ

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

ОПИСАНИЕ

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

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

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

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

Space-separated list of keywords indicating which category of extra debug messages should be shown. Possible values are: "entities", "generic", "onsgml", "refs" and "tag".
Выводить больше информации, о том, что сейчас происходит.
Список тегов, разделенных пробелами, (помимо тех, что перечислены в DTD), на основе которых нужно создавать msgid, т.е. содержимое которых нужно переводить.
Список тегов, разделенных пробелами, (помимо тех, что перечислены в DTD), которые содержат другие теги. Некоторые из них могут также входить в категорию translate.
Список тегов, разделенных пробелами, которые добавляют дополнительные отступы к своему содержимому. Это повлияет на отступы в итоговом документа.
Расположение элементов внутри этих тегов не должно изменяться. Переводы строк в абзацах будут сохранены, никакие дополнительные отступы добавляться не будут.
Теги, которые могут быть не закрытыми.
Теги, которые игнорируются и рассматриваются po4a просто как часть строки. То есть они могут быть частью msgid. Например, <b> является хорошим примером такого тега, поскольку если бы он был переводимым (translate), то его содержимое извлекалось бы в отдельный msgids, в котором было бы только его содержимое (и обычно оно не представляет из себя законченного предложения), что не есть хорошо.
Список атрибутов тегов, разделённых пробелами, которые необходимо переводить. Вы можете задавать атрибуты просто по их имени (например, С<lang>), но вы также можете добавить к нему префикс из одного или нескольких тегов, чтобы указать, что этот атрибут должен переводиться только когда он относится к конкретному тегу. Например: "<bbb><aaa>lang" указывает, что "lang" будет переводиться только если он относится к тегу "<aaa>", который в свою очередь находится внутри тега "<bbb>". Имена тегов, на самом деле, являются регулярными выражениями, поэтому вы также можете делать штуки вроде "<aaa|bbb>lang", чтобы переводить атрибут "lang", когда он находятся или в теге "<aaa>" или в "<bbb>".
Список атрибутов, разделенных пробелами, для которых перевод должен быть дополнен именем атрибута, т.е. текст, извлечённый для перевода, будет включать как имя атрибута, так и его значение. Так например, для тега "<aaa lang_en="foo">" переводчикам для перевода будет доступна строка "lang_en="foo"". Обратите внимание, что этот параметр также автоматически добавляет данный атрибут в список attributes.
Не прекращать работу даже, если DTD неизвестен или onsgmls нашёл ошибку во входном файле.
По умолчанию msgid, содержащие только одну сущность (например, "&version;"), пропускаются (для удобства переводчиков). При задании этого параметра подобные строки будут извлечены для перевода наравне со всеми остальными. Это может быть полезно, если в документе будет что-то вроде "<title>&Aacute;</title>", хотя я сомневаюсь, что такое когда-нибудь действительно случится...
Список сущностей, разделенных пробелами, которые не будут встроены. Используйте этот параметр с осторожностью: он может привести к тому, что 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).

2024-08-06 perl v5.38.2