.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" 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 .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Locale::Po4a::Man 3pm" .TH Locale::Po4a::Man 3pm "2018-12-17" "Инструменты 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\-страниц из/в \s-1PO\s0 файлы .SH "ОПИСАНИЕ" .IX Header "ОПИСАНИЕ" Целью проекта po4a (\s-1PO\s0 везде или для всего) является облегчение процесса перевода (и что более важно \- поддержка переводов), использующего инструменты gettext там, где переводимые файлы не выглядят как документация. .PP Locale::Po4a::Man является модулем, предназначенным для помощи в переводе документации в формате nroff (язык man\-страниц) на другие [человеческие] языки. .SH "ПЕРЕВОД С ПОМОЩЬЮ PO4A::MAN" .IX Header "ПЕРЕВОД С ПОМОЩЬЮ PO4A::MAN" Данный модуль делает достаточно трудную жизнь переводчика легче. Для этого, текст предоставляемый переводчику, не является полной копией текста, обнаруженной в man\-странице. Фактически, части, относящиеся к nroff форматированию скрываются, поэтому переводчик не может их испортить. .SS "Перенос текста" .IX Subsection "Перенос текста" 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. .PP В любом случае, изменения будут относиться к положению дополнительных пробелов в переформатированном параграфе и, как мне кажется, это неважно. .SS "Определение шрифтов" .IX Subsection "Определение шрифтов" Первое изменение относится к изменению способа определения шрифтов. В nroff существует несколько способов определения того, каким должен быть шрифт: маленьким, жирным или курсивом. В тексте для перевода существует только один способ, наследуемый из формата \s-1POD \s0(Perl online documentation): .IP "I \*(-- курсив" 4 .IX Item "I курсив" эквивалентен \efItext\efP или \*(L".I text\*(R" .IP "B \*(-- жирный текст" 4 .IX Item "B жирный текст" эквивалентен \efBtext\efP или \*(L".B text\*(R" .IP "R \*(-- roman text" 4 .IX Item "R roman text" эквивалентен \efRtext\efP .IP "CW \*(-- моноширинный" 4 .IX Item "CW моноширинный" эквивалентен \ef(CWtext\efP или \*(L".CW text\*(R" .PP Заметка: Начертание \s-1CW\s0 доступно не для всех groff устройствах. Такое начертание не рекомендуется использовать. Предоставляется только для вашего удобства. .SS "Автоматическая транслитерация символов" .IX Subsection "Автоматическая транслитерация символов" Po4a автоматически транслитерирует некоторые буквы для облегчения перевода или последующего чтения. Ниже приведён список транслитераций: .IP "дефис" 4 .IX Item "дефис" Дефис (\-) и знак минуса (\e\-) в man страницах транслитерируются в простое тире (\-) в \s-1PO\s0 файле. Затем все тире транслитерируются в знак минуса roff (\e\-) при формировании выходного документа. .Sp Переводчики могут принудительно использовать roff дефис '\e[hy]' в своих переводах. .IP "неразрывные пробел" 4 .IX Item "неразрывные пробел" Переводчики могут использовать неразрывные пробелы. Такие неразрывные пробелы (0xA0 в latin1) будут транслитерированы в неразрывные пробелы roff ('\e '). .IP "транслитерация кавычек" 4 .IX Item "транслитерация кавычек" `` и '' будут транслитерированы соответственно в \e*(lq and \e*(rq. .Sp Чтобы избежать подобной транлитерации, переводчики могут вставить roff символ нулевой ширины (т.е., использовать `\e&` или '\e&' соответственно). .SS "Вставка '<' и '>' в перевод" .IX Subsection "Вставка '<' и '>' в перевод" Поскольку эти символы используются для разграничения глав (to delimit parts under font modification), используйте вместо них E и E (так же как в \s-1POD\s0). .SH "OPTIONS ACCEPTED BY THIS MODULE" .IX Header "OPTIONS ACCEPTED BY THIS MODULE" Ниже приведены, специфические для данного модуля, параметры: .IP "\fBdebug\fR" 4 .IX Item "debug" Активация отладки для некоторых внутренних механизмов данного модуля. Используйте исходники для просмотра части, которая может быть отлажена. .IP "\fBverbose\fR" 4 .IX Item "verbose" Увеличение количества выводимой служебной информации. .IP "\fBgroff_code\fR" 4 .IX Item "groff_code" Данный параметр позволяет изменять поведение модуля при встрече секций .de, \&.ie или .if. Он может принимать следующие значения: .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 or .if были предложены для перевода. Необходимо использовать данный параметр если они содержат строки, предназначенные для перевода. В противном случае, более предпочтительной является параметр \fIverbatim\fR. .RE .RS 4 .RE .IP "\fBgenerated\fR" 4 .IX Item "generated" Данный параметр указывает на то, чтобы файл был сгенерирован, и что po4a не должен пытаться определить из какого формата сгенерирована man\-страница. Позволяет использовать po4a для сгенерированных страниц. Данный параметр не имеет аргументов. .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 \s-1DOCUMENT_TITLE 1 \s0\*(L"Month day, year\*(R" \s-1OS \s0\*(L"Section Name\*(R" .PP Следующие параметры позволяют определить поведение новых макросов (определённые с помощью запроса .de), или макросов, которые не поддерживаются po4a. В качестве аргумента подаётся список макросов, разделённый запятыми. Например: .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 Заметка: не проводится никакого тестирования для того, чтобы удостовериться, что каждой команде \fIend\fR соответствует команда \fIbegin\fR; любая завершающая команда отключает режим no_wrap . Если встречается макрос \fIbegin\fR (соответственно \fIend\fR) или макрос \fIend\fR (соответственно \fIbegin\fR), вам необходимо определить существующий \fIend\fR (like fi) или \fIbegin\fR (like nf). Данный макрос (и его аргументы) переводить не нужно. .IP "\fBinline\fR" 4 .IX Item "inline" Данный параметр определяет список разделённых запятыми макросов, которые не должны разделять текущий параграф. Строка для перевода будет содержать \fIfoo <.bar baz qux> quux\fR, где \fIbar\fR является командой, которая должна быть подставлена, а \fIbaz qux\fR ее аргументы. .IP "\fBunknown_macros\fR" 4 .IX Item "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: \fBfailed\fR (the default value), \fBuntranslated\fR, \fBnoarg\fR, \&\fBtranslate_joined\fR, or \fBtranslate_each\fR (see above for an explanation of these values). .SH "СОГЛАШЕНИЕ МЕЖДУ АВТОРАМИ MAN\-СТРАНИЦ И PO4A::MAN" .IX Header "СОГЛАШЕНИЕ МЕЖДУ АВТОРАМИ MAN-СТРАНИЦ И PO4A::MAN" Данный модуль очень ограничен и будет таким всегда, так как он не является интерпретатором nroff. Возможно в будущем можно будет создать настоящий интерпретатор nroff, чтобы предоставить авторам возможность использовать все существующие макросы, но мы не хотим делать это. Это может оказаться слишком сложной задачей и, как мы считаем, в этом нет необходимости. Мы считаем, что если авторы man\-страниц хотят видеть свои продукты переведёнными, то они могут их адаптировать, чтобы облегчить работу переводчикам. .PP Таким образом парсер () встроенный в po4a имеет несколько известных ограничений, которые мы не склонны корректировать, и которые содержат в себе потенциальные опасности, которые вам необходимо учитывать если вы хотите, чтобы переводчики заботились о вашей документации. .SS "Не программируйте на nroff" .IX Subsection "Не программируйте на nroff" nroff это полноценный язык программирования, с возможностью определения макросов, conditionals и так далее. Так как этот парсер не является полнофункциональным интерпретатором nroff, он не сможет обработать страницы, использующие эти возможности (у меня есть около 200 таких страниц). .SS "Используйте простой набор макросов" .IX Subsection "Используйте простой набор макросов" Существуют еще несколько макросов, которые не поддерживаются po4a::man. Только потому что я не смог отыскать документацию по ним. Ниже приведён список неподдерживаемых макросов, используемых на моем компьютере. Обратите внимание, что этот список не является полным, так как программа завершает работу при первой встрече с неподдерживаемым макросом. Если у вас есть информация о каком\-либо из этих макросов, я с удовольствием добавлю поддержку данных макросов. Потому что на моем компьютере около 250 страниц некорректно обрабатывающихся po4a::man. .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 не должен переводиться. А во втором случае \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 (this will require the options \fB\-o groff_code=verbatim\fR and \fB\-o untranslated=IR_untranslated\fR; with this construct, the \fB.if !'po4a'hide'\fR conditional is not strictly needed since po4a will not parse the internal of the macro definition) .PP or using an alias: .als IR_untranslated \s-1IR\s0 .PP .Vb 1 \& .IR_untranslated \e\-q ", " \e\-\e\-quiet .Ve .PP это потребует ключа \fB\-o groff_code=verbatim\fR. .SS "Заключение" .IX Subsection "Заключение" 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 \ec 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. .PP Of course, another possibility is to use another format, more translator friendly (like \s-1POD\s0 using po4a::pod, or one of the \s-1XML\s0 family like \s-1SGML\s0), but thanks to po4a::man it isn't needed anymore. That being said, if the source format of your documentation is \s-1POD,\s0 or \s-1XML,\s0 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 \&\s-1POD\s0 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 \s-1POD\s0 and will be ignored by po4a::man. .PP 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 \*(L"bugs\*(R" ;) If you encounter such case, be sure to report this, along with a fix when possible… .SH "STATUS OF THIS MODULE" .IX Header "STATUS OF THIS MODULE" This module can be used for most of the existing man pages. .PP Some tests are regularly run on Linux boxes: .IP "\(bu" 4 one third of the pages are refused because they were generated from another format supported by po4a (e.g. \s-1POD\s0 or \s-1SGML\s0). .IP "\(bu" 4 10% of the remaining pages are rejected with an error (e.g. a groff macro is not supported). .IP "\(bu" 4 Then, less than 1% of the pages are accepted silently by po4a, but with significant issues (i.e. missing words, or new words inserted) .IP "\(bu" 4 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). .SH "СМОТРИ ТАКЖЕ" .IX Header "СМОТРИ ТАКЖЕ" \&\fILocale::Po4a::Pod\fR\|(3pm), \fILocale::Po4a::TransTractor\fR\|(3pm), \&\fIpo4a\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 This program is free software; you may redistribute it and/or modify it under the terms of \s-1GPL \s0(see the \s-1COPYING\s0 file).