Locale::Po4a::Sgml
Section: Инструменты Po4a (3pm)Updated: 2024-01-29
Index Return to Main Contents
НАЗВАНИЕ
Locale::Po4a::SGML: преобразование документов SGML из/в PO-файлыОПИСАНИЕ
Целью проекта po4a (PO for anything, PO везде и для всего) является облегчение процесса перевода (и что более важно — поддержки перевода), используя инструменты gettext в тех случаях, когда их применение может выглядеть неожиданным, например для документации.Locale::Po4a::Sgml — это модуль, предназначенным для помощи в переводе документации в формате SGML на другие [человеческие] языки.
Этот модуль использует onsgmls(1) для разбора файлов SGML. Убедитесь, что он установлен. Также убедитесь, что в системе установлены DTD-файлы SGML.
ПАРАМЕТРЫ ПРИНИМАЕМЫЕ ЭТИМ МОДУЛЕМ
- debug
- Список ключевых слов, разделенных пробелами, задающий, какие отладочные сообщения выводить. Возможные значения: "tag", "generic", "entities" и "refs".
- 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|bbbb>lang, чтобы переводить атрибут lang, когда он находятся или в теге <aaa> или в <bbb>.
- qualify
- Список атрибутов, разделенных пробелами, для которых перевод должен быть дополнен именем атрибута. Обратите внимание, что этот параметр также автоматически добавляет данный атрибут в список 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).
Index
- НАЗВАНИЕ
- ОПИСАНИЕ
- ПАРАМЕТРЫ ПРИНИМАЕМЫЕ ЭТИМ МОДУЛЕМ
- СОСТОЯНИЕ ЭТОГО МОДУЛЯ
- АВТОРЫ
- АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИИ
This document was created by using the manual pages.
Time: 00:28:47 GMT, January 29, 2024