
        *****************************************************
        *           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>

Space-separated list of keywords indicating which category of extra debug messages should be shown. Possible values are: C<entities>, C<generic>, C<onsgml>, C<refs> and 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).

