Provided by: po4a_0.57-2_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
это потребует ключа -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)
АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИИ
Copyright © 2002-2008 SPI, Inc.
This program is free software; you may redistribute it and/or modify it under the terms of
GPL (see the COPYING file).