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

NUME
Locale::Po4a::TeX - convertește documente TeX și derivate 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::TeX este un modul care ajută la traducerea documentelor TeX în alte limbi [umane]. De asemenea, poate fi folosit ca bază pentru a construi module pentru documente bazate pe TeX.

Utilizatorii ar trebui să folosească probabil modulul LaTeX, care moștenește din modulul TeX și conține definițiile comenzilor LaTeX comune.

TRADUCEREA CU PO4A::TEX
Acest modul poate fi utilizat direct pentru a gestiona documente TeX generice. Acesta va împărți documentul în blocuri mai mici (paragrafe, blocuri verbatim sau chiar mai mici, cum ar fi titluri sau indexuri).

Există câteva opțiuni (descrise în secțiunea următoare) care pot personaliza acest comportament. Dacă acest lucru nu se potrivește formatului dvs. de document, sunteți încurajat să scrieți propriul dvs. modul derivat din acesta, pentru a descrie detaliile formatului dvs. Pentru descrierea procesului, consultați secțiunea SCRIEREA MODULELOR DERIVATE de mai jos.

Acest modul poate fi, de asemenea, personalizat prin linii care încep cu „% po4a:” în fișierul TeX. Acest proces este descris în secțiunea PERSONALIZARE INLINE.

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.

no_wrap
    Listă separată prin virgule de medii care nu ar trebui să fie redimensionate.

    Rețineți că există o diferență între mediile verbatim și no_wrap. Nu există o analiză a comenzilor și comentariilor în blocurile verbatim.

    Dacă acest mediu nu a fost deja înregistrat, po4a va considera că acest mediu nu primește niciun parametru.

exclude_include
    Lista de fișiere separate prin două puncte (:) care nu ar trebui incluse de „\input” și „\include”.

definitions
    Numele unui fișier care conține definiții pentru po4a, astfel cum sunt definite în secțiunea PERSONALIZARE INLINE. Puteți utiliza această opțiune dacă nu este posibil să introduceți definițiile în documentul tradus.

verbatim
    Listă de medii separate prin virgule care ar trebui să fie luate ca verbatim.

    Dacă acest mediu nu a fost deja înregistrat, po4a va considera că acest mediu nu primește niciun parametru.

Utilizați aceste opțiuni pentru a trece peste comportamentul implicit al comenzilor definite.

PERSONALIZARE INLINE
Modulul TeX poate fi personalizat cu linii care încep cu % po4a:. Aceste linii sunt interpretate ca fiind comenzi pentru analizator. Sunt recunoscute următoarele comenzi:

% po4a: command comanda1 alias comanda2
    Indică faptul că argumentele comenzii comanda1 trebuie să fie tratate ca argumente ale comenzii comanda2.

% po4a: command comanda1 parametrii
    Aceasta descrie în detaliu parametrii comenzii comanda1. Aceste informații vor fi utilizate pentru a verifica numărul de argumente și tipurile acestora.

    Puteți preceda comanda comanda1 cu

    un asterisc (*)
        po4a va extrage această comandă din paragrafe (dacă este situată la începutul sau la sfârșitul unui paragraf). Traducătorii vor trebui apoi să traducă parametrii care sunt marcați ca traductibili.

    un plus (+)
        În ceea ce privește asteriscul, comanda va fi extrasă dacă apare la o extremitate a unui bloc, dar parametrii nu vor fi traduși separat. Traducătorul va trebui să traducă comanda concatenată cu toți parametrii săi. Acest lucru păstrează mai mult context și este util pentru comenzile cu cuvinte mici în parametri, care pot avea mai multe sensuri (și traduceri).

        Notă: În acest caz, nu trebuie să specificați care parametri sunt traductibili, dar po4a trebuie să cunoască tipul și numărul parametrilor.

    un minus (-)
        În acest caz, comanda nu va fi extrasă din niciun bloc. Dar dacă apare singură într-un bloc, atunci numai parametrii marcați ca traductibili vor fi prezentați traducătorului. Acest lucru este util pentru comenzile privind fonturile. În general, aceste comenzi nu ar trebui să fie separate de paragraful lor (pentru a păstra contextul), dar nu există niciun motiv pentru a enerva traducătorul cu ele dacă un întreg șir de caractere este inclus într-o astfel de comandă.

    Argumentul parametrii este un set de [] (pentru a indica un argument opțional) sau {} (pentru a indica un argument obligatoriu). Puteți plasa un semn de subliniere (_) între aceste paranteze pentru a indica faptul că parametrul trebuie să fie tradus. De exemplu:
     % po4a: command *chapter [_]{_}

    Acest lucru indică faptul că comanda „chapter” are doi parametri: unul opțional (titlu scurt) și unul obligatoriu, care trebuie să fie traduși amândoi. Dacă doriți să specificați că comanda „href” are doi parametri obligatorii, că nu doriți să traduceți adresa URL (primul parametru) și că nu doriți ca această comandă să fie separată de paragraful său (care permite traducătorului să mute legătura în frază), puteți utiliza:
     % po4a: command -href {}{_}

    În acest caz, informațiile care indică ce argumente trebuie traduse sunt utilizate numai dacă un paragraf este compus numai din această comandă „href”.

% po4a: environment mediu parametrii
    Aceasta definește parametrii acceptați de mediul mediu și îi specifică pe cei care trebuie traduși. Această informație este utilizată ulterior pentru a verifica numărul de argumente ale comenzii „\begin”. Sintaxa argumentului parametrii este aceeași cu cea descrisă pentru celelalte comenzi. Primul parametru al comenzii „\begin” este numele mediului. Acest parametru nu trebuie să fie specificat în lista de parametri. Iată câteva exemple:
     % po4a: environment multicols {}
     % po4a: environment equation

    În ceea ce privește comenzile, mediu poate fi precedat de un plus (+) pentru a indica faptul că comanda „\begin” trebuie tradusă cu toate argumentele sale.

% po4a: separator mediu "expresie-regulată"
    Indică faptul că un mediu ar trebui să fie divizat în conformitate cu expresia regulată dată.

    Expresia regulată este delimitată prin ghilimele. Ea nu trebuie să creeze nicio referință înapoi. Ar trebui să utilizați (?:) dacă aveți nevoie de un grup. De asemenea, poate avea nevoie de unele eludări.

    De exemplu, modulul LaTeX utilizează expresia regulată „(?:&|\\\\)” pentru a traduce separat fiecare celulă a unui tabel (liniile sunt separate prin „\\”, iar celulele prin „&”).

    Noțiunea de mediu este extinsă la tipul afișat în fișierul PO. Aceasta poate fi utilizată pentru a diviza pe „\\\\” în primul argument obligatoriu al comenzii title. În acest caz, mediul este title{#1}.

% po4a: verbatim environment mediu
    Indică faptul că mediu este un mediu verbatim. Comentariile și comenzile vor fi ignorate în acest mediu.

    Dacă acest mediu nu a fost deja înregistrat, po4a va considera că acest mediu nu primește niciun parametru.

SCRIEREA MODULELOR DERIVATE

pre_trans
post_trans
add_comment
    Adaugă un șir de caractere ca un comentariu care să fie adăugat în jurul următorului element tradus. Acest lucru este util mai ales pentru modulul texinfo, deoarece comentariile sunt gestionate automat în TeX.

translate
    Modul de învăluire în jurul traducerii Transtractor, cu filtre de pre și post-procesare.

    Comentariile unui paragraf sunt inserate ca un comentariu PO pentru primul șir tradus din acest paragraf.

get_leading_command($buffer)
    Această funcție returnează:

    Un nume de comandă
        Dacă nu se găsește nicio comandă la începutul tamponului dat, acest șir va fi gol. Sunt luate în considerare numai comenzile care pot fi separate. Seria %separated_command conține lista acestor comenzi.

    O variantă
        Aceasta indică dacă se utilizează o variantă. De exemplu, un asterisc (*) poate fi adăugat la sfârșitul secțiunilor de comandă pentru a specifica faptul că acestea nu trebuie numerotate. În acest caz, acest câmp va conține „*”. Dacă nu există nicio variantă, câmpul este un șir gol.

    O matrice de cupluri (tip de argument, argument)
        Tipul de argument poate fi „{” (pentru argumente obligatorii) sau „[” (pentru argumente opționale).

    Tamponul rămas
        Restul tamponului după eliminarea acestei comenzi principale și a argumentelor sale. Dacă nu se găsește nicio comandă, tamponul original nu este atins și este returnat în acest câmp.

get_trailing_command($buffer)
    La fel ca get_leading_command, dar pentru comenzi la sfârșitul unui tampon.

translate_buffer
    Traduce recursiv un tampon prin separarea comenzilor anterioare și ulterioare (cele care trebuie traduse separat) din tampon.

    Dacă o funcție este definită în %translate_buffer_env pentru mediul curent, această funcție va fi utilizată pentru a traduce tamponul în loc de translate_buffer().

read
    Supraîncarcă funcția read() a Transtractor.

read_file
    Citește recursiv un fișier, adăugând fișierele incluse care nu sunt listate în matricea @exclude_include. Fișierele incluse sunt căutate folosind comanda kpsewhich din biblioteca Kpathsea.

    Cu excepția părții de includere a fișierului, este o simplă tăiere și lipire (o copie) din citirea lui Transtractor.

parse_definition_file
    Subrutină pentru analizarea unui fișier cu directive po4a (definiții pentru comenzi noi).

parse_definition_line
    Analizează o linie de definiție de forma „% po4a: ”.

    Pentru mai multe detalii, consultați secțiunea PERSONALIZARE INLINE.

is_closed
parse
docheader

FUNCȚII INTERNE utilizate pentru scrierea analizatorilor derivativi
Funcțiile de comandă și de mediu primesc următoarele argumente (în plus față de obiectul $self):

Un nume de comandă
O variantă
O matrice de cupluri (tip, argument)
Mediul actual

Primele 3 argumente sunt extrase de get_leading_command sau get_trailing_command.

Funcțiile de comandă și mediu returnează traducerea comenzii cu argumentele sale și un nou mediu.

Funcțiile de mediu sunt apelate atunci când este găsită o comandă „\begin”. Acestea sunt apelate cu comanda „\begin” și argumentele sale.

Modulul TeX propune doar o funcție de comandă și o funcție de mediu: generic_command și generic_environment.

generic_command utilizează informațiile specificate de către register_generic_command sau prin adăugarea definiției la fișierul TeX:
 % po4a: command comanda1 parametri

generic_environment utilizează informațiile specificate de către register_generic_environment sau prin adăugarea definiției la fișierul TeX:
 % po4a: environment mediu parametri

Ambele funcții vor traduce numai parametrii care au fost specificați ca fiind traductibili (cu un „_”). generic_environment va adăuga numele mediului la stiva de medii, iar generic_command va adăuga numele comenzii urmat de un identificator al parametrului (cum ar fi {#7} sau [#2]).

STAREA ACESTUI MODUL
Acest modul necesită mai multe teste.

Acesta a fost testat pe o carte și cu documentația Python.

LISTA CU LUCRURI DE FĂCUT

Detectarea automată a comenzilor noi
    Modulul TeX ar putea analiza argumentele noii comenzi și ar putea încerca să ghicească numărul de argumente, tipul acestora și dacă ar trebui sau nu să fie traduse.

Traducerea separatorului de mediu
    Atunci când \item este utilizat ca separator de mediu, argumentul „item” este atașat la următorul șir de caractere.

Unele comenzi ar trebui adăugate la stiva de mediu
    Aceste comenzi trebuie să fie specificate prin cupluri. Aceasta poate fi utilizată pentru a specifica comenzile care încep sau încheie un mediu verbatim.

Altele
    Diverse alte puncte sunt etichetate TODO în codul-sursă.

ERORI CUNOSCUTE
Diverse puncte sunt etichetate FIXME în codul-sursă.

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

AUTORI
 Nicolas François <nicolas.francois@centraliens.net>

DREPTURI DE AUTOR și LICENȚĂ
Drepturi de autor © 2004, 2005 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.

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).