НАЗВАНИЕ

Locale::Po4a::Man - преобразование man-страниц из/в PO файлы

ОПИСАНИЕ

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

Locale::Po4a::Man является модулем, предназначенным для помощи в переводе документации в формате nroff (язык man-страниц) на другие [человеческие] языки.

ПЕРЕВОД С ПОМОЩЬЮ PO4A::MAN

Данный модуль делает достаточно трудную жизнь переводчика легче. Для этого, текст предоставляемый переводчику, не является полной копией текста, обнаруженной в man-странице. Фактически, части, относящиеся к nroff форматированию скрываются, поэтому переводчик не может их испортить.

Перенос текста

Unindented paragraphs are automatically rewrapped for the translator. This can lead to some minor difference in the generated output, since the rewrapping rules used by groff aren't very clear. For example, two spaces after a parenthesis are sometimes preserved.

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

Определение шрифтов

Первое изменение относится к изменению способа определения шрифтов. В nroff существует несколько способов определения того, каким должен быть шрифт: маленьким, жирным или курсивом. В тексте для перевода существует только один способ, наследуемый из формата POD (Perl online documentation):

I<text> -- курсив: эквивалентен \fItext\fP или ".I text"
B<text> -- жирный текст: эквивалентен \fBtext\fP или ".B text"
R<text> -- roman text: эквивалентен \fRtext\fP
CW<text> -- моноширинный: эквивалентен \f(CWtext\fP или ".CW text"

Заметка: Начертание CW доступно не для всех groff устройствах. Такое начертание не рекомендуется использовать. Предоставляется только для вашего удобства.

Автоматическая транслитерация символов

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

дефис: Дефис (-) и знак минуса (\-) в man страницах транслитерируются в простое тире (-) в PO файле. Затем все тире транслитерируются в знак минуса roff (\-) при формировании выходного документа.
Переводчики могут принудительно использовать roff дефис '\[hy]' в своих переводах.
неразрывные пробел: Переводчики могут использовать неразрывные пробелы. Такие неразрывные пробелы (0xA0 в latin1) будут транслитерированы в неразрывные пробелы roff ('\ ').
транслитерация кавычек: `` и '' будут транслитерированы соответственно в \*(lq and \*(rq.
Чтобы избежать подобной транлитерации, переводчики могут вставить roff символ нулевой ширины (т.е., использовать `\&` или '\&' соответственно).

Вставка '<' и '>' в перевод

Поскольку эти символы используются для разграничения глав (to delimit parts under font modification), используйте вместо них E<lt> и E<gt> (так же как в POD).

OPTIONS ACCEPTED BY THIS MODULE

Ниже приведены, специфические для данного модуля, параметры:

debug: Активация отладки для некоторых внутренних механизмов данного модуля. Используйте исходники для просмотра части, которая может быть отлажена.
verbose: Увеличение количества выводимой служебной информации.
groff_code: Данный параметр позволяет изменять поведение модуля при встрече секций .de, .ie или .if. Он может принимать следующие значения:

fail: Значение по умолчанию. Модуль будет приводить к останову при встрече с секциями .de, .ie или .if.
verbatim: Указывает на то, чтобы секции de, .ie или .if были скопированы как есть из оригинала в переводимый документ.
translate: Указывает на то, чтобы секции .de, .ie or .if были предложены для перевода. Необходимо использовать данный параметр если они содержат строки, предназначенные для перевода. В противном случае, более предпочтительной является параметр verbatim.

generated

Данный параметр указывает на то, чтобы файл был сгенерирован, и что po4a не должен пытаться определить из какого формата сгенерирована man-страница. Позволяет использовать po4a для сгенерированных страниц. Данный параметр не имеет аргументов.

mdoc

Данный параметр полезен для mdoc страниц.

Позволяет использовать строгий формат mdoc, указывая po4a не переводить секцию 'NAME'.mdoc страницы, секция 'NAME' которых не будет создавать никаких заголовков при переводе.

Согласно странице groff_mdoc секции NAME, SYNOPSIS и DESCRIPTION обязательны. Есть нерешённые проблемы при переводе секций SYNOPSIS или DESCRIPTION, но вы можете определить эти секции следующим образом:
-o mdoc=NAME,SYNOPSIS,DESCRIPTION

Проблемы mdoc также могут быть решены следующим образом:
PO4A-HEADER:mode=before;position=^.Dd
.TH DOCUMENT_TITLE 1 "Month day, year" OS "Section Name"

Следующие параметры позволяют определить поведение новых макросов (определённые с помощью запроса .de), или макросов, которые не поддерживаются po4a. В качестве аргумента подаётся список макросов, разделённый запятыми. Например:

 -o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX

Заметка: если макрос не поддерживается po4a и если вы считаете, что это стандартный макрос roff, сообщите, пожалуйста, о нем команде разработчиков po4a.

untranslated: untranslated указывает, что данный макрос (в списке аргументов) не нужно переводить.
noarg: noarg подобен untranslated, с точностью до того, что po4a будет проверять чтобы аргументы не добавлялись в данный макрос.
translate_joined: translate_joined указывает на то, что po4a должен предложить перевести аргумент макроса.
translate_each: С translate_each, аргументы будут так же предложены для перевода, но каждый будет переводиться отдельно.
no_wrap: Данный параметр принимает в качестве аргумента список, разделённых запятыми несколько - begin:end, где begin и end являются командами, которые разделяют начало и конец секции, которая должна быть переформатирована (rewrapped).
Заметка: не проводится никакого тестирования для того, чтобы удостовериться, что каждой команде end соответствует команда begin; любая завершающая команда отключает режим no_wrap . Если встречается макрос begin (соответственно end) или макрос end (соответственно begin), вам необходимо определить существующий end (like fi) или begin (like nf). Данный макрос (и его аргументы) переводить не нужно.
inline: Данный параметр определяет список разделённых запятыми макросов, которые не должны разделять текущий параграф. Строка для перевода будет содержать foo <.bar baz qux> quux, где bar является командой, которая должна быть подставлена, а baz qux ее аргументы.
unknown_macros: This option indicates how po4a should behave when an unknown macro is found. By default, po4a fails with a warning. It can take the following values: failed (the default value), untranslated, noarg, translate_joined, or translate_each (see above for an explanation of these values).

СОГЛАШЕНИЕ МЕЖДУ АВТОРАМИ MAN-СТРАНИЦ И PO4A::MAN

Данный модуль очень ограничен и будет таким всегда, так как он не является интерпретатором nroff. Возможно в будущем можно будет создать настоящий интерпретатор nroff, чтобы предоставить авторам возможность использовать все существующие макросы, но мы не хотим делать это. Это может оказаться слишком сложной задачей и, как мы считаем, в этом нет необходимости. Мы считаем, что если авторы man-страниц хотят видеть свои продукты переведёнными, то они могут их адаптировать, чтобы облегчить работу переводчикам.

Таким образом парсер () встроенный в po4a имеет несколько известных ограничений, которые мы не склонны корректировать, и которые содержат в себе потенциальные опасности, которые вам необходимо учитывать если вы хотите, чтобы переводчики заботились о вашей документации.

Не программируйте на nroff

nroff это полноценный язык программирования, с возможностью определения макросов, conditionals и так далее. Так как этот парсер не является полнофункциональным интерпретатором nroff, он не сможет обработать страницы, использующие эти возможности (у меня есть около 200 таких страниц).

Используйте простой набор макросов

Существуют еще несколько макросов, которые не поддерживаются po4a::man. Только потому что я не смог отыскать документацию по ним. Ниже приведён список неподдерживаемых макросов, используемых на моем компьютере. Обратите внимание, что этот список не является полным, так как программа завершает работу при первой встрече с неподдерживаемым макросом. Если у вас есть информация о каком-либо из этих макросов, я с удовольствием добавлю поддержку данных макросов. Потому что на моем компьютере около 250 страниц некорректно обрабатывающихся po4a::man.

 ..               ."              .AT             .b              .bank
 .BE              ..br            .Bu             .BUGS           .BY
 .ce              .dbmmanage      .do                             .En
 .EP              .EX             .Fi             .hw             .i
 .Id              .l              .LO             .mf
 .N               .na             .NF             .nh             .nl
 .Nm              .ns             .NXR            .OPTIONS        .PB
 .pp              .PR             .PRE            .PU             .REq
 .RH              .rn             .S<             .sh             .SI
 .splitfont       .Sx             .T              .TF             .The
 .TT              .UC             .ul             .Vb             .zZ

Скрытие текста в po4a

Иногда автор знает, что некоторые части не надо переводить и поэтому не должны извлекаться программой po4a. Например настройка может принимать аргумент other, и other может всегда появляться конце списка. В первом случае, other не должен переводиться. А во втором случае other должен быть переведён.

В данном случае, автор может избежать извлечения некоторых строк программой po4a, с помощью использования некоторых groff конструкций:

 .if !'po4a'hide' .B other

(это потребует ключа -o groff_code=verbatim)

Можно определить также новый макрос, чтобы автоматизировать этот процесс:
.de IR_untranslated
. IR \\$@
..

 .IR_untranslated \-q ", " \-\-quiet

(this will require the options -o groff_code=verbatim and -o untranslated=IR_untranslated; with this construct, the .if !'po4a'hide' conditional is not strictly needed since po4a will not parse the internal of the macro definition)

or using an alias:
.als IR_untranslated IR

 .IR_untranslated \-q ", " \-\-quiet

это потребует ключа -o groff_code=verbatim.

Заключение

To summarise this section, keep simple, and don't try to be clever while authoring your man pages. A lot of things are possible in nroff, and not supported by this parser. For example, don't try to mess with \c to interrupt the text processing (like 40 pages on my box do). Or, be sure to put the macro arguments on the same line that the macro itself. I know that it's valid in nroff, but would complicate too much the parser to be handled.

Of course, another possibility is to use another format, more translator friendly (like POD using po4a::pod, or one of the XML family like SGML), but thanks to po4a::man it isn't needed anymore. That being said, if the source format of your documentation is POD, or XML, it may be clever to translate the source format and not this generated one. In most cases, po4a::man will detect generated pages and issue a warning. It will even refuse to process POD generated pages, because those pages are perfectly handled by po4a::pod, and because their nroff counterpart defines a lot of new macros I didn't want to write support for. On my box, 1432 of the 4323 pages are generated from POD and will be ignored by po4a::man.

In most cases, po4a::man will detect the problem and refuse to process the page, issuing an adapted message. In some rare cases, the program will complete without warning, but the output will be wrong. Such cases are called "bugs" ;) If you encounter such case, be sure to report this, along with a fix when possible…

STATUS OF THIS MODULE

This module can be used for most of the existing man pages.

Some tests are regularly run on Linux boxes:

one third of the pages are refused because they were generated from another format supported by po4a (e.g. POD or SGML).
10% of the remaining pages are rejected with an error (e.g. a groff macro is not supported).
Then, less than 1% of the pages are accepted silently by po4a, but with significant issues (i.e. missing words, or new words inserted)
The other pages are usually handled without differences more important than spacing differences or line rewrapped (font issues in less than 10% of the processed pages).

СМОТРИ ТАКЖЕ

Locale::Po4a::Pod(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)

АВТОРЫ

 Denis Barbier <barbier@linuxfr.org>
 Nicolas François <nicolas.francois@centraliens.net>
 Martin Quinson (mquinson#debian.org)

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

This program is free software; you may redistribute it and/or modify it under the terms of GPL (see the COPYING file).