.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Locale::Po4a::Man 3pm" .TH Locale::Po4a::Man 3pm "2023-01-03" "Инструменты Po4a" "Инструменты Po4a" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "НАЗВАНИЕ" .IX Header "НАЗВАНИЕ" Locale::Po4a::Man: преобразование man\-страниц из/в PO\-файлы .SH "ОПИСАНИЕ" .IX Header "ОПИСАНИЕ" Целью проекта po4a (\s-1PO\s0 for anything, \s-1PO\s0 везде и для всего) является облегчение процесса перевода (и что более важно — поддержки перевода), используя инструменты gettext в тех случаях, когда их применение может выглядеть неожиданным, например для документации. .PP Locale::Po4a::Man — это модуль, предназначенным для помощи в переводе документации в формате nroff (язык разметки man\-страниц) на другие [человеческие] языки. .SH "ПЕРЕВОД С ПОМОЩЬЮ PO4A::MAN" .IX Header "ПЕРЕВОД С ПОМОЩЬЮ PO4A::MAN" Этот модуль старается как только может, чтобы облегчить жизнь переводчика. Чтобы добиться этого, передаваемый переводчику текст не является дословной копией содержимого man\-страницы. Фактически, большинство сырых элементов формата nroff скрыты от глаз переводчика так, чтобы он не смог их испортить. .SS "Перенос текста" .IX Subsection "Перенос текста" Абзацы без отступов будут автоматически переформатированы для переводчика. Это может привести к некоторым незначительным отличиям в выходных файлах, т.к. правила форматирования используемые groff не совсем чёткие. Например, иногда резервируется два пробела после скобок. .PP В любом случае, отличия будут только в положении дополнительных пробелов в переформатированном абзаце и, как мне кажется, это мелочь. .SS "Определение шрифтов" .IX Subsection "Определение шрифтов" Первое изменение — это изменение способа определения шрифтов. В nroff, существует несколько способов определить, каким должен быть шрифт, маленьким, жирным или курсивом. В переводимом тексте, существует только один способ, позаимствованный из формата \s-1POD\s0 (Perl online documentation): .IP "I<текст> \*(-- курсив" 4 .IX Item "I<текст> курсив" эквивалентен \efIтекст\efP или \*(L".I текст\*(R" .IP "B<текст> \*(-- жирный" 4 .IX Item "B<текст> жирный" эквивалентен \efBтекст\efP или \*(L".B текст\*(R" .IP "R<текст> \*(-- обычный (man использует термин «roman» )" 4 .IX Item "R<текст> обычный (man использует термин «roman» )" эквивалентен \efRтекст\efP .IP "CW<текст> \*(-- моноширинный" 4 .IX Item "CW<текст> моноширинный" эквивалентен \ef(CWтекст\efP или \*(L".CW текст\*(R" .PP Замечание: Начертание \s-1CW\s0 доступно не на всех groff устройствах. Такое начертание не рекомендуется использовать. Предоставляется только для вашего удобства. .SS "Автоматическая транслитерация символов" .IX Subsection "Автоматическая транслитерация символов" Po4a автоматически производит транслитерацию некоторых символов для облегчения перевода или последующей проверки оного. Ниже приведён список таких транслитераций: .IP "дефисы" 4 .IX Item "дефисы" Дефис (\-) и знак минуса (\e\-) в man страницах транслитерируются в простое тире (\-) в PO\-файле. Затем все тире транслитерируются в знак минуса roff (\e\-) при формировании выходного документа. .Sp Переводчики могут принудительно использовать roff дефис '\e[hy]' в своих переводах. .IP "неразрывные пробелы" 4 .IX Item "неразрывные пробелы" Переводчики могут использовать неразрывные пробелы. Такие неразрывные пробелы (0xA0 в latin1) будут транслитерированы в неразрывные пробелы roff ('\e '). .IP "транслитерация кавычек" 4 .IX Item "транслитерация кавычек" `` и '' будут соответственно транслитерированы в \e*(lq и \e*(rq. .Sp Чтобы избежать подобной транслитерации, переводчики могут вставить roff символ нулевой ширины (т.е., использовать `\e&` или '\e&' соответственно). .SS "Вставка '<' и '>' в перевод" .IX Subsection "Вставка '<' и '>' в перевод" Поскольку эти символы используются для разделения частей при изменении шрифта, вы не можете использовать их буквально. Используйте вместо них E и E (так же как в \s-1POD\s0). .SH "ПАРАМЕТРЫ ПРИНИМАЕМЫЕ ЭТИМ МОДУЛЕМ" .IX Header "ПАРАМЕТРЫ ПРИНИМАЕМЫЕ ЭТИМ МОДУЛЕМ" Ниже приведены специфические для данного модуля параметры: .IP "\fBdebug\fR" 4 .IX Item "debug" Включение отладки некоторых внутренних механизмов данного модуля. Какие части имеют отладочные закладки смотрите в исходном коде. .IP "\fBverbose\fR" 4 .IX Item "verbose" Увеличение количества выводимой служебной информации. .IP "\fBgroff_code\fR" 4 .IX Item "groff_code" This option controls the behavior of the module when it encounter a .de, .ie or .if section. It can take the following values: .RS 4 .IP "\fIfail\fR" 4 .IX Item "fail" Значение по умолчанию. Модуль будет приводить к останову при встрече с секциями .de, .ie или .if. .IP "\fIverbatim\fR" 4 .IX Item "verbatim" Указывает на то, чтобы секции de, .ie или .if были скопированы как есть из оригинала в переведённый документ. .IP "\fItranslate\fR" 4 .IX Item "translate" Указывает, чтобы секции .de, .ie или .if были предложены для перевода. Данное значение необходимо использовать, если эти секции содержат кукую\-либо переводимую строку. В противном случае, следует использовать \fIverbatim\fR. .RE .RS 4 .RE .IP "\fBgenerated\fR" 4 .IX Item "generated" This option specifies that the file was generated, and that po4a should not try to detect if the man pages was generated from another format. This option is mandatory to use po4a on generated man pages. Note that translating generated pages instead of sources ones is often more fragile, and thus a bad idea. .IP "\fBmdoc\fR" 4 .IX Item "mdoc" Данный параметр может быть полезен только для mdoc страниц. .Sp Позволяет использовать более строгий формат mdoc, в частности, указывая po4a не переводить название секции '\s-1NAME\s0'. Для страниц mdoc, с переведённой секцией '\s-1NAME\s0', не будут создаваться собственные верхние и нижние колонтитулы. .Sp Согласно странице справки groff_mdoc, секции \s-1NAME, SYNOPSIS\s0 и \s-1DESCRIPTION\s0 обязательны. Однако, какие\-либо проблемы при переводе названий секций \s-1SYNOPSIS\s0 или \s-1DESCRIPTION,\s0 на данный момент не известны, но вы также можете предотвратить перевод имён данных секций следующим образом: \-o mdoc=NAME,SYNOPSIS,DESCRIPTION .Sp Эти проблемы mdoc также можно решить с помощью файла дополнения: PO4A\-HEADER:mode=before;position=^.Dd .TH НАЗВАНИЕ_ДОКУМЕНТА 1 \*(L"Месяц, день, год\*(R" \s-1OS\s0 \*(L"Имя man\-раздела\*(R" .PP The following options specify the behavior of a user-defined macro (with a .de request), or of a classical macro that is not supported by po4a. They take as argument a comma-separated list of macros. For example: .PP .Vb 1 \& \-o noarg=FO,OB,AR \-o translate_joined=BA,ZQ,UX .Ve .PP Замечание: если макрос не поддерживается po4a и вы считаете, что это стандартный макрос roff, сообщите, пожалуйста, об этом команде разработчиков po4a. .IP "\fBuntranslated\fR" 4 .IX Item "untranslated" \&\fBuntranslated\fR указывает, что данные макросы (указанные в аргументе) не требуют перевода. .IP "\fBnoarg\fR" 4 .IX Item "noarg" \&\fBnoarg\fR подобен \fBuntranslated\fR, с той разницей что po4a будет проверять чтобы аргументы не передавались данному макросу. .IP "\fBtranslate_joined\fR" 4 .IX Item "translate_joined" \&\fBtranslate_joined\fR указывает, что po4a должен отметить для перевода аргументы данного макроса. .IP "\fBtranslate_each\fR" 4 .IX Item "translate_each" С \fBtranslate_each\fR, аргументы будут также отмечены для перевода, но каждый из них будет переводиться отдельно. .IP "\fBno_wrap\fR" 4 .IX Item "no_wrap" Данный параметр принимает в качестве аргумента разделённый замятыми список пар \fIbegin\fR:\fIend\fR, где \fIbegin\fR и \fIend\fR являются командами, которые определяют начало и конец секции, которая не должна быть переформатирована (rewrapped). .Sp Note: no test is done to ensure that an \fIend\fR command matches its \fIbegin\fR command; any ending command stop the no_wrap mode. If you have a \fIbegin\fR (respectively \fIend\fR) macro that has no \fIend\fR (respectively \fIbegin\fR), you can specify an existing \fIend\fR (like fi) or \fIbegin\fR (like nf) as a counterpart. These macros (and their arguments) won't be translated. .IP "\fBinline\fR" 4 .IX Item "inline" Данный параметр определяет разделённый запятыми список макросов, которые не должны разбивать текущий абзац. Переводимая строка будет содержать \fIfoo <.bar baz qux> quux\fR, где \fIbar\fR — это команда, переданная \fBinline\fR, а \fIbaz\fR и \fIqux\fR — её аргументы. .IP "\fBunknown_macros\fR" 4 .IX Item "unknown_macros" Этот параметр определяет поведение po4a когда встречается неизвестный макрос. По умолчанию po4a завершает работу выводя предупреждение. Он может принимать следующие значения: \fIfailed\fR (значение по умолчанию), \fIuntranslated\fR, \fInoarg\fR, \fItranslate_joined\fR, \fItranslate_each\fR. (См. описание этих значений выше). .SH "СОЗДАНИЕ MAN\-СТРАНИЦ СОВМЕСТИМЫХ С PO4A::MAN" .IX Header "СОЗДАНИЕ MAN-СТРАНИЦ СОВМЕСТИМЫХ С PO4A::MAN" Данный модуль очень ограничен и будет таким всегда, т.к. он не является интерпретатором nroff. Конечно, было бы возможно создать настоящий интерпретатор nroff, чтобы предоставить авторам возможность использовать все существующие макросы или даже объявлять новые, но мы не хотим этим заниматься. Это было бы слишком сложной задачей и, как мы считаем, в этом нет необходимости. Мы считаем, что если авторы man\-страниц хотят видеть свои творения переведёнными, то они могут их адаптировать, чтобы облегчить работу переводчикам. .PP Таким образом у парсера, реализованного в po4a, есть несколько известных ограничений, которые мы не собираемся устранять. Эти ограничения содержат некоторые ловушки, которые вам придётся избегать, если вы хотите чтобы переводчики позаботились о вашей документации. .SS "Не программируйте на nroff" .IX Subsection "Не программируйте на nroff" nroff это полноценный язык программирования, с возможностью определения макросов, условными операторами и так далее. Так как этот парсер не является полнофункциональным интерпретатором nroff, он не сможет обработать страницы, использующие подобные возможности (у меня есть около 200 таких страниц). .SS "Используйте простой набор макросов" .IX Subsection "Используйте простой набор макросов" Есть ещё несколько макросов, которые не поддерживаются po4a::man только потому, что я не смог отыскать документацию по ним. Ниже приведён список таковых макросов используемых на моём компьютере. Обратите внимание, что этот список не является полным, т.к. программа завершает работу при первой встрече с неподдерживаемым макросом. Если у вас есть информация о каком либо из них, я с удовольствием добавлю поддержку оного. Из\-за таких макросов po4a::man не может обработать корректно порядка 250 страниц на моём компьютере. .PP .Vb 11 \& .. ." .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 .Ve .SS "Скрытие текста от po4a" .IX Subsection "Скрытие текста от po4a" Иногда автор знает, что некоторые части не подлежат переводу и не должны извлекаться программой po4a. Например, параметр может принимать аргумент \fIother\fR, и \fIother\fR может также обозначать последний аргумент списка. В первом случае, \fIother\fR не должно быть переведено. А во втором случае — должно. .PP В этом случае, автор может заставить po4a воздержаться от извлечения некоторых строк, с помощью определённых groff конструкций: .PP .Vb 1 \& .if !\*(Aqpo4a\*(Aqhide\*(Aq .B other .Ve .PP (это потребует параметра \fB\-o groff_code=verbatim\fR) .PP Можно также определить новый макрос, чтобы автоматизировать этот процесс: .de IR_untranslated . \s-1IR\s0 \e\e$@ .. .PP .Vb 1 \& .IR_untranslated \e\-q ", " \e\-\e\-quiet .Ve .PP (это потребует параметров \fB\-o groff_code=verbatim\fR и \fB\-o untranslated=IR_untranslated\fR; с этой конструкцией условный оператор \fB.if !'po4a'hide'\fR, строго говоря, не обязателен т.к. po4a не будет пытаться разобрать внутреннюю часть макроопределения) .PP или использовать псевдоним: .als IR_untranslated \s-1IR\s0 .PP .Vb 1 \& .IR_untranslated \e\-q ", " \e\-\e\-quiet .Ve .PP Это потребует параметра \fB\-o untranslated=als,IR_untranslated\fR. .SS "Заключение" .IX Subsection "Заключение" Подводя итоги выше сказанному, делайте всё просто и не пытайтесь умничать, когда готовите свои man\-страницы. В nroff есть много возможностей, и многие из них не поддерживаются этим парсером. Например, не пытайтесь связываться с \ec, чтобы остановить исполнение (как делают 40 страниц на моей машине). И убедитесь, что оставляете аргументы макроса на той же строке, что и он сам. Я знаю, что обратное допустимо в nroff, но это сильно осложнит работу парсера. .PP Конечно, другая возможность — это использовать другой формат, более дружелюбный к переводчикам (например \s-1POD\s0 с po4a::pod или один из XML\-семейства, например \s-1SGML\s0), но благодаря po4a::man в этом больше нет необходимости. Как говорится, если исходный формат вашей документации \s-1POD\s0 или \s-1XML,\s0 то будет мудро переводить исходный формат, а не то что из него сгенерировано. В большинстве случаев, po4a::man определяет сгенерированные страницы и выводит предупреждение. Он даже откажется обрабатывать сгенерированные из \s-1POD\s0 страницы, потому что такие страницы идеально обрабатываются с помощью po4a::pod и потому что nroff в них определяет уйму новых макросов, для которых у меня нет ни какого желания писать поддержку. На моей машине, 1432 из 4323 страниц сгенерированы из \s-1POD\s0 и будут проигнорированы po4a::man. .PP В большинстве случаев po4a::man будет находить проблему и прекратит обработку страницы, выводя удовлетворительное сообщение. В некоторых редких случаях программа завершится без предупреждений, но вывод будет ошибочным. Такие случаи называются «Багами» ;) Если вы столкнётесь с подобными ситуациями, обязательно сообщайте о них, по возможности с исправлениями… .SH "СОСТОЯНИЕ ЭТОГО МОДУЛЯ" .IX Header "СОСТОЯНИЕ ЭТОГО МОДУЛЯ" Этот модуль можно использовать с большинством существующих man страниц. .PP Некоторые проверки регулярно проводятся на машинах с Linux: .IP "\(bu" 4 треть всех страниц отвергаются, потому что они были сгенерированы из других форматов поддерживаемых po4a (например, \s-1POD\s0 или \s-1SGML\s0). .IP "\(bu" 4 10% оставшихся страниц отвергаются с какой\-либо ошибкой (например из\-за того, что макросы groff не поддерживаются). .IP "\(bu" 4 Затем, менее 1% страниц проходят все проверки po4a без сообщений об ошибках, но в результате имеют значительные проблемы (например, пропущенные или лишние слова) .IP "\(bu" 4 Все остальные страницы обычно обрабатываются без каких\-либо проблем более значительных, нежели изменения пробелов или переносов строк (проблемы со шрифтами в менее, чем 10% обработанных страниц). .SH "СМОТРИТЕ ТАКЖЕ" .IX Header "СМОТРИТЕ ТАКЖЕ" \&\fBLocale::Po4a::Pod\fR\|(3pm), \fBLocale::Po4a::TransTractor\fR\|(3pm), \fBpo4a\fR\|(7) .SH "АВТОРЫ" .IX Header "АВТОРЫ" .Vb 3 \& Denis Barbier \& Nicolas François \& Martin Quinson (mquinson#debian.org) .Ve .SH "АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИИ" .IX Header "АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИИ" Copyright © 2002\-2008 \s-1SPI,\s0 Inc. .PP Данная программа является свободным программным обеспечением; вы можете распространять и/или изменять её на условиях Универсальной общественной лицензии (\s-1GPL\s0) \s-1GNU\s0 (см. файл \s-1COPYING\s0).