
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 NAAM

Locale::Po4a::TransTractor - generieke vertaler en extractor.

=head1 BESCHRIJVING

Het doel van het project po4a (PO voor alles) is om de vertaalwerkzaamheden
(en interessanter nog, het onderhoud van vertalingen) te vergemakkelijken
met behulp van gettext-hulpmiddelen in domeinen waarin deze niet meteen
verwacht worden, zoals documentatie.

Deze klasse is de voorouder van alle po4a-ontleders die gebruikt worden om
een document te ontleden, vertaalbare tekstfragmenten op te zoeken, deze
naar een PO-bestand te extraheren en deze te vervangen door hun vertaling in
het uitvoerdocument.

Meer formeel neemt ze de volgende argumenten als invoer:

=over 2

=item -

een te vertalen document;

=item -

een PO-bestand dat de te gebruiken vertalingen bevat.

=back

Als uitvoer produceert ze:

=over 2

=item -

nog een PO-bestand als het resultaat van de extractie van vertaalbare
tekstfragmenten uit het invoerdocument;

=item -

een vertaald document met dezelfde structuur als het invoerdocument, maar
waarin alle vertaalbare tekstfragmenten vervangen werden door de vertalingen
die in het als invoer verstrekte PO-bestand aangetroffen werden.

=back

Hier volgt een grafische voorstelling:

   Input document --\                             /---> Output document
                     \                           /       (translated)
                      +-> parse() function -----+
                     /                           \
   Input PO --------/                             \---> Output PO
                                                         (extracted)

=head1 FUNCTIES DIE UW ONTLEDERER MOET OVERSTIJGEN

=over 4

=item parse()

Dit is waar al het werk gebeurt: het ontleden van invoerdocumenten, het
genereren van uitvoer en het extraheren van de vertaalbare
tekstfragmenten. Dit is redelijk eenvoudig met de hieronder in de sectie
B<INTERNE FUNCTIES> verstrekte functies. Bekijk ook het B<OVERZICHT> met
daarin een voorbeeld.

Deze functie wordt aangeroepen door de functie process() hieronder, maar
indien u ervoor kiest de functie new() te gebruiken en handmatig inhoud toe
te voegen aan uw document, zult u deze functie zelf moeten aanroepen.

=item docheader()

Deze functie geeft de header terug die we aan het geproduceerde document
moeten toevoegen, passend aangehaald om in de doeltaal als commentaar te
gelden. Raadpleeg de sectie B<Ontwikkelaars onderrichten over vertalingen>
van L<po4a(7)|po4a.7> over waarvoor dit goed is.

=back

=head1 OVERZICHT

Inhet volgende voorbeeld wordt een lijst alinea's die beginnen met "<p>",
ontleed. Gemakshalve gaan we ervan uit dat het document goed is opgemaakt,
d.w.z. dat '<p>'-tags de enige aanwezige tags zijn, en dat deze tag helemaal
aan het begin van elke alinea staat.

 sub parse {
   my $self = shift;

   PARAGRAPH: while (1) {
       my ($paragraph,$pararef)=("","");
       my $first=1;
       my ($line,$lref)=$self->shiftline();
       while (defined($line)) {
           if ($line =~ m/<p>/ && !$first--; ) {
               # Not the first time we see <p>.
               # Reput the current line in input,
               #  and put the built paragraph to output
               $self->unshiftline($line,$lref);

               # Now that the document is formed, translate it:
               #   - Remove the leading tag
               $paragraph =~ s/^<p>//s;

               #   - push to output the leading tag (untranslated) and the
               #     rest of the paragraph (translated)
               $self->pushline(  "<p>"
                               . $self->translate($paragraph,$pararef)
                               );

               next PARAGRAPH;
           } else {
               # Append to the paragraph
               $paragraph .= $line;
               $pararef = $lref unless(length($pararef));
           }

           # Reinit the loop
           ($line,$lref)=$self->shiftline();
       }
       # Did not get a defined line? End of input file.
       return;
   }
 }

Nadat u de ontleedfunctie geïmplementeerd heeft, kunt u uw documentklasse
gebruiken met behulp van de openbare interface die in de volgende sectie
voorgesteld wordt.

=head1 OPENBARE INTERFACE voor scripts die uw ontleder gebruiken

=head2 Constructor

=over 4

=item process(%)

Deze functie kan in één aanroep alles doen wat u moet doen met een
po4a-document. De argumenten moeten als een hash worden verpakt. ACTIES:

=over 3

=item a.

Leest alle in po_in_name vermelde PO-bestanden

=item b.

Leest alle in file_in_name vermelde documenten

=item c.

Ontleedt het document

=item d.

Leest alle opgegeven addenda en past deze toe

=item e.

Schrijft het vertaalde document naar file_out_name (indien gespecificeerd)

=item f.

Schrijft het geëxtraheerd PO-bestand naar po_out_name (indien
gespecificeerd)

=back

ARGUMENTEN, behalve die welke door new() geaccepteerd worden (met verwacht
type):

=over 4

=item file_in_name (@)

Lijst met namen van bestanden waaruit we het invoerdocument moeten lezen.

=item file_in_charset ($)

In het invoerdocument gebruikte tekenset (Indien dit niet gespecificeerd
werd, zal UTF-8 gebruikt worden).

=item file_out_name ($)

Naam van het bestand waarnaar we het uitvoerdocument moeten schrijven.

=item file_out_charset ($)

In het uitvoerdocument gebruikte tekenset (Indien dit niet gespecificeerd
werd, zal UTF-8 gebruikt worden).

=item po_in_name (@)

Namenlijst van de bestanden waaruit we de invoerPO-bestanden moeten lezen,
welke de vertaling bevatten die gebruikt zal worden om het document te
vertalen.

=item po_out_name ($)

Naam van het bestand waarin we het uitvoerPO-bestand moeten schrijven, dat
de tekstfragmenten bevat die uit het invoerdocument geëxtraheerd werden.

=item addendum (@)

Namenlijst van de bestanden waaruit we de addenda moeten inlezen.

=item addendum_charset ($)

Tekenset voor de addenda.

=back

=item new(%)

Een nieuw po4a document creëren. Mogelijke opties (in de hash die als
parameter meegegeven wordt):

=over 4

=item verbose ($)

Stelt in hoeveel informatie gegeven wordt.

=item debug ($)

Stelt het debuggen in.

=item wrapcol ($)

De kolom waar de regelafbreking moet gebeuren in het uitvoerdocument
(standaard: 76).

Een negatieve waarde betekent dat er helemaal geen regelafbreking moet
gebeuren.

=back

Het accepteert ook de volgende opties voor onderliggende Po-bestanden:
B<porefs>, B<copyright-holder>, B<msgid-bugs-address>, B<package-name>,
B<package-version>, B<wrap-po>.

=back

=head2 Documentbestanden behandelen

=over 4

=item read($$$)

Gegevens van nog een ander invoerdocument toevoegen aan het einde van de
bestaande array C<< @{$self->{TT}{doc_in}} >>.

This function takes two mandatory arguments and an optional one.
 * The filename to read on disk;
 * The name to use as filename when building the reference in the PO file;
 * The charset to use to read that file (UTF-8 by default)

This array C<< @{$self->{TT}{doc_in}} >> holds this input document data as an
array of strings with alternating meanings.
 * The string C<$textline> holding each line of the input text data.
 * The string C<< $filename:$linenum >> holding its location and called as
   "reference" (C<linenum> starts with 1).

Merk op dat dit niets ontleedt. U moet de functie parse()  gebruiken wanneer
u klaar bent met het inladen van invoerbestanden in het document.

=item write($)

Het vertaalde document schrijven naar het bestand met de opgegeven naam.

This translated document data are provided by:
 * C<< $self->docheader() >> holding the header text for the plugin, and
 * C<< @{$self->{TT}{doc_out}} >> holding each line of the main translated text in the array.

=back

=head2 PO-bestanden manipuleren

=over 4

=item readpo($)

De inhoud van een bestand (waarvan de naam als argument opgegeven werd)
toevoegen aan het bestaande invoerPO-bestand. De oude inhoud wordt niet
verwijderd.

=item writepo($)

Het geëxtraheerde PO-bestand naar het bestand schrijven waarvan de naam
opgegeven werd.

=item stats()

Geeft bepaalde statistieken weer over de tot nu toe gemaakte vertaling. Merk
op dat het niet dezelfde statistieken zijn als die welke door msgfmt
--statistic getoond worden. Hier gaat het om statistieken over het recente
gebruik van het PO-bestand, terwijl msgfmt rapporteert over de toestand van
het bestand. Het is een omhulsel voor de functie
Locale::Po4a::Po::stats_get, toegepast op het invoerPO-bestand. Een
gebruiksvoorbeeld:

    [normal use of the po4a document...]

    ($percent,$hit,$queries) = $document->stats();
    print "We found translations for $percent\%  ($hit from $queries) of strings.\n";

=back

=head2 Addenda manipuleren

=over 4

=item addendum($)

Raadpleeg L<po4a(7)|po4a.7> voor meer informatie over wat addenda zijn en
hoe vertalers ze moeten schrijven. Om een addendum toe te passen op het
vertaalde document, moet u gewoon de bestandsnaam ervan doorgeven aan deze
functie en u bent klaar ;)

Deze functie zendt bij een fout een geheel getal terug dat geen nul is.

=back

=head1 INTERNE FUNCTIES welke gebruikt worden voor het schrijven van afgeleide
ontleders

=head2 Invoer krijgen, uitvoer leveren

Er staan vier functies ter beschikking om invoer te krijgen en uitvoer af te
leveren. Zij zijn erg vergelijkbaar met shift/unshift en push/pop van Perl.

 * Perl shift returns the first array item and drop it from the array.
 * Perl unshift prepends an item to the array as the first array item.
 * Perl pop returns the last array item and drop it from the array.
 * Perl push appends an item to the array as the last array item.

Het eerste paar heeft betrekking op invoer, terwijl het tweede op uitvoer
betrekking heeft. Geheugensteuntje: bij invoer bent u geïnteresseerd in de
eerste regel, hetgeen shift geeft, en bij uitvoer wilt u uw resultaat
toevoegen aan het einde, zoals push doet.

=over 4

=item shiftline()

Deze functie zendt de eerste te ontleden regel terug en zijn overeenkomstige
referentie (verpakt als lijst) uit de lijst C<< @{$self->{TT}{doc_in}} >> en
verwijdert deze eerste 2 lijstitems. Hier wordt de referentie verstrekt door
een tekenreeks C<< $filename:$linenum >> (bestandsnaam:regelnummer).

=item unshiftline($$)

Plaatst de laatste met shift uit het invoerdocument verwijderde regel en
zijn overeenkomstige referentie terug aan het begin van C<<
{$self->{TT}{doc_in}} >>.

=item pushline($)

Voegt een nieuwe regel toe aan het einde van C<< {$self->{TT}{doc_out}} >>.

=item popline()

Verwijdert de laatste met push toegevoegde regel aan het einde van C<<
{$self->{TT}{doc_out}} >>.

=back

=head2 Tekstfragmenten als vertaalbaar markeren

Er wordt een functie verstrekt om de tekst die moet worden vertaald, te
verwerken.

=over 4

=item translate($$$)

Verplichte argumenten:

=over 2

=item -

Een te vertalen tekstfragment

=item -

De referentie van dit tekstfragment (d.w.z. positie in het invoerbestand)

=item -

Het type van dit tekstfragment (d.w.z. de letterlijke beschrijving van zijn
structurele rol; gebruikt in Locale::Po4a::Po::gettextization(); zie ook
L<po4a(7)|po4a.7>, afdeling B<Het gettextize-proces: hoe werkt dit?>)

=back

Aan deze functie kunnen ook enkele extra argumenten meegegeven worden. Zij
moeten als een hash georganiseerd worden. Bijvoorbeeld:

  $self->translate("string","ref","type",
                   'wrap' => 1);

=over

=item B<wrap>

Booleaanse operator die aangeeft of we witruimte in tekstfragmenten al dan
niet als belangrijk moeten beschouwen. Indien ja, dan canoniseert de functie
het tekstfragment voordat ze op zoek gaat naar een vertaling of voordat ze
dit fragment extraheert, en past ze regelafbreking toe op de vertaling.

=item B<wrapcol>

de kolom waarop de regelafbreking moet gebeuren (standaard: de waarde van
B<wrapcol> die is opgegeven tijdens het maken van de TransTractor of 76).

De negatieve waarde wordt afgetrokken van de standaardwaarde.

=item B<comment>

een aan het element toe te voegen extra commentaar.

=back

Acties:

=over 2

=item -

Duwt tekstfragment, referentie en type naar po_out.

=item -

Zendt de vertaling van het tekstfragment (zoals gevonden in po_in) terug,
zodat de ontleder het doc_out kan bouwen.

=item -

Gebruikt de tekensets voor het hercoderen van de tekstfragmenten vooraleer
deze naar po_out gezonden worden en voorafgaand aan het terugzenden van de
vertalingen.

=back

=back

=head2 Diverse functies

=over 4

=item verbose()

Geeft aan of de optie verbose opgegeven werd tijdens de creatie van de
TransTractor.

=item debug()

Geeft aan of de optie debug opgegeven werd tijdens de creatie van de
TransTractor.

=item get_in_charset()

Deze functie geeft de tekenset terug die als hoofdtekenset is opgegeven

=item get_out_charset()

Deze functie zendt terug welke tekenset gebruikt moet worden in het
uitvoerdocument (gewoonlijk nuttig om de gedetecteerde karakterset van het
invoerdocument te vervangen waar dit aangetroffen werd).

De aan de commandoregel gespecificeerde tekenset zal gebruikt worden. Indien
daar niets gespecificeerd werd, wordt de tekenset van het invoerPO-bestand
gebruikt, en indien in het invoerPO-bestand het standaard "CHARSET" vermeld
staat, zal de tekenset van het invoerdocument teruggezonden worden, zodat
geen tekenhercodering uitgevoerd wordt.

=back

=head1 RICHTINGEN VOOR DE TOEKOMST

Een tekortkoming van het huidige TransTractor is dat het niet overweg kan
met vertaalde documenten welke alle talen bevatten, zoals debconf-sjablonen
of .desktop-bestanden.

Om dit probleem aan te pakken, zijn de enige noodzakelijke aanpassingen aan
de interface:

=over 2

=item -

voor po_in_name het (Perl) variabeletype hash gebruiken (een lijst per taal)

=item -

een te vertalen argument toevoegen om de doeltaal aan te geven

=item -

een pushline_all-functie maken, die pushline zou toepassen voor zijn inhoud
voor alle talen met behulp van een kaartachtige syntaxis:

    $self->pushline_all({ "Description[".$langcode."]=".
                          $self->translate($line,$ref,$langcode)
                        });

=back

We zullen zien of dit volstaat ;)

=head1 AUTEURS

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)
 Jordi Vilalta <jvprat@gmail.com>
