
        *****************************************************
        *           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 NAME

Locale::Po4a::TransTractor - generischer Übersetzungs-Ausleser

=head1 BESCHREIBUNG

Das Projektziel von Po4a (PO für alles) ist es, die Übersetzung (und
interessanter, die Wartung der Übersetzung) zu vereinfachen, indem die
Gettext-Werkzeuge auch für Gebiete verwendet werden, wo diese nicht erwartet
werden, wie Dokumentation.

Diese Klasse ist Vorfahr jedes Po4a-Parsers. Sie wird zum Auswerten eines
Dokuments, zur Suche nach übersetzbaren Zeichenketten, zum Auslesen in eine
PO-Datei und zur Ersetzung durch ihre Übersetzung im Ausgabedokument,
verwandt.

Oder formaler, sie erwartet die folgenden Argumente als Eingabe:

=over 2

=item -

ein zu übersetzendes Dokument

=item -

eine PO-Datei, die die zu verwendende Übersetzung enthält.

=back

Als Ausgabe produziert sie:

=over 2

=item -

eine weitere PO-Datei, die aus der Auslösung der übersetzbaren Zeichenketten
aus dem Eingabedokument entsteht

=item -

ein übersetztes Dokument mit der gleichen Struktur wie das der Eingabe, bei
der aber alle übersetzbaren Zeichenketten mit den in der als Eingabe
bereitgestellten PO-Datei gefundenen Übersetzungen ersetzt wurden.

=back

Dies ist eine graphische Darstellung davon:

   Eingabedokument --\                             /---> Ausgabedokument
                      \                           /        (übersetzt)
                       +-> parse()-Funktion -----+
                      /                           \
   Eingabe-PO -------/                             \---> Ausgabe-PO
                                                         (herausgelöst)

=head1 FUNCTIONEN, DIE IHR PARSER ÜBERSCHREIBEN SOLLTE

=over 4

=item parse()

Hier findet die gesamte Arbeit statt: das Auswerten der Eingabedokumente,
die Erstellung der Ausgabe und das Herauslösen der übersetzbaren
Zeichenketten. Das ist mit den in Abschnitt B<INTERNE FUNKTIONEN> weiter
unten vorgestellten angebotenen Funktionen recht einfach. Lesen Sie auch die
B<ÜBERSICHT>, in der ein Beispiel vorgestellt wird.

Diese Funktion wird von der unten beschriebenen process()-Funktion
aufgerufen. Falls Sie sich aber entscheiden, die new()-Funktion zu verwenden
und den Inhalt manuell zu Ihrem Dokument hinzuzufügen, müssen Sie diese
Funktion selbst aufrufen.

=item docheader()

Diese Funktion gibt den Header zurück und sollte dem erzeugten Dokument
hinzugefügt werden, ordentlich zitiert, so dass sie in der Zielsprache ein
Kommentar wird. Lesen Sie den Abschnitt B<Entwickler über Übersetzungen
schulen>, von L<po4a(7)|po4a.7>, um zu erfahren, wozu dies benutzt wird.

=back

=head1 ÜBERSICHT

Das folgende Beispiel wertet eine Liste von Absätzen aus, die mit »<p>»
beginnen. Der Einfachheit halber wird angenommen, dass das Dokument gut
formatiert ist, d.h. dass »<p>«-Markierungen die einzigen vorhandene
Markierungen sind und dass diese Markierung ganz am Anfang jedes Absatzes
steht.

 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--; ) {
               # Nicht das erste Mal, dass wir <p> sehen.
               # Die aktuelle Zeile erneut in die Eingabe packen,
               #  und den gebauten Absatz in die Ausgabe
               $self->unshiftline($line,$lref);

               # Jetzt, wo das Dokument zusammengebaut ist, übersetze es:
               #   - Einleitende Markierung entfernen
               $paragraph =~ s/^<p>//s;

               #   - Rausschieben, um die einleitende Markierung (nicht übersetzt) und den
               #     Rest des Absatzes (übersetzt) auszugeben
               $self->pushline(  "<p>"
                               . $self->translate($paragraph,$pararef)
                               );

               next PARAGRAPH;
           } else {
               # An den Absatz anhängen
               $paragraph .= $line;
               $pararef = $lref unless(length($pararef));
           }

           # Die Schleife neu initialisieren
           ($line,$lref)=$self->shiftline();
       }
       # Keine definierte Zeile erhalten? Ende der Eingabedatei.
       return;
   }
 }

Sobald Sie die Funktion zum Auswerten implementiert haben, können Sie Ihre
Dokumentenklasse verwenden, die die öffentliche Schnittstelle benutzt, die
im nächsten Abschnitt vorgestellt wird.

=head1 ÖFFENTLICHE SCHNITTSTELLE für Skripte, die Ihren Parser benutzen

=head2 Konstruktor

=over 4

=item process(%)

Diese Funktion kann alles tun, was Sie mit einem Po4a-Dokument in einem
Aufruf tun müssen. Ihre Argumente müssen als ein Hash gepackt
sein. AKTIONEN:

=over 3

=item a.

liest alle PO-Dateien, die in po_in_name angegeben sind

=item b.

liest alle Originaldokumente, die in file_in_name angegeben sind

=item c.

wertet das Dokument aus

=item d.

liest alle angegebenen Addenda und wendet sie an

=item e.

schreibt das übersetzte Dokument in file_out_name (falls angegeben)

=item f.

schreibt die extrahierte PO-Datei nach po_out_name (falls angegeben)

=back

ARGUMENTE jenseits der durch new() akzeptierten (mit erwartetem Typ):

=over 4

=item file_in_name (@)

Liste der Dateinamen, bei denen das Eingabedokument gelesen werden sollte

=item file_in_charset ($)

im Eingabedokument benutzter Zeichensatz (falls er nicht angegeben wurde,
wird UTF-8 benutzt).

=item file_out_name ($)

Name der Datei, in den das Ausgabedokument geschrieben werden soll

=item file_out_charset ($)

im Ausgabedokument benutzter Zeichensatz (falls er nicht angegeben wurde,
wird UTF-8 benutzt).

=item po_in_name (@)

Liste der Dateinamen, von denen die Eingabe-PO-Dateien gelesen werden
sollen; enthält die Übersetzung, die benutzt wird, um das Dokument zu
übersetzen

=item po_out_name ($)

Name der Datei, in den die Ausgabe-PO-Datei geschrieben werden soll; enthält
die aus dem Eingabedokument extrahierten Zeichenketten.

=item addendum (@)

Liste der Dateinamen, aus denen die Addenda gelesen werden

=item addendum_charset ($)

Zeichensatz für die Addenda

=back

=item new(%)

erstellt ein neues Po4a-Dokument; akzeptiert Optionen (in dem als Parameter
übergebenen Hash):

=over 4

=item verbose ($)

setzt die Detailstufe

=item debug ($)

setzt die Debugging-Stufe

=item wrapcol ($)

die Spalte, an der der Text im Ausgabedokument umgebrochen werden soll
(standardmäßig 76)

Ein negativer Wert bedeutet, dass überhaupt kein Umbruch stattfindet.

=back

Es akzeptiert auch die nächsten Optionen für zugrundeliegende PO-Dateien:
B<porefs>, B<copyright-holder>, B<msgid-bugs-address>, B<package-name>,
B<package-version>, B<wrap-po>.

=back

=head2 Manipulieren von Dokumentdateien

=over 4

=item read($$$)

Fügt weitere Eingabedokumentendaten am Ende des bestehenden Felds C<<
@{$self->{TT}{doc_in}} >> hinzu.

Diese Funktion akzeptiert zwei verpflichtende Argumente und ein optionales.
 * Der von Platte zu lesende Dateiname;
 * Der Name, der für den Bau von Referenzen in der PO-Datei verwandt werden soll;
 * Der Zeichensatz, der zum Lesen dieser Datei (standardmäßig UTF-8) verwendet werden soll

Das Feld C<< @{$self->{TT}{doc_in}} >> hält die Eingabedokumentdaten als ein
Feld von Zeichenketten mit abwechselnden Bedeutungen.
 * Die Zeichenkette C<$textline> hält jede Zeile der Eingabetextdaten.
 * Die Zeichenkette C<< $filename:$linenum >> hält ihren Ort und wird
   »reference« genannt (C<linenum> beginnt mit 1).

Bitte beachten Sie, dass es nichts auswertet. Sie sollten die Funktion
parse() benutzen, wenn Sie damit fertig sind, Eingabedateien in das Dokument
zu packen.

=item write($)

schreibt das übersetzte Dokument in den angegebene Dateinamen

Diese übersetzten Dokumentdaten werden bereitgestellt durch:
 * C<< $self->docheader() >> hält den Kopftext für die Erweiterung und
 * C<< @{$self->{TT}{doc_out}} >> hält jede Zeile des übersetzten Haupttextes in dem Feld.

=back

=head2 PO-Dateien bearbeiten

=over 4

=item readpo($)

fügt den Inhalt einer Datei (deren Name als Argument übergeben wird) der
existierenden Eingabe-PO-Datei hinzu. Der alte Inhalt wird nicht verworfen.

=item writepo($)

schreibt die extrahierte PO-Datei in den angegebene Dateinamen

=item stats()

gibt einige Statistiken über bisher erledigte Übersetzungen zurück. Bitte
beachten Sie, dass es sich nicht um die gleichen Statistiken handelt, die
»msgfmt --statistics« ausgibt. Hier geht es um den aktuellen Gebrauch der
PO-Datei, während Msgfmt den Status der Datei ausgibt. Es ist ein Wrapper
für die Funktion Locale::Po4a::Po::stats_get, die auf die Eingabe-PO-Datei
angewandt wird. Beispiel für die Benutzung:

    [Normale Verwendung des Po4a-Dokuments …]

    ($percent,$hit,$queries) = $document->stats();
    print "Es wurden Übersetzungen für $percent\%  ($hit von $queries) der Zeichenketten gefunden.\n";

=back

=head2 Addenda manipulieren

=over 4

=item addendum($)

Weitere Informationen, was Addenda sind und wie Übersetzer sie schreiben
sollten, finden Sie unter L<po4a(7)|po4a.7>. Um ein Addendum auf ein
übersetztes Dokument anzuwenden, übergeben Sie einfach dieser Funktion
seinen Dateinamen und Sie sind fertig. ;)

Diese Funktion gibt bei einem Fehler eine Ganzzahl ungleich Null zurück.

=back

=head1 INTERNE FUNKTIONEN, die zum Schreiben abgeleiteter Parser verwendet werden

=head2 Eingaben erhalten, Ausgaben bereitstellen

Es werden vier Funktionen bereitgestellt, um Eingaben zu erhalten und
Ausgaben zurückzuliefern. Sie sind den Funktionen shift/unshift und push/pop
von Perl sehr ähnlich.

 * Perl shift liefert den ersten Feldeintrag zurück und entfernt ihn aus dem Feld.
 * Perl unshift hängt einen Eintrag als ersten Feldeintrag vor das Feld.
 * Perl pop liefert den letzten Feldeintrag zurück und entfernt ihn aus dem Feld.
 * Perl push hängt einen Eintrag als letzten Feldeintrag an das Feld an.

Das erste Paar handelt von der Eingabe, während das Zweite von der Ausgabe
handelt. Merkhilfe: In der Eingabe sind Sie an der ersten Zeile
interessiert, was Shift ausgibt und in der Ausgabe möchten Sie Ihr Ergebnis
an das Ende hinzufügen, wie dies Push tut.

=over 4

=item shiftline()

Diese Funktion liefert die erste auszuwertende Zeile und ihre entsprechende
Referenz (als Feld gepackt) aus dem Feld C<< @{$self->{TT}{doc_in}} >>
zurück und entfernt diese ersten zwei Feldeinträge. Hier wird die Referenz
durch eine Zeichenkette C<< $filename:$linenum >> bereitgestellt.

=item unshiftline($$)

Schiebt die letzte geschobene Zeile des Eingabedokuments und seiner
entsprechenden Referenz an den Kopf von C<< {$self->{TT}{doc_in}} >> zurück.

=item pushline($)

Schiebt eine neue Zeile an das Ende von C<< {$self->{TT}{doc_out}} >>.

=item popline()

Holt die zuletzt geschobene Zeile vom Ende von C<< {$self->{TT}{doc_out}}
>>.

=back

=head2 Zeichenketten als übersetzbar markieren

Eine Funktion wird bereitgestellt, um den Text zu handhaben, der übersetzt
werden soll.

=over 4

=item translate($$$)

vorgeschriebene Argumente:

=over 2

=item -

eine zu übersetzende Zeichenkette

=item -

die Referenz dieser Zeichenkette (d.h. Position in der Eingabedatei)

=item -

der Typ der Zeichenkette (d.h. die inhaltliche Beschreibung ihrer
strukturellen Rolle; benutzt in Locale::Po4a::Po::gettextization(); siehe
auch L<po4a(7)|po4a.7>, Abschnitt B<Gettextisierung: Wie funktioniert das?>)

=back

Diese Funktion kann außerdem einige zusätzliche Argumente
entgegennehmen. Sie müssen als Hash organisiert sein. Zum Beispiel:

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

=over

=item B<wrap>

logische Variable, ob die Leerzeichen in der Zeichenkette als unwichtig
betrachtet werden können. Falls ja, wird die Funktion die Zeichenkette in
eine kanonische Form bringen, bevor nach einer Übersetzungen gesucht oder
diese extrahiert wird und ein Zeilenumbruch wird durchgeführt.

=item B<wrapcol>

die Spalte an der umgebrochen werden soll (standardmäßig der Wert von
B<wrapcol>, der während der Erstellung des TransTractor festgelegt wurde
oder 76).

Der negative Wert wird von der Vorgabe abgezogen.

=item B<comment>

ein zusätzlicher Kommentar, der zum Eintrag hinzugefügt wird

=back

Aktionen:

=over 2

=item -

schiebt die Zeichenkette, die Referenz und den Typ nach po_out

=item -

gibt die Übersetzung der Zeichenkette (wie sie in po_in gefunden wurde)
zurück, so dass der Parser das doc_out bauen kann

=item -

handhabt die Zeichensätze, um den Zeichensatz der Zeichenkette umzuwandeln,
bevor sie an po_out gesandt werden und bevor die Übersetzungen zurückgegeben
werden

=back

=back

=head2 Verschiedene Funktionen

=over 4

=item verbose()

kehrt zurück, falls die Option »verbose« während der Erstellung von
TransTractor übergeben wurde

=item debug()

kehrt zurück, falls die Option »debug« während der Erstellung von
TransTractor übergeben wurde

=item get_in_charset()

Diese Funktion liefert den Zeichensatz zurück, der als Hauptzeichensatz
bereitgestellt wurde

=item get_out_charset()

Diese Funktion wird den Zeichensatz zurückgeben, der im ausgegebenen
Dokument benutzt werden sollte (üblicherweise nützlich, um den ermittelten
Zeichensatz des Eingabedokuments zu ersetzen, wo er gefunden wurde).

Sie wird den auf der Befehlszeile angegebenen Zeichensatz verwenden. Falls
er nicht angegeben wurde, wird sie den Zeichensatz der Eingabe-PO-Datei
benutzen und falls die Eingabe-PO-Datei die Vorgabe »CHARSET« hat, wird sie
den Zeichensatz des Eingabedokuments zurückgeben, so dass die Kodierung
durchgeführt wird.

=back

=head1 ZUKÜNFTIGE ENTWICKLUNGEN

Ein Mangel des aktuellen Transtractors ist, dass er keine übersetzten
Dokumente handhaben kann, die alle Sprachen enthalten, wie
Debconf-Schablonen oder Desktop-Dateien.

Um dieses Problem anzugehen, sind nur bestimmte Schnittstellenänderungen
notwendig:

=over 2

=item -

einen Hash in po_in_name nehmen (eine Liste pro Sprache)

=item -

ein zu übersetzendes Argument hinzufügen, um die Zielsprache anzugeben

=item -

ein Funktion pushline_all erstellen, die pushline ihres Inhalts für alle
Sprachen unter Benutzung einer kartenähnlichen Syntax ausführen würde:

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

=back

Es wird sich zeigen, ob das ausreicht. ;)

=head1 AUTOREN

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