Provided by: po4a_0.52-1_all 
ИМЯ
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
(this will require the -o untranslated=als,IR_untranslated option)
Заключение
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 familly 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)
АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИИ
Copyright 2002-2008 by SPI, inc.
This program is free software; you may redistribute it and/or modify it under the terms of GPL (see the
COPYING file).
Инструменты Po4a 2017-08-26 Locale::Po4a::Man(3pm)