НАЗВАНИЕ¶

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

ОПИСАНИЕ¶

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

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

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

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

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

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

debug

Включение отладки некоторых внутренних механизмов данного модуля. Какие части имеют отладочные закладки смотрите в исходном коде.

verbose

Увеличение количества выводимой служебной информации.

groff_code

Данный параметр позволяет изменять поведение модуля при обработке секций .de, .ie или .if. Он может принимать следующие значения:

generated

Данный параметр указывает, что файл был сгенерирован, и что po4a не должен пытаться самостоятельно определить это. Позволяет использовать 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 НАЗВАНИЕ_ДОКУМЕНТА 1 "Месяц, день, год" OS "Имя man-раздела"

Следующие параметры позволяют определить поведение новых макросов (определённые с помощью директивы .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 (например fi) или для begin (например nf). Данный макрос (и его аргументы) переводиться не будут.

inline

Данный параметр определяет разделённый запятыми список макросов, которые не должны разбивать текущий абзац. Переводимая строка будет содержать foo <.bar baz qux> quux, где bar — это команда, переданная inline, а baz и qux — её аргументы.

unknown_macros

Этот параметр определяет поведение po4a когда встречается неизвестный макрос. По умолчанию po4a завершает работу выводя предупреждение. Он может принимать следующие значения: failed (значение по умолчанию), untranslated, noarg, translate_joined, translate_each. (См. описание этих значений выше).

СОЗДАНИЕ MAN-СТРАНИЦ СОВМЕСТИМЫХ С PO4A::MAN¶

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

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

 ..               ."              .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

 .if !'po4a'hide' .B other

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

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

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

Этот модуль можно использовать с большинством существующих man страниц.

Некоторые проверки регулярно проводятся на машинах с Linux:

• треть всех страниц отвергаются, потому что они были сгенерированы из других форматов поддерживаемых po4a (например, POD или SGML).
• 10% оставшихся страниц отвергаются с какой-либо ошибкой (например из-за того, что макросы groff не поддерживаются).
• Затем, менее 1% страниц проходят все проверки po4a без сообщений об ошибках, но в результате имеют значительные проблемы (например, пропущенные или лишние слова)
• Все остальные страницы обычно обрабатываются без каких-либо проблем более значительных, нежели изменения пробелов или переносов строк (проблемы со шрифтами в менее, чем 10% обработанных страниц).

СМОТРИТЕ ТАКЖЕ¶

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)

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

Copyright © 2002-2008 SPI, Inc.

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