ИМЕ

Locale::Po4a::Man - двосмерна конверзија страна упутства и PO фајлова

ОПИС

Циљ po4a (PO for anything – PO за било шта) пројекта је да поједностави превођење (и што је још интересантније, одржавање превода) употребом gettext алата на деловима на којима се не очекује њихова употреба, као што је документација.

Locale::Po4a::Man је модул који помаже превођење документације у nroff формату (језик страница упутства) на друге [људске] језике.

ПРЕВОЂЕЊЕ ПОМОЋУ PO4A::MAN

Овај модул се заиста својски труди да олакша живот преводиоцу. Текст који се представља преводиоцима није дословна копија текста који се налази у man страни. Наравно, грубљи делови nroff формата су скривени, тако да преводиоци не могу да се петљају са њима.

Обмотавање текста

Неувучени пасуси се за преводиоца аутоматски поново обавијају. То може довести до ситуације да постоје неке минималне разлике у генерисаном излазу, пошто правила поновног обавијања која користи groff нису баш најјаснија. На пример, два размака након заграда понекад остају очувана.

У сваком случају, разлика ће бити једино у позицији екстра размака у обавијеном пасусу и ја мислим да је вредна.

Спецификација фонта

Прва измена је у вези спецификација за промену фонта. У nroff, постоји неколико начина да се наведе да ли одређена реч треба да се испише малим словима, подебљано или курзивом. У тексту који се преводи, постоји само један начин, позајмљен из POD (Perl online documentation) формата:

I<текст> -- курзивни текст: еквивалентно са \fIтекст\fP или ".I текст"
B<текст> -- подебљани текст: еквивалентно са \fBтекст\fP или ".B текст"
R<текст> -- латинични текст: еквивалентно са \fRтекст\fP
CW<текст> -- текст са карактерима константне ширине: еквивалентно са \f(CWтекст\fP или ".CW текст"

Опаска: CW писмо није доступно за све groff уређаје. Његова употреба се не препоручује. Понуђено је да би вама било једноставно.

Аутоматско пресловљавање карактера

Програм po4a аутоматски пресловљава неке карактере како би се олакшало превођење или лекторисање превода. Ево листе пресловљавања:

цртице на крају реда: У PO фајлу се цртице на крају реда (-) и минус знаци (\-) у man страницама све пресловљавају у просте цртице (-). Затим се све црте пресловљавају у roff минус знаке (\-) када се превод умеће у излазни документ.
Преводиоци могу да форсирају цртице на крају реда употребом roff глифа ’\[hy]’ у својим преводима.
размаци на којима нема прелома реда: Преводиоци у својим преводима могу да користе непреламајуће размаке. Ови непреламајући размаци (0xA0 у latin1 кодној страни) ће да се преслове у roff непреламајући размак (’\ ’).
пресловљавања навода: `` и '' се пресловљавају у \*(lq и \*(rq респективно.
Ако желе да спрече ова пресловљавања, преводиоци могу да уметну roff карактер нулте ширине (нпр. употребом `\&` или '\&' респективно).

Стављање ’<’ и ’>’ и преводе

Пошто се ови карактери користе за одвајање делова под изменом фонта, не можете да их користите дословно. Употребите уместо њих E<lt> и E<gt> (као у POD, још једном).

ОПЦИЈЕ КОЈЕ ПРИХВАТА ОВАЈ МОДУЛ

Ово су опције везане само за овај модул:

debug: Активира дибаговање за неке интерне механизме овог модула. Погледајте изворни код да сазнате за који делове може да се користи дибаг.
verbose: Повећава количину информација.
groff_code: Ова опција контролише понашање модула када наиђе на .de, .ie или .if одељке. Може да има следеће вредности:

fail: Ово је подразумевана вредност. Модул ће прекинути са извршавањем када се наиђе на .de, .ie или .if одељак.
verbatim: Назначава да .de, .ie или .if одељци морају да се копирају из оригинала у преведени документ онакви какви су.
translate: Назначава да ће .de, .ie или .if одељци да се предложе за превођење. Ову опцију би требало да користите само ако се стринг за превођење налази у једном од ових одељака. У супротном, бољи избор је verbatim.

generated

Ова опција наводи да је фајл генерисан, и да програм po4a не би требало да покуша са откривањем да ли су man стране генерисане из неког другог формата. Ова опција је обавезна код употребе po4a над генерисаним man страницама. Имајте на уму да превођење генерисаних страница уместо извора често доводи до грешака, па није добра идеја.

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: Ова опција као аргумент узима листу парова почетак:крај раздвојених зарезима, где су почетак и крај команде које ограђују почетак и крај одељка који не би требало да се поново обавија.
Напомена: не ради се никакав тест да се осигура подударање команде крај са својом командом почетак; било која команда уређивања зауставља no_wrap режим. Ако имате почетак (и одговарајући крај) макро који нема крај (и одговарајући почетак), можете да наведете неки постојећи крај (као fi) или почетак (као nf) као његов пар. Ови макрои (и њихови аргументи) неће бити превођени.
inline: Ова опција наводи листу макроа раздвојених зарезима који не смеју да преломе текући пасус. Тада ће стринг који треба да се преведе садржати foo <.bar baz qux> quux, где је bar команда која би требало да се налази унутар текста, а baz qux су њени аргументи.
unknown_macros: Ова опција одређује како би програм po4a требало да се понаша када се наиђе на непознат макро. Подразумева се да програм po4a прекине извршавање са упозорењем. Може да има следеће вредности: failed (подразумевана вредност), untranslated, noarg, translate_joined, или translate_each (погледајте изнад за објашњење ових вредности).

ПИСАЊЕ MAN СТРАНИЦА САГЛАСНИХ СА PO4A::MAN

Овај модул је и даље веома ограничен, и увек ће бити, јер он није прави nroff интерпретер. Било би могуће да се направи прави nroff интерпретер, чиме би аутори могли да користе све постојеће макрое, или да чак у својим страницама дефинишу и нове, али нисмо хтели то да урадимо. Било би сувише тешко, и мислили смо да није неопходно. Сматрамо да ако аутори man страница желе да виде своја дела преведена, морали би мало да се прилагоде како би олакшали посао преводиоцима.

Дакле, man парсер имплементиран у програм po4a има нека позната ограничења која баш и не желимо да исправимо, и која ће проузроковати неке проблеме које ћете морати да избегнете ако желите да видите преводиоце како се старају о вашој документацији.

Немојте да програмирате у nroff

nroff је комплетан програмски језик, са дефиницијом макроа, кондиционалима и тако даље. Пошто овај парсер није комплетан 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 би требало да се преведе.

Користећи неке специјалне groff конструкције, аутор у том случају може да постићи да po4a не издвоји неке стрингове:

.if !'po4a'hide' .B other

(за ово је неопходна опција -o groff_code=verbatim)

Ово може да се аутоматизује дефинисањем новог макроа:
.de IR_untranslated
. IR \\$@
..

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

(за ово су неопходне опције -o groff_code=verbatim и -o untranslated=IR_untranslated; уз ову конструкцију, кондиционал .if !'po4a'hide' није стриктно неопходан јер програм po4a неће парсирати интерну дефиницију макроа)

или коришћењем алијаса:
.als IR_untranslated IR

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

За ово је неопходна опција -o untranslated=als,IR_untranslated.

Закључак

Да укратко поновимо поенту овог одељка, нека буде једноставно, и немојте да се правите паметни када пишете своје man странице. У nroff је могуће урадити много ствари које овај парсер не подржава. На пример, не покушавајте да се петљате са \c како бисте прекинули процесирање текста (као што 40 страница на мојој машини ради). Или, будите сигурни да сте ставили аргументе макроа у исту линију у којој је и сам макро. Знам да је то исправно у nroff, али би сувише искомпликовало парсер ако би се применило.

Наравно, друга могућност је да користите неки други формат, погоднији за преводиоца (као што је POD који користи po4a::pod, или неки из XML породице као што је SGML), мада захваљујући po4a::man то више није неопходно. Дакле, ако је изворни формат ваше документације POD, или XML, паметније би било да преведете изворни формат, а не овај генерисани. po4a::man ће у већини случајева моћи да детектује генерисане странице и издаће упозорење. Чак ће и одбити да обради POD генерисане стране, јер po4a::pod савршено ради са њима, а и због тога што њихови одговарајући nroff еквиваленти дефинишу пуно нових макроа, нисам желео да напишем подршку за то. На мојој машини, 1432 од 4323 странице су генерисане из POD и po4a::man ће да их игнорише.

У већини случајева, po4a::man ће открити проблем и одбиће да обради страницу, издајући прилагођену поруку. У неким ретким случајевима, програм ће да се изврши без упозорења али излаз неће бити исправан. Такви случајеви се зову „багови” ;) Ако наиђете на такав случај, обавезно га пријавите, ако је могуће заједно са исправком…

СТАТУС ОВОГ МОДУЛА

Овај модул може да се користи за већину постојећих man страница.

Неки тестови се редовно врше на Linux машинама:

•: одбија се обрада једне трећине страница јер су генерисане из другог формата који програм po4a подржава (нпр. POD или SGML).
•: 10% осталих страница се не обрађује услед неке грешке (нпр. groff макро који није подржан).
•: Затим, програм po4a без обавештења прихвата мање од 1% страница, али са озбиљним проблемима (нпр. речи које недостају, или уметнуте нове речи)
•: Остале странице се обично обрађују без неких значајнијих разлика, осим на пример разлике у размацима или поново обавијене линије (проблеми са фонтом у мање од 10% обрађених страница).

ПОГЛЕДАЈТЕ ТАКОЂЕ

Locale::Po4a::Pod(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)

АУТОРИ

Дени Барбије <barbier@linuxfr.org>
Никола Франсоа <nicolas.francois@centraliens.net>
Мартин Квинсон (mquinson#debian.org)

ПРАВА УМНОЖАВАЊА И ЛИЦЕНЦА

Овај програм је слободан софтвер; можете да га редистрибуирате и/или мењате под условима GPL v2.0 или новије (погледајте фајл COPYING).