
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 НАЗВАНИЕ

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

=head1 ОПИСАНИЕ

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

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

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

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

=over 4

=item B<debug>

Список ключевых слов, разделенных пробелами, задающий, какие категории
отладочных сообщения выводить. Возможные значения: C<entities>, C<generic>,
C<onsgml>, C<refs> и C<tag>.

=item B<verbose>

Выводить больше информации, о том, что сейчас происходит.

=item B<translate>

Список тегов, разделенных пробелами, (помимо тех, что перечислены в DTD), на
основе которых нужно создавать msgid, т.е. содержимое которых нужно
переводить.

=item B<section>

Список тегов, разделенных пробелами, (помимо тех, что перечислены в DTD),
которые содержат другие теги. Некоторые из них могут также входить в
категорию B<translate>.

=item B<indent>

Список тегов, разделенных пробелами, которые добавляют дополнительные
отступы к своему содержимому. Это повлияет на отступы в итоговом документе.

=item B<verbatim>

Расположение элементов внутри этих тегов не должно изменяться. Переводы
строк в абзацах будут сохранены, никакие дополнительные отступы добавляться
не будут.

=item B<empty>

Теги, которые могут быть не закрытыми.

=item B<ignore>

Теги, которые игнорируются и рассматриваются po4a просто как часть
строки. То есть они могут быть частью msgid. Например, E<lt>bE<gt> является
хорошим примером такого тега, поскольку, если бы он был переводимым
(B<translate>), то его содержимое извлекалось бы в отдельный msgids, в
котором было бы только его содержимое (и обычно оно не представляет из себя
законченного предложения), что не есть хорошо.

=item B<attributes>

Список атрибутов тегов, разделённых пробелами, которые необходимо
переводить. Вы можете задавать атрибуты просто по их имени (например,
С<lang>), но вы также можете добавить к нему префикс из одного или
нескольких тегов, чтобы указать, что этот атрибут должен переводиться только
когда он относится к конкретному тегу. Например: C<< <bbb><aaa>lang >>
указывает, что C<lang> будет переводиться только если он относится к тегу
C<< <aaa> >>, который в свою очередь находится внутри тега C<< <bbb>
>>. Имена тегов, на самом деле, являются регулярными выражениями, поэтому вы
также можете делать штуки вроде C<< <aaa|bbb>lang >>, чтобы переводить
атрибут C<lang>, когда он находятся или в теге C<< <aaa> >> или в C<< <bbb>
>>.

=item B<qualify>

Список атрибутов, разделенных пробелами, для которых перевод должен быть
дополнен именем атрибута, т.е. текст, извлечённый для перевода, будет
включать как имя атрибута, так и его значение. Так например, для тега C<<
<aaa lang_en="foo"> >> переводчикам для перевода будет доступна строка
C<lang_en="foo">. Обратите внимание, что этот параметр также автоматически
добавляет данный атрибут в список B<attributes>.

=item B<force>

Не прекращать работу даже, если DTD неизвестен или B<onsgmls> нашёл ошибку
во входном файле.

=item B<include-all>

По умолчанию msgid, содержащие только одну сущность (например,
C<&version;>), пропускаются (для удобства переводчиков). При задании этого
параметра подобные строки будут извлечены для перевода наравне со всеми
остальными. Это может быть полезно, если в документе будет что-то вроде C<<
<title>&Aacute;</title> >>, хотя я сомневаюсь, что такое когда-нибудь
действительно случится...

=item B<ignore-inclusion>

Список сущностей, разделенных пробелами, которые не будут
встроены. Используйте этот параметр с осторожностью: он может привести к
тому, что B<onsgmls> (используемый внутри модуля) будет добавлять лишние
теги, и, в следствии этого, к созданию некорректного выходного документа.

=back

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

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

=over 2

=item *

Поток ошибок B<onsgmls> по умолчанию перенаправляется в /dev/null, что,
очевидно, плохо. Я не знаю, как сделать это по-другому.

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

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

Если вы хотите увидеть вывод B<onsgmls>, то просто добавьте следующий
параметр в командную строку (или в файл настроек po4a):

  -o debug=onsgmls

=item *

Этот модуль работает только с DebianDoc и DocBook DTD. Добавить поддержку
других новых DTD, скорей всего, будет очень легко. Механизм одинаков для
всех DTD, вам просто нужно указать список существующих тегов и некоторые их
характеристики.

Я согласен, что это момент мог бы быть задокументирован и по-лучше, но этот
модуль, как считается, всё ещё находится на стадии бета-версии, а я ненавижу
документировать вещи, которые могут/будут измениться в будущем.

=item *

Внимание: поддержка DTD является относительно экспериментальной. Я не
поверял определение всех тегов в каких-либо справочных руководствах. Я
просто добавлял теги в модуль, пока оно не начало работать на некоторых
документах, которые я нашёл в сети. Если в вашей документации используются
какие-то ещё теги, которых не было в моей, то этот модуль не будет
работать. Но, как я уже сказал выше, поправить это будет довольно легко.

DocBook я тестировал только на Руководстве системного администратора (SAG,
System Administrator Guide), но этот документ довольно большой и, скорей
всего, использует большую часть того что есть в спецификации DocBook.

Что касается DebianDoc, то я протестировал модуль на некоторых руководствах
из DDP, хотя и не всех.

=item *

Если файл включает другие файлы, то сноски на номера строк в PO-файлах
(т.е. строки типа C<#: en/titletoc.sgml:9460>) будут некорректными.

Это связано с тем, что я предварительно обрабатываю файл, чтобы защитить
условные включения (т.е. элементы вроде C<E<lt>! [ %foo [> и C<]]E<gt>>) и
некоторые объекты (например, C<&version;>) от B<onsgmls>, потому что я хочу,
чтобы они копировались дословно в итоговый документ. Для этого я делаю
временную копию входного файла и вношу в него все необходимые изменения,
прежде чем передавать его B<onsgmls>.

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

=back

=head1 АВТОРЫ

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

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

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

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

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

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

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