LOCALE::PO4A::MAN.3PM(1)

NUME
Locale::Po4a::Man - convertește pagini de manual din/în fișiere PO

DESCRIERE
Scopul proiectului po4a (PO pentru orice) este de a ușura traducerile (și mai interesant, întreținerea traducerilor) folosind instrumente gettext în domenii în care nu erau așteptate, cum ar fi documentația.

Locale::Po4a::Man este un modul care ajută la traducerea documentației în format nroff (limba paginilor de manual) în alte limbi [umane].

TRADUCEREA CU PO4A::MAN
Acest modul încearcă din răsputeri să facă viața traducătorului mai ușoară. Pentru aceasta, textul prezentat traducătorilor nu este o copie literală a textului găsit în pagina de manual. Într-adevăr, părțile mai grosolane ale formatului nroff sunt ascunse, astfel încât traducătorii să nu se poată încurca cu ele.

  Încadrarea textului
Paragrafele neindentate sunt în mod automat re-încadrate pentru traducător. Acest lucru poate duce la unele diferențe minore în rezultatul generat, deoarece regulile de reformulare utilizate de groff nu sunt foarte clare. De exemplu, două spații după o paranteză sunt uneori păstrate.

Oricum, diferența va fi doar în ceea ce privește poziția spațiilor suplimentare în paragraful încadrat, și cred că merită.

  Specificarea fontului
Prima modificare se referă la specificațiile de schimbare a fontului. În nroff, există mai multe modalități de a specifica dacă un anumit cuvânt ar trebui să fie scris cu litere mici, aldine sau cursive. În textul de tradus, există o singură modalitate, împrumutată din formatul POD (documentația în linie Perl):

I<text> -- text cursiv
    echivalent cu \fItext\fP sau ".I text"

B<text> -- text aldin
    echivalent cu \fBtext\fP sau ".B text"

R<text> -- text normal (roman)
    echivalent cu \fRtext\fP

CW<text> -- text cu lățime constantă
    echivalent cu \f(CWtext\fP sau ".CW text"

Observație: Aspectul CW al fontului nu este disponibil pentru toate dispozitivele Groff. Nu este recomandată utilizarea acestuia. Acesta este furnizat pentru confortul dumneavoastră.

  Transliterarea automată a caracterelor
Po4a translitera automat unele caractere pentru a facilita traducerea sau revizuirea traducerii. Aici este lista transliterărilor:

cratime
    Cratimele (-) și semnele minus (\-) din paginile de manual sunt toate transliterate ca liniuțe simple (-) în fișierul PO. Apoi, toate liniuțele sunt transliterate în semne minus roff (\-) atunci când traducerea este inserată în documentul de ieșire.

    Traducătorii pot forța o cratimă prin utilizarea glifului roff „\[hy]” în traducerile lor.

spații rigide
    Traducătorii pot utiliza spații fără pauză în traducerile lor. Aceste spații rigide (0xA0 în latin1) vor fi transliterate într-un spațiu fără pauză roff ('\ ').

transliterații de ghilimele
    Ghilimelele `` și '' sunt transliterate în \*(lq și respectiv \*(rq.

    Pentru a evita aceste transliterări, traducătorii pot introduce un caracter roff de lățime zero (de exemplu, folosind „\&” sau, respectiv, „\&”).

  Introducerea „<” și „>” în traduceri
Deoarece aceste caractere sunt utilizate pentru a delimita părțile în care se modifică fontul, nu le puteți utiliza textual. Utilizați în schimb E<lt> și E<gt> (ca în POD, încă o dată).

OPȚIUNI ACCEPTATE DE ACEST MODUL
Acestea sunt opțiunile particulare ale acestui modul:

debug
    Activează depanarea pentru unele mecanisme interne ale acestui modul. Utilizați sursa pentru a vedea care părți pot fi depanate.

verbose
    Mărește nivelul de detaliere al ieșirii.

groff_code
    Această opțiune controlează comportamentul modulului atunci când întâlnește o secțiune .de, .ie sau .if. Aceasta poate lua următoarele valori:

    fail
        Aceasta este valoarea implicită. Modulul va eșua atunci când este întâlnită o secțiune .de, .ie sau .if.

    verbatim
        Indică faptul că secțiunile .de, .ie sau .if trebuie copiate ca atare din original în documentul tradus.

    translate
        Indică faptul că secțiunile .de, .ie sau .if vor fi propuse pentru traducere. Ar trebui să utilizați această opțiune numai dacă un șir traductibil este conținut în una dintre aceste secțiuni. În caz contrar, ar trebui preferată opțiunea verbatim.

generated
    Această opțiune specifică faptul că fișierul a fost generat și că po4a nu trebuie să încerce să detecteze dacă paginile de manual au fost generate din alt format. Această opțiune este obligatorie pentru a utiliza po4a pe paginile de manual generate. Rețineți că traducerea paginilor generate în locul celor sursă este adesea mai fragilă și, prin urmare, o idee proastă.

mdoc
    Această opțiune este utilă numai pentru paginile mdoc.

    Aceasta selectează un suport mai strict al formatului mdoc, spunându-i lui po4a să nu traducă secțiunea „NAME”. Paginile mdoc a căror secțiune „NAME” este tradusă nu vor genera niciun antet sau notă de subsol.

    Conform paginii groff_mdoc, secțiunile NAME, SYNOPSIS și DESCRIPTION sunt obligatorii. Nu există probleme cunoscute cu secțiunile SYNOPSIS sau DESCRIPTION traduse, dar puteți specifica aceste secțiuni și în acest mod:
     -o mdoc=NAME,SYNOPSIS,DESCRIPTION

    Această problemă mdoc poate fi rezolvată și cu un addendum ca acesta:
     PO4A-HEADER:mode=before;position=^.Dd
     .TH DOCUMENT_TITLE 1 „Luna ziua, anul” OS „Numele secțiunii”

Următoarele opțiuni specifică comportamentul unei macrodefiniții definite de utilizator (cu o cerere .de) sau al unei macrodefiniții clasice care nu este acceptată de po4a. Acestea iau ca argument o listă de nume de macrodefiniții separate prin virgulă. De exemplu:

 -o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX

Notă: dacă o macrodefiniție nu este acceptată de po4a și dacă considerați că este o macrodefiniție roff standard, trebuie să o trimiteți echipei de dezvoltare po4a.

untranslated
    untranslated indică faptul că această macrodefiniție (sau argumentele sale) nu trebuie să fie tradusă.

noarg
    noarg este ca untranslated, cu excepția faptului că po4a va verifica dacă nu este adăugat niciun argument la această macrodefiniție.

translate_joined
    translate_joined indică faptul că po4a trebuie să propună traducerea argumentelor macrodefiniției.

translate_each
    Cu translate_each, argumentele vor fi, de asemenea, propuse pentru traducere, doar că fiecare va fi tradus separat.

no_wrap
    Această opțiune primește ca argument o listă de cupluri separate prin virgulă begin:end, unde begin și end sunt comenzi care delimitează începutul și sfârșitul unei secțiuni care nu ar trebui să fie reîncadrată.

    Notă: nu se efectuează niciun test pentru a se asigura că o comandă end corespunde comenzii sale begin; orice comandă de sfârșit oprește modul no_wrap. Dacă aveți o macrocomandă begin (respectiv end) care nu are end (respectiv begin), puteți specifica o macrocomandă end ( precum fi) sau begin (precum nf) existentă ca o contrapartidă. Aceste macrocomenzi (și argumentele lor) nu vor fi traduse.

inline
    Această opțiune specifică o listă de macro-uri separate prin virgulă care nu trebuie să despartă paragraful curent. Șirul de caractere de tradus va conține atunci foo <.bar baz qux> quux, unde bar este comanda care trebuie introdusă, iar baz qux argumentele sale.

unknown_macros
    Această opțiune indică modul în care po4a ar trebui să se comporte atunci când este găsită o macrocomandă necunoscută. În mod implicit, po4a eșuează cu un avertisment. Aceasta poate lua următoarele valori: failed (valoarea implicită), untranslated, noarg, translate_joined sau translate_each ( a se vedea mai sus pentru o explicație a acestor valori).

CREAREA DE PAGINI DE MANUAL CONFORME CU PO4A::MAN
Acest modul este încă foarte limitat, și va fi întotdeauna, deoarece nu este un interpret nroff real. Ar fi posibil să realizăm un interpret nroff real, pentru a permite autorilor să utilizeze toate macrocomenzile existente sau chiar să definească altele noi în paginile lor, dar nu am dorit acest lucru. Ar fi prea dificil și am considerat că nu este necesar. Ne gândim că, dacă autorii paginilor de manual doresc ca produsele lor să fie traduse, ar trebui să se adapteze pentru a ușura munca traducătorilor.

Așadar, analizatorul man implementat în po4a are unele limitări cunoscute pe care nu prea suntem înclinați să le corectăm și care vor constitui unele capcane pe care va trebui să le evitați dacă doriți ca traducătorii să aibă grijă de documentația dumneavoastră.

  Nu programați în nroff
nroff este un limbaj de programare complet, cu definiție macro, condiționale și așa mai departe. Deoarece acest analizator nu este un interpret nroff complet, el va eșua pe paginile care utilizează aceste facilități (există aproximativ 200 de astfel de pagini pe calculatorul meu).

  Utilizați un set de macrocomenzi simplu
Există încă unele macrocomenzi care nu sunt acceptate de po4a::man. Acest lucru se datorează doar faptului că nu am reușit să găsesc nicio documentație despre acestea. Iată lista macrocomenzilor neacceptate utilizate pe calculatorul meu. Rețineți că această listă nu este exhaustivă, deoarece programul eșuează la prima macrocomandă neacceptată întâlnită. Dacă aveți informații despre unele dintre aceste macrocomenzi, voi adăuga cu plăcere suport pentru acestea. Din cauza acestor macrocomenzi, aproximativ 250 de pagini din calculatorul meu sunt inaccesibile pentru 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

  Ascunderea textului de po4a
Uneori, autorul știe că unele părți nu sunt traductibile și nu ar trebui extrase de po4a. De exemplu, o opțiune poate accepta un argument other, iar other poate apărea și ca ultimul element al unei liste. În primul caz, other nu ar trebui să poată fi tradus. Iar în al doilea caz, other ar trebui să fie tradus.

În acest caz, autorul poate evita po4a pentru a extrage unele șiruri de caractere, folosind unele construcții groff speciale:

 .if !'po4a'hide' .B other

(aceasta va necesita opțiunea -o groff_code=verbatim)

De asemenea, poate fi definit o nouă macrocomandă pentru a automatiza acest lucru:
 .de IR_untranslated
 . IR \\$@
 ..

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

(aceasta va necesita opțiunile -o groff_code=verbatim și -o untranslated=IR_untranslated; cu această construcție, condiționalul .if !'po4a'hide' nu este strict necesar deoarece po4a nu va analiza interiorul definiției macro)

sau folosind un alias:
 .als IR_untranslated IR

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

Acesta va necesita opțiunea -o untranslated=als,IR_untranslated.

  Concluzie
Pentru a rezuma această secțiune, păstrați simplitatea și nu încercați să fiți inteligenți atunci când vă scrieți paginile de manual. O mulțime de lucruri sunt posibile în nroff și nu sunt acceptate de acest analizator. De exemplu, nu încercați să vă jucați cu \c pentru a întrerupe procesarea textului (așa cum fac 40 de pagini de pe calculatorul meu). Sau, asigurați-vă că puneți argumentele macro pe aceeași linie cu macroul în sine. Știu că este valabil în nroff, dar ar complica prea mult analizatorul pentru a fi gestionat.

Desigur, o altă posibilitate este de a utiliza un alt format, mai ușor de tradus (cum ar fi POD folosind po4a::pod, sau unul din familia XML cum ar fi SGML), dar datorită po4a::man nu mai este necesar. Acestea fiind spuse, dacă formatul sursă al documentației dvs. este POD sau XML, poate fi inteligent să traduceți formatul sursă și nu acest format generat. În majoritatea cazurilor, po4a::man va detecta paginile generate și va emite un avertisment. Acesta va refuza chiar să proceseze paginile generate de POD, deoarece aceste pagini sunt gestionate perfect de po4a::pod și deoarece omologul lor nroff definește o mulțime de macrocomenzi noi pentru care nu am vrut să scriu suport. Pe calculatorul meu, 1432 din cele 4323 de pagini sunt generate de POD și vor fi ignorate de po4a::man.

În majoritatea cazurilor, po4a::man va detecta problema și va refuza să proceseze pagina, emițând un mesaj adaptat. În unele cazuri rare, programul se va finaliza fără avertisment, dar rezultatul va fi greșit. Astfel de cazuri sunt numite „erori” ;) Dacă întâlniți un astfel de caz, asigurați-vă că raportați acest lucru, împreună cu o remediere atunci când este posibil…

STAREA ACESTUI MODUL
Acest modul poate fi utilizat pentru majoritatea paginilor de manual existente.

Unele teste sunt efectuate în mod regulat pe cutii Linux:

•   o treime din pagini sunt refuzate deoarece au fost generate dintr-un alt format acceptat de po4a (de exemplu, POD sau SGML).

•   10% din paginile rămase sunt respinse cu o eroare (de exemplu, macrocomanda groff nu este acceptată).

•   Apoi, mai puțin de 1% din pagini sunt acceptate silențios de po4a, dar cu probleme semnificative (de exemplu, cuvinte lipsă sau cuvinte noi introduse)

•   Celelalte pagini sunt, de obicei, tratate fără diferențe mai importante decât diferențele de spațiere sau de linie (probleme de font în mai puțin de 10% din paginile procesate).

CONSULTAȚI ȘI
Locale::Po4a::Pod(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)

AUTORI
 Denis Barbier <barbier@linuxfr.org>
 Nicolas François <nicolas.francois@centraliens.net>
 Martin Quinson (mquinson#debian.org)

DREPTURI DE AUTOR și LICENȚĂ
Drepturi de autor © 2002-2008 SPI, Inc.

Acest program este software liber; îl puteți redistribui și/sau modifica în conformitate cu termenii GPL v2.0 sau o versiune ulterioară (consultați fișierul COPYING).