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

Po4a - Rahmenwerk zur Übersetzung von Dokumentation und anderen Materialien

=head1 Einleitung

Po4a (PO für alles) erleichtert die Pflege von Dokumentationsübersetzungen
mittels der klassischen Gettext-Werkzeuge. Die Hauptfunktionalität von Po4a
ist, dass sie die Übersetzung des Inhaltes von der Dokumentenstruktur
trennt.

Dieses Dokument dient als Einführung in das Po4a-Projekt mit einem Fokus auf
mögliche Benutzer, die überlegen, ob sie dieses Werkzeug verwenden sollten
und den Neugierigen, die verstehen möchten, warum die Dinge so sind, wie sie
sind.

=head1 Warum Po4a?

Die Philosophie Freier Software ist es, die Technik wirklich für jeden
verfügbar zu machen. Aber Lizenzierung ist nicht die einzige Betrachtung:
nicht übersetzte Freie Software ist für nicht englisch sprechende Personen
nutzlos. Daher haben wir noch einiges zu tun, Software für jede Person
verfügbar zu machen.

Von den meisten Projekten wird diese Situation sehr gut verstanden und jeder
ist jetzt von der Notwendigkeit, alles zu übersetzen, überzeugt. Allerdings
stellt die eigentliche Übersetzung einen riesengroßen Aufwand durch viele
Beteiligte dar, die zudem von kleinen technischen Schwierigkeiten behindert
werden.

Dankenswerterweise ist Open-Source-Software mittels der
Gettext-Werkzeugsammlung sehr gut übersetzt. Diese Werkzeuge werden zum
Entnehmen der zu übersetzenden Zeichenketten aus einem Programm verwandt und
dann werden diese Zeichenketten in einem standardisierten Format dargestellt
(genannt PO-Dateien oder Übersetzungskataloge). Ein gesamtes Ökosystem an
Werkzeugen ist entstanden, um Übersetzern beim eigentlichen Übersetzen
dieser PO-Dateien zu helfen. Das Ergebnis wird dann von Gettext zur Laufzeit
verwandt, um dem Endbenutzer die übersetzten Meldungen anzuzeigen.

Im Hinblick auf Dokumentation ist die Situation allerdings immer noch etwas
entäuschend. Anfangs erscheint die Übersetzung der Dokumentation leichter
als die Übersetzung eines Programms, da es so aussieht, als müssten Sie nur
das Ursprungsdokument kopieren und anfangen, den Inhalt zu übersetzen. Wenn
allerdings das Ursprungsdokument verändert wird, wird die Nachverfolgung der
Änderungen schnell zu einem Albtraum für Übersetzer. Falls dies manuell
erfolgt, ist die Aufgabe unschön und fehlerbehaftet.

Veraltete Übersetzungen sind oft schlimmer als gar keine. Endbenutzer können
durch Dokumentation, die veraltetes Verhalten des Programms beschreibt,
verwirrt werden. Sie können zudem nicht direkt mit dem Betreuer in Kontakt
treten, da sie kein Englisch sprechen. Zusätzlich kann der Betreuer keine
Probleme beheben, da er nicht jede Sprache spricht, in die seine
Dokumentation übersetzt ist. Diese Schwierigkeiten, die oft durch schlechte
Werkzeuge hervorgerufen werden, können die Motivation für freiwillige
Übersetzer unterminieren, wodurch das Problem weiter verschlimmert wird.

B<Das Ziel des Po4a-Projektes ist es, die Arbeit der Dokumentenübersetzer zu
erleichtern.> Insbesondere macht es die Dokumentenübersetzungen I<pflegbar>.

Die Idee besteht darin, den Gettext-Ansatz für dieses Feld wiederzuverwenden
und anzupassen. Wie bei Gettext werden Texte aus ihren ursprünglichen Orten
herausgelöst und den Übersetzern als PO-Übersetzungskataloge
dargestellt. Die Übersetzer können die klassischen Gettext-Werkzeuge wirksam
einsetzen, um die zu erledigende Arbeit zu überwachen, zusammenzuarbeiten
und sich als Teams zu organisieren. Po4a fügt dann die Übersetzung direkt in
die Dokumentationsstruktur ein, um übersetzte Quelldateien zu erstellen, die
dann genau wie die englischen Dateien verarbeitet und verteilt werden
können. Jeder Absatz, der nicht übersetzt ist, verbleibt im entstehenden
Dokument auf englisch, wodurch sichergestellt ist, dass die Endbenutzer
niemals veraltete Übersetzungen in der Dokumentation sehen.

Dies automatisiert den größten Teil der Routinearbeit bei der Wartung von
Übersetzungen. Es wird sehr leicht, die zu aktualisierenden Absätze zu
erkennen und der Prozess ist vollständig automatisiert, wenn Elemente ohne
weitere Änderungen neu sortiert werden. Es können auch spezielle
Überprüfungen verwandt werden, um die Möglichkeit von Formatierungsfehlern
zu verringern, die zu einem defekten Dokument führen würden.

Bitte lesen Sie auch die B<FAQ> weiter unten in diesem Dokument für eine
komplette Liste der Vor- und Nachteile dieser Vorgehensweise.

=head2 Unterstützte Formate

Derzeit wurde diese Vorgehensweise erfolgreich für mehrere Arten von
Textformatierungsformaten umgesetzt:

=over 

=item man (ausgereiftes Auswertprogramm)

Das gute alte Handbuchformat, verwandt von vielen Programmen da draußen. Die
Unterstützung durch Po4a wird hier sehr begrüßt, da dieses Format etwas
schwierig zu benutzen und für Neulinge nicht wirklich einladend ist.

Das Modul L<Locale::Po4a::Man(3pm)|Man> unterstützt das Format »mdoc«, das
von den BSD-Handbuchseiten verwandt wird (diese sind auch unter Linux recht
häufig anzutreffen).

=item AsciiDoc (ausgereiftes Auswertprogramm)

Dieses Format ist ein leichtgewichtiges Textauszeichnungsformat, um das
Schreiben von Dokumentation zu erleichtern. Es wird beispielsweise von dem
Git-System verwandt. Dessen Handbuchseiten werden mittels Po4a übersetzt.

=item pod (ausgereiftes Auswertprogramm)

Das ist das »Perl Online Documentation«-Format. Die Sprache und
Erweiterungen selbiger sind in diesem Format dokumentiert sowie die meisten
existierenden Perl-Skripte. Sie erleichtert es, die Dokumentation nahe beim
eigentlichen Code zu halten, indem beide in die gleiche Datei eingebettet
werden. Es erleichtert Programmierern die Arbeit, aber unglücklicherweise
nicht den Übersetzern, bis sie Po4a verwenden.

=item sgml (ausgereiftes Auswertprogramm)

Obwohl dieses Format heutzutage von XML verdrängt wurde, wird es noch für
Dokumente verwandt, die mehr als ein paar Bildschirmseiten lang sind. Es
kann sogar für komplette Bücher verwandt werden. Die Übersetzung so langer
Dokumente zu aktualisieren kann eine echte Herausforderung werden. B<diff>
stellt sich oft als nutzlos raus, wenn der ursprüngliche Text nach der
Aktualisierung neu eingerückt wurde. Glücklicherweise kann Ihnen Po4a nach
diesem Prozess helfen.

Derzeit werden nur die DebianDoc- und DocBook-DTD unterstützt, aber das
Hinzufügen einer Unterstützung für eine neue DTD ist wirklich leicht. Es ist
sogar möglich, Po4a für eine unbekannte SGML-DTD zu verwenden, ohne den Code
zu verändern, indem die benötigten Informationen auf der Befehlszeile
übergeben werden. Lesen Sie L<Locale::Po4a::Sgml(3pm)> für weitere Details.

=item TeX / LaTeX (ausgereiftes Auswertprogramm)

Das LaTeX-Format ist ein wichtiges Dokumentationsformat, das in der Welt der
Freien Software und für Veröffentlichungen genutzt wird.

Das Modul L<Locale::Po4a::LaTeX(3pm)|LaTeX> wurde mit der
Python-Dokumentation, einem Buch und ein paar Präsentationen ausprobiert.

=item text (ausgereiftes Auswertprogramm)

Das Text-Format ist das Grundlagenformat für viele Formate, die längere
Textblöcke enthalten wie Markdown, debian/changelog und debian/control.

Dies unterstützt das häufige in »Static Site Generators«, READMEs und
anderen Dokumentationssystemen verwandte Format. Siehe
L<Locale::Po4a::Text(3pm)|Text> für Details.

=item xml und XHMTL (wahrscheinlich ausgereiftes Auswertprogramm)

Das XML-Format liegt vielen Dokumentationsformaten zu Grunde.

Derzeit werden die DocBook-DTD (siehe L<Locale::Po4a::Docbook(3pm)> für
weitere Details) und XHTML von Po4a unterstützt.

=item texinfo (sehr hoch experimentelles Auswertprogramm)

Die gesamte GNU-Dokumentation ist in diesem Format geschrieben (dies ist
sogar eine der Voraussetzungen, um ein offizielles GNU-Projekt zu
werden). Die Unterstützung für L<Locale::Po4a::Texinfo(3pm)|Texinfo> in Po4a
ist noch ganz am Anfang. Bitte berichten Sie Fehler und
Funktionalitätswünsche.

=item Andere unterstützte Formate

Po4a kann auch mit einigen selteneren oder spezialisierten Formaten umgehen,
wie dem Dokumentationsformat der Kompilierungsoptionen des
2.4+-Linux-Kernels oder der vom Dia-Werkzeug erstellten Diagramme. Das
Hinzufügen eines neuen Formats ist oft sehr leicht und die Hauptaufgabe
besteht darin, einen Parser für Ihr Zielformat zu entwickeln. Lesen Sie
L<Locale::Po4a::TransTractor(3pm)> für mehr Informationen dazu.

=item Nicht unterstützte Formate

Unglücklicherweise fehlen Po4a immer noch Unterstützung für eine Reihe von
Dokumentationsformaten. Viele davon könnten leicht in Po4a unterstützt
werden. Dazu gehören auch Formate, die nicht nur für die Dokumentation
verwandt werden, wie Paketbeschreibungen (Deb und RPM),
Paketinstallationsskriptfragen, Paket-Änderungsprotokolle (»Changelogs«) und
alle spezialisierten Dateiformate, die von Programmen verwandt werden, wie
Spieleszenarien oder WINE-Ressource-Dateien.

=back

=head1 Po4a verwenden

Historisch war Po4a um vier Skripte herum aufgebaut, wobei jedes eine
bestimmte Aufgabe erfüllte. L<po4a-gettextize(1)> hilft beim erstmaligen
Erzeugen von Übersetzungen und optional der Umwandlung bestehender
Übersetzungsprojekte in Po4a. L<po4a-updatepo(1)> spiegelt die Änderungen an
der Ursprungsdokumentation in die entsprechenden
PO-Dateien. L<po4a-translate(1)> baut übersetzte Quelldateien aus der
ursprünglichen Datei und der entsprechenden PO-Datei. Zusätzlich ist
L<po4a-normalize(1)> hauptsächlich zur Fehlersuche der
Po4a-Auswerteprogramme nützlich, da es ein nicht übersetztes Dokument aus
dem ursprünglichen baut. Dies erleichtert es, Störungen zu finden, die aus
dem Auswerteprozess stammen.

Die meisten Projekte benötigen nur die Funktionalitäten von
L<po4a-updatepo(1)> und L<po4a-translate(1)>. Allerdings habe sich diese
Skripte als mühsam und fehleranfällig erwiesen. Falls die zu übersetzende
Dokumentation auf mehrere Quelldateien verteilt ist, ist es schwierig, die
PO-Dateien aktuell zu halten und die Dokumentationsdateien korrekt zu
bauen. Zur Lösung wurde ein Komplettwerkzeug bereitgestellt:
L<po4a(1)>. Dieses Werkzeug akzeptiert eine Konfigurationsdatei, die die
Struktur des Übersetzungsprojektes beschreibt: den Ort der PO-Dateien, die
Liste der zu übersetzenden Dateien und die zu verwendenden Optionen. Der
Prozess ist damit vollständig automatisiert. Wenn Sie L<po4a(1)> aufrufen,
aktualisiert es die PO-Dateien und regeneriert die Übersetzungsdateien wo
notwendig. Falls alles bereits aktuell ist, ändert L<po4a(1)> keine Datei.

Der Rest dieses Abschnitts gibt einen Überblick über die Skriptschnittstelle
von Po4a. Die meisten Benutzer werden wahrscheinlich das Komplettwerkzeug
bevorzugen, das in der Dokumentation von L<po4a(1)> beschrieben ist.

=head2 Graphischer Überblick über die Po4a-Skripte

Das nachfolgende Schema gibt einen Überblick darüber, wie jedes Po4a-Skript
verwandt werden kann. Hier steht F<master.dok> als Beispielname für die zu
übersetzende Dokumentation; F<XX.dok> das gleiche Dokument übersetzt in die
Sprache XX während F<doc.XX.po> der Übersetzungskatalog für das Dokument in
der Sprache XX ist. Dokumentationsautoren kümmern sich hauptsächlich um
F<master.dok> (dies kann eine Handbuchseite, ein XML-Dokument, eine
Asciidoc-Datei oder ähnliches sein); die Übersetzer kümmern sich
hauptsächlich um die PO-Dateien, während die Endbenutzer nur die Datei
F<XX.dok> sehen werden.

                                   Master.dok
                                       |
                                       V
     +<-----<----+<-----<-----<--------+------->-------->-------+
     :           |                     |                        :
{Übersetzung}    |     { Aktualisierung von Master.dok }        :
     :           |                     |                        :
   XX.dok        |                     V                        V
(optional)       |                 Master.dok ->-------->------>+
     :           |                   (neu)                      |
     V           V                     |                        |
  [po4a-gettextize]   dok.XX.po--->+   |                        |
          |            (alt)       |   |                        |
          |              ^         V   V                        |
          |              |     [po4a-updatepo]                  |
          V              |           |                          V
   Übersetzung.pot       ^           V                          |
          |              |         dok.XX.po                    |
          |              |        (unscharf)                    |
   { Übersetzung }       |           |                          |
          |              ^           V                          V
          |              |  {manuelle Bearbeitung}              |
          |              |           |                          |
          V              |           V                          V
      dok.XX.po --->---->+<---<---- doc.XX.po   Addendum     Master.dok
    (anfänglich)                    (aktuell)  (optional)     (aktuell) 
          :                          |            |             |
          :                          V            |             |
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V            V             V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                           [po4a-translate]
                                                  |
                                                  V
                                                XX.dok
                                               (aktuell)

Dieses Schema ist kompliziert, aber in der Praxis wird nur der rechte Teil
(der L<po4a-updatepo(1)> und L<po4a-translate(1)> betrifft) verwandt, sobald
das Projekt eingerichtet und konfiguriert ist.

Der linke Teil stellt dar, wie L<po4a-gettextize(1)> verwandt werden kann,
um ein bestehendes Übersetzungsprojekt in die Po4a-Infrastruktur zu
überführen. Dieses Skript akzeptiert ein Ursprungsdokument und sein
übersetztes Gegenstück und versucht, eine entsprechende PO-Datei daraus zu
bauen. Eine solche manuelle Umwandlung ist recht beschwerlich (lesen Sie die
Dokumentation von L<po4a-gettextize(1)> für weitere Details), sie wird aber
nur einmalig notwendig, um Ihre bestehende Übersetzungen zu
überführen. Falls Sie keine Übersetzungen überführen müssen, können Sie
diesen Schritt ignorieren und sich auf den rechten Teil des Schemas
konzentrieren.

Ganz oben rechts wird die Aktion der Ursprungsautors dargestellt, der die
Dokumentation aktualisiert. Der mittel-rechte Teil stellt die automatischen
Aktionen von L<po4a-updatepo(1)> dar. Das neue Material wird herausgelöst
und mit der bestehenden Übersetzung verglichen. Die vorherige Übersetzung
wird für unveränderte Teile verwandt, während teilweise geänderte Teile mit
der vorherigen Übersetzung mit einer »fuzzy«-Markierung verbunden sind, die
anzeigt, dass die Übersetzung aktualisiert werden muss. Neues oder stark
verändertes Material verbleibt unübersetzt.

Dann stellt der I<manuelles Bearbeiten> die Aktionen der Übersetzer dar, die
die PO-Dateien verändern, um Übersetzungen für jede Ursprungszeichenkette
und jeden Absatz bereitzustellen. Dies kann entweder mit einem speziellen
Editor wie dem B<GNONME-Übersetzungs-Editor>, KDEs B<Lokalize> oder
B<poedit> erfolgen, oder mittels einer Online-Lokalisierungsplattform wie
B<Weblate> oder B<Pootle>. Das Übersetzungsergebnis ist eine Gruppe von
PO-Dateien, eine pro Sprache. Bitte lesen Sie die Gettext-Dokumentation für
weitere Details.

Der untere Teil der Abbildung zeigt, wie L<po4a-translate(1)> ein
übersetztes Quelldokument aus dem ursprünglichen Dokument F<master.doc> und
dem Übersetzungskatakog F<doc.XX.po>, der durch die Übersetzer aktualisiert
wurde, erstellt. Die Struktur des Dokuments wird wiederverwandt, während der
ursprüngliche Inhalt durch sein übersetztes Gegenstück ersetzt
wird. Optional kann ein Addendum verwandt werden, um einigen Extratext zu
der Übersetzung hinzuzufügen. Dies wird oft dazu verwandt, den Namen des
Übersetzers zum finalen Dokument hinzuzufügen. Sie finden Details hierzu
weiter unten.

Wie zuvor angemerkt, kombiniert das Programm L<po4a(1)> die Wirkung der
getrennten Skripte, Aktualisierungen der PO-Dateien und des übersetzten
Dokumentes in einem Aufruf. Die zugrundeliegende Logik bleibt identisch.

=head2 Eine neue Übersetzung beginnen

Falls Sie L<po4a(1)> verwenden, gibt es keinen bestimmten Schritt zum Start
einer Übersetzung. Sie müssen nur die Sprachen in der Konfigurationsdatei
aufführen und die fehlenden PO-Dateien werden automatisch
erstellt. Natürlich müssen die Übersetzer dann die Übersetzungen für
sämtliche Inhalte in Ihren Dokumenten bereitstellen. L<po4a(1)> erstellt
auch eine POT-Datei, das ist eine PO-Vorlagendatei. Mögliche Übersetzer
können Ihr Projekt in eine neue Sprache übersetzen, indem sie diese Datei
umbenennen und die Übersetzungen in ihrer Sprache bereitstellen.

Falls Sie es bevorzugen, die individuellen Skripte separat zu verwenden,
sollten Sie L<po4a-gettextize(1)> wie folgt verwenden, um die POT-Datei zu
erstellen. Diese Datei kann dann nach F<XX.po> kopiert werden, um eine neue
Übersetzung zu starten.

  $ po4a-gettextize --format <Format> --master <Master.dok> --po <Übersetzung.pot>

Das Masterdokument wird als Eingabe, während die POT-Datei als die Ausgabe
des Prozesses verwandt wird.

=head2 Integration von Änderungen am ursprünglichen Dokument

Das hierzu zu verwendende Programm ist L<po4a-updatepo(1)> (bitte lesen Sie
dessen Dokumentation für Details):

  $ po4a-updatepo --format <Format> --master <neue_Master.dok> --po <alte_dok.XX.po>

Das Master-Dokument wird in der Eingabe verwandt, während die PO-Datei
aktualisiert wird: sie wird sowohl in der Ein- als auch der Ausgabe
verwandt.

=head2 Erstellen eines übersetzten Dokumentes

Sobald Sie mit der Übersetzung fertig sind, möchten Sie die übersetzte
Dokumentation erhalten und diese dann zusammen mit der ursprünglichen an die
Benutzer verteilen. Verwenden Sie hierfür das Programm L<po4a-translate(1)>
wie folgt:

  $ po4a-translate --format <Format> --master <Master.dok> --po <dok.XX.po> --localized <XX.dok>

Sowohl die Master- als auch die PO-Dateien werden als Eingabe verwandt,
während die lokalisierte Datei die Ausgabe dieses Prozesses ist.

=head2 Verwendung von Addenda, um zusätzlichen Text zu Übersetzungen hinzuzufügen

Hinzufügen von neuem Text zu der Übersetzung ist wahrscheinlich das einzige,
was langfristig bei der manuellen Übersetzung einfacher ist :). Dies kommt
vor, wenn Sie einen zusätzlichen Abschnitt zu dem übersetzten Dokument
hinzufügen möchten, der nicht zu Inhalten im Ursprungsdokument passt. Der
klassische Anwendungsfall ist die Danksagung an das Übersetzungs-Team und
die Information, wie übersetzungsspezifische Fehler berichtet werden sollen.

Mit Po4a müssen Sie B<addendum>-Dateien angeben, die konzeptionell als
Patches angesehen werden können, die auf das lokalisierte Dokument nach der
Verarbeitung angewandt werden. Jedes Addendum muss als separate Datei
bereitgestellt werden, wobei das Format sich allerdings deutlich von
klassischen Patches unterscheidet. Die erste Zeile ist eine I<Kopfzeile>,
die den Einschubpunkt des Addendums definiert (mit einer unglücklicherweise
kryptischen Syntax -- siehe unten), während der Rest der Datei unverändert
an der festgelegten Position eingefügt wird.

Die Kopfzeile muss mit der Zeichenkette B<PO4A-HEADER:> beginnen, gefolgt
von einer durch Semikola getrennten Liste von
I<Schlüssel>B<=>I<Wert>-Paaren.

Beispielsweise erklärt die folgende Kopfzeile, dass ein Addendum ganz am
Ende der Übersetzung abgelegt werden muss.

 PO4A-HEADER: mode=eof

Die Dinge werden komplexer, wenn Sie den zusätzlichen Inhalt in der Mitte
des Dokuments hinzufügen wollen. Die folgende Kopfzeile erklärt, dass nach
dem XML-Abschnitt, der die Zeichenkette B<Über dieses Dokument> in der
Übersetzung enthält, ein Addendum abgelegt werden muss.

=pod

 PO4A-HEADER: position=Über dieses Dokument; mode=after; endboundary=</section>

In der Praxis wird Po4a beim Versuch, ein Addendum anzuwenden, nach der
ersten Zeile, die auf das Argument C<Position> passt, suchen (C<Position>
kann ein regulärer Ausdruck sein). Vergessen Sie nicht, dass Po4a hier das
B<übersetzte> Dokument betrachtet. Das Ursprungsdokument ist auf Englisch,
aber Ihre Zeile sollte wahrscheinlich wie folgt aussehen, falls Sie möchten,
dass sie auf die französische Übersetzung des Dokuments angewandt wird.

 PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>

Sobald die C<Position> im Zieldokument gefunden wurde, sucht Po4a für die
nächste Zeile nach der C<Position>, die auf das bereitgestellte
C<endboundary> passt. Das Addendum wird direkt B<nach> dieser Zeile
eingefügt (da wir eine I<endboundary> bereitstellten, d.h. eine Begrenzung,
die den aktuellen Abschnitt beendet).

Der genau gleiche Effekt könnte mit den nachfolgenden Kopfzeilen erreicht
werden, die äquivalent sind:

 PO4A-HEADER: position=Über dieses Dokument; mode=after; beginboundary=<section>

Hier sucht Po4a in der Übersetzung nach der ersten Zeile, die auf
C<<section>> passt und nach der auf C<Über dieses Dokument> passenden Zeile
liegt, und fügt das Addendum B<vor> dieser Zeile ein, da wir ein
I<beginboundary> bereitgestellt haben, d.h. eine Begrenzungsmarkierung, die
den Anfang des nächsten Abschnitts markiert. Daher verlangt diese Kopfzeile,
dass das Addendum nach dem Abschnitt, der C<Über dieses Dokument> enthält,
gesetzt wird, und weist Po4a an, dass dieser Abschnitt mit einer Zeile, die
die Markierung C<<section>> enthält, beginnt. Dies ist zum vorherigen
Beispiel äquivalent, da Sie in Wirklichkeit möchten, dass dieses Addendum
entweder nach C</section>> oder vor C<<section>> hinzugefügt wird.

Sie können den Einfüge-I<Modus> auch auf den Wert C<before> setzen, mit
einer ähnlichen Semantik: Kombinierung von C<mode=before> mit einem
C<endboundary> wird dass Addendum genau B<nach> der passenden Begrenzung
setzen. Dies ist die letzte mögliche Begrenzungszeile vor der
C<Position>. Kombinierung von C<mode=before> mit einer C<beginboundary>
setzt das Addendum genau B<vor> die passende Begrenzung. Dies ist die letzte
mögliche Begrenzung vor der C<Position>.

  Modus  | Begrenzungsart |  Verwandte Begrenzung | Einfügepunkt im Vergleich zur Begrenzung
 ========|================|=======================|=========================================
 'before'| 'endboundary'  | letzte vor 'Position' | direkt nach der ausgewählten Begrenzung
 'before'|'beginboundary' | letzte vor 'Position' | direkt vor der ausgewählten Begrenzung
 'after' | 'endboundary'  | erste nach 'Position' | direkt nach der ausgewählten Begrenzung
 'after' |'beginboundary' | erste nach 'Position' | direkt vor der ausgewählten Begrenzung
 'eof'   |   (keine)      |  n.Z.                 | Dateiende

=head3 Tipps und Tricks rund um Addenda

=over 

=item 

Denken Sie daran, dass dies reguläre Ausdrücke sind. Falls Sie
beispielsweise das Ende eines Nroff-Abschnittes, das auf die Zeile C<.fi>
endet, vergleichen wollen, verwenden Sie nicht C<.fi> als B<endboundary>, da
es auf C<the[ fi]le> passen wird, was sie offensichtlich nicht erwarten
würden. Das korrekte B<endboundary> ist in diesem Fall: B<^\.fi$>.

=item 

Leerzeichen SIND im Inhalt von C<position> und Begrenzungen wichtig. Daher
B<unterscheiden> sich die beiden nachfolgenden Zeilen. Die zweite wird nur
gefunden, falls im übersetzen Dokument ausreichend angehängte Leerzeichen
sind.

 PO4A-HEADER: position=Über dieses Dokument; mode=after; beginboundary=<section>
 PO4A-HEADER: position=Über dieses Dokument ; mode=after; beginboundary=<section>

=item 

Obwohl diese Kontextsuche so betrachtet werden könnte, als ob sie ungefähr
auf jeder Zeile des B<übersetzten> Dokuments arbeiten würde, arbeitet sie
tatsächlich auf der internen Datenzeichenkette des übersetzten
Dokuments. Diese interne Datenzeichenkette kann ein Text sein, der mehrere
Absätze mit mehreren Zeilen umfasst oder kann eine einzelne XML-Markierung
selbst sein. Der genaue I<Einfügepunkt> des Addendums muss vor oder nach der
internen Datenzeichenkette und kann nicht innerhalb der internen
Datenzeichenkette liegen.

=item 

Übergeben Sie das Argument B<-vv> an Po4a, um zu verstehen, wie Addenda zu
der Übersetzung hinzugefügt werden. Es kann auch helfen, Po4a im
Fehlersuchmodus zu betreiben, um die tatsächlichen internen
Datenzeichenketten zu sehen, wenn Ihr Addendum nicht angewandt wird.

=back

=head3 Addenda-Beispiele

=over 

=item 

Falls Sie etwas hinter den folgenden Nroff-Abschnitt hinzufügen möchten:

  .SH "AUTOREN"

Sie sollten den zweischrittigen Zugang durch Setzen von B<mode=after>
wählen. Dann sollten Sie mit dem regulären Argumentenausdruck B<Position>
die Suche auf die Zeile nach B<AUTOREN> eingrenzen. Dann sollten Sie eine
Übereinstimmung mit dem Anfang des nächsten Abschnittes (d.h. B<^\.SH>) mit
dem regulären Argumentenausdruck B<beginboundary> erzielen. Mit anderen
Worten:

 PO4A-HEADER:mode=after;position=AUTOREN;beginboundary=\.SH

=item 

Falls Sie etwas direkt nach einer Zeile hinzufügen möchten (etwa hinter
»Copyright Großer Kerl«), verwenden Sie eine B<Position>, die auf diese
Zeile passt und geben Sie ein B<beginboundary> an, das zu irgendeiner Zeile
passt.

 PO4A-HEADER:mode=after;position=Copyright Großer Kerl, 2004;beginboundary=^

=item 

Falls Sie am Ende des Dokuments etwas hinzufügen möchten, geben Sie eine
B<Position> an, die zu einer Zeile Ihres Dokuments passt (aber nur eine
Zeile – Po4a wird nicht fortfahren, wenn sie nicht eindeutig ist) und geben
Sie ein B<endboundary> an, das zu nichts passt. Verwenden Sie hier keine
einfachen Zeichenketten wie B<»EOF«>, aber nehmen Sie bevorzugt solche, bei
denen es unwahrscheinlich ist, dass sie sich in Ihrem Dokument befinden.

 PO4A-HEADER:mode=after;position=Über dieses Dokument;beginboundary=FakePo4aBoundary

=back



=head3 Ein ausführlicheres Beispiel

Originaldokument (POD-formatiert):

 |=head1 BESCHREIBUNG
 |
 |dummy - Ein Platzhalterprogramm
 |
 |=head1 AUTOR
 |
 |ich

Dann wird das folgende Addendum sicherstellen, dass ein Abschnitt (auf
Französisch) über den Übersetzer an das Ende der Datei hinzugefügt wird (auf
Französisch heißt »ÜBERSETZER« »TRADUCTEUR« und »moi« heißt »ich«).

 |PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
 |
 |=head1 TRADUCTEUR
 |
 |moi
 |

Um Ihr Addendum vor dem AUTOR einzufügen, verwenden Sie die folgende
Kopfzeile:

 PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1

Dies funktioniert, da die nächste auf das B<beginboundary> /^=head1/
passende Zeile nach dem Abschnitt »BESCHREIBUNG« (übersetzt zu »NOM« auf
Französisch) diejenige ist, die die Autoren deklariert. Daher wird das
Addendum zwischen beide Abschnitte gelegt. Beachten Sie: Falls später ein
anderer Abschnitt zwischen den Abschnitten NAME und AUTHOR hinzugefügt wird,
wird Po4a das Addendum fehlerhafterweise vor den neuen Abschnitt legen.

Um dies zu vermeiden, können Sie das gleiche mittels B<mode>=I<before>
erreichen:

 PO4A-HEADER:mode=before;position=^=head1 AUTEUR

=head1 Wie funktioniert es?

Dieses Kapitel gibt Ihnen einen kurzen Überblick über die Interna von Po4a,
so dass Sie sich sicherer fühlen, es zu warten und zu verbessern. Es könnte
Ihnen auch dabei helfen, zu verstehen, warum es nicht das tut, was Sie
erwarten, und wie Sie Ihre Probleme beheben können.

Die Po4a-Architektur ist objektorientiert. Die Klasse
L<Locale::Po4a::TransTractor(3pm)|TransTractor> ist der gemeinsame Vorfahr
von allen Auswertungsklassen. Dieser merkwürdige Name ist der Tatsache zu
verdanken, dass er gleichzeitig für das Übersetzen des Dokuments und das
Extrahieren von Zeichenketten zuständig ist.

Förmlicher ausgedrückt nimmt es ein Dokument zum Übersetzen plus eine
PO-Datei, die die Übersetzungen enthält, als Eingabe, während es zwei
getrennte Ausgaben erzeugt: Eine weitere PO-Datei (die das Ergebnis des
Extrahierens übersetzbarer Zeichenketten vom Eingabedokument ist) und einem
übersetzen Dokument (mit der gleichen Struktur, wie der aus der Eingabe, bei
der aber alle übersetzbaren Zeichenketten durch den Inhalt der
Eingabe-PO-Datei ersetzt wurden). Hier eine grafische Darstellung davon:

 Eingabedokument -- \                             /---> Ausgabedokument
                     \      TransTractor::       /       (übersetzt)
                      +-->--   parse()  --------+
                     /                           \
 Eingabe-PO-Datei---/                             \---> Ausgabe-PO-Datei
                                                          (extrahiert)



Dieser kleine Knochen ist der Kern der Po4a-Architektur. Falls Sie die
Eingabe-PO-Datei und das Ausgabedokument weglassen, erhalten Sie
B<po4a-gettextize>. Falls Sie beide Eingaben bereitstellen und die
Ausgabe-PO-Datei nicht beachten, erhalten Sie B<po4a-translate>. B<po4a>
ruft TransTractor zweimal auf und ruft B<msgmerge -U> zwischen diesen
TransTractor-Aufrufen auf, um Lösungen aus einer Hand mit einer einzelnen
Konfigurationsdatei bereitzustellen. Bitte lesen Sie
L<Locale::Po4a::TransTractor(3pm)> für weitere Details.

=head1 Open-Source-Projekte, die Po4a verwenden

Es folgt eine unvollständige Liste von Projekten, die Po4a für ihre
Dokumentation im Einsatz haben. Falls Sie Ihre Projekt in diese Liste
aufgenommen haben möchten, schicken Sie uns auf Englisch eine E-Mail (oder
einen »Merge Request«).

=over 

=item 

adduser (man): Benutzer- und Gruppenverwaltungswerkzeug.

=item 

apt (man, docbook): Debian-Paketverwalter.

=item 

aptitude (docbook, svg): Terminal-baierter Paketverwalter für Debian

=item 

L<F-Droid website|https://gitlab.com/fdroid/fdroid-website> (markdown):
installierbarer Katalog an FOSS (Free and Open Source Software) Anwendungen
für die Android-Plattform.

=item 

L<git|https://github.com/jnavila/git-manpages-l10n> (asciidoc): verteiltes
Versionssteuersystem zur Nachverfolgung von Quellcodeänderungen.

=item 

L<Linux manpages|https://salsa.debian.org/manpages-l10n-team/manpages-l10n>
(man)

Dieses Projekt stellt die Infrastruktur zur Übersetzung vieler
Handbuchseiten in verschiedene Sprachen bereit, mit Integration in viele
große Distributionen (Arch Linux, Debian und abgeleitete, Fedora).

=item 

L<Stellarium|https://github.com/Stellarium/stellarium> (HTML): ein freies,
Open-Source-Planetarium für Ihren Rechner. Po4a wird zur Übersetzung der
Himmelskulturbeschreibungen verwandt.

=back



=head1 Häufig gestellte Fragen

=head2 Wie wird Po4a ausgesprochen?

Ich persönlich spreche es als L<pouah|https://en.wiktionary.org/wiki/pouah>
aus, was auf Französich lautmalerisch anstelle von »Bäh« verwandt wird :)
Vielleicht habe ich einen merkwürdigen Humor :)

=head2 Was ist mit den anderen Übersetzungswerkzeugen für Dokumentation, die
Gettext benutzen?

Soweit mir bekannt, gibt es nur zwei davon:

=over 

=item B<poxml>

Dies ist das durch KDE-Leute entwickelte Werkzeug, um DocBook-XML zu
handhaben. Soweit bekannt, war es das erste Programm zum Extrahieren von
Zeichenketten aus der Dokumentation in PO-Dateien und um sie nach dem
Übersetzen wieder einzuspeisen.

Es kann nur XML und eine spezielle DTD handhaben. Der Verfasser ist ziemlich
unglücklich mit der Handhabung von Listen, die in einer großen Msgid
enden. Wenn die Liste groß wird, wird es schwerer, mit dem großen Stück
umzugehen.

=item B<po-debiandoc>

Dieses von Denis Barbier erstellte Programm ist so eine Art Vorläufer des
Po4a-SGML-Moduls, wodurch ersteres mehr oder weniger missbilligt ist. Wie
der Name sagt, handhabt es nur die DebianDoc-DTD, die mehr oder weniger eine
missbilligte DTD ist.

=back

Die Hauptvorteile von Po4a demgegenüber sind die Erleichterung beim
Hinzufügen zusätzlichen Inhalts (was dort sogar schlechter ist) und die
Fähigkeit, Gettext zu verwenden.

=head2 ZUSAMMENFASSUNG der Vorteile der Gettext-basierten Herangehensweise

=over 2

=item 

Die Übersetzungen werden nicht zusammen mit dem Original gespeichert,
wodurch es möglich wird, festzustellen, ob Übersetzungen nicht mehr aktuell
sind.

=item 

Die Übersetzungen werden jeweils in separaten Dateien gespeichert, was
verhindert, dass sich Übersetzer unterschiedlicher Sprachen, sowohl beim
Senden des Patches als auch auf der Ebene des Dateikodierung, stören.

=item 

Es basiert intern auf B<Gettext> (B<Po4a> bietet aber eine sehr einfache
Schnittstelle, so dass Sie die Interna nicht verstehen müssen, um es zu
benutzen). Auf diese Art muss das Rad nicht neu erfunden werden und aufgrund
ihrer weiten Verbreitung kann davon ausgegangen werden, dass diese Werkzeuge
mehr oder weniger fehlerfrei sind.

=item 

Für den Endanwender hat sich nichts geändert (außer der Tatsache, dass
Übersetzungen hoffentlich besser gepflegt werden). Die resultierende
Dokumentationsdatei, die verteilt wird, ist exakt dieselbe.

=item 

Es ist nicht nötig, dass Übersetzer eine neue Dateisyntax lernen und ihr
bevorzugter PO-Editor (wie der PO-Modus von Emacs, Lokalize oder
Gtranslator) wird gut funktionieren.

=item 

Gettext bietet eine einfache Möglichkeit, Statistiken darüber zu erhalten,
was erledigt ist, was überprüft und aktualisiert werden sollte und was noch
zu erledigen ist. Einige Beispiele können unter den folgenden Adressen
gefunden werden:

 - https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html
 - http://www.debian.org/intl/l10n/

=back

Aber nicht alles ist rosig und diese Herangehensweise hat auch einige
Nachteile, die bewältigt werden müssen.

=over 2

=item 

Addenda sind … auf den ersten Blick merkwürdig.

=item 

Sie können den übersetzten Text nicht nach Ihren Präferenzen anpassen, wie
das Aufteilen eines Absatzes hier und das Zusammensetzen zwei anderer
dort. Aber, falls es in einem gewissen Sinn ein Problem mit dem Original
gibt, sollte es sowieso als Fehler gemeldet werden.

=item 

Sogar mit der einfachen Oberfläche bleibt es ein neues Werkzeug, das Leute
lernen müssen.

Es wäre traumhaft, wenn jemand Po4a in Gtranslator oder Lokalize einbinden
würde. Wenn eine Dokumentationsdatei geöffnet wird, werden die Zeichenketten
automatisch extrahiert. Wenn sie gespeichert wird, kann eine übersetzte
Datei + PO-Datei auf die Platte geschrieben werden. Falls es fertiggebracht
wird, ein MS-Word-Modul™ (oder zumindest RTF) zu erstellen, können es sogar
professionelle Übersetzer nutzen.

=back

=head1 SIEHE AUCH

=over 

=item 

Die Dokumentation des Komplettwerkzeuges, das Sie verwenden sollen:
L<po4a(1)>.

=item 

Die Dokumentation der individuellen Po4a-Skripte: L<po4a-gettextize(1)>,
L<po4a-updatepo(1)>, L<po4a-translate(1)>, L<po4a-normalize(1)>.

=item 

Die zusätzlichen Helferskripte: L<msguntypot(1)>, L<po4a-display-man(1)>,
L<po4a-display-pod(1)>.

=item 

Die Auswertprogramme für jedes Format, insbesondere, um die durch jedes
akzeptierten Optionen zu sehen: L<Locale::Po4a::AsciiDoc(3pm)>
L<Locale::Po4a::Dia(3pm)>, L<Locale::Po4a::Guide(3pm)>,
L<Locale::Po4a::Ini(3pm)>, L<Locale::Po4a::KernelHelp(3pm)>,
L<Locale::Po4a::Man(3pm)>, L<Locale::Po4a::RubyDoc(3pm)>,
L<Locale::Po4a::Texinfo(3pm)>, L<Locale::Po4a::Text(3pm)>,
L<Locale::Po4a::Xhtml(3pm)>, L<Locale::Po4a::Yaml(3pm)>,
L<Locale::Po4a::BibTeX(3pm)>, L<Locale::Po4a::Docbook(3pm)>,
L<Locale::Po4a::Halibut(3pm)>, L<Locale::Po4a::LaTeX(3pm)>,
L<Locale::Po4a::Pod(3pm)>, L<Locale::Po4a::Sgml(3pm)>,
L<Locale::Po4a::TeX(3pm)>, L<Locale::Po4a::Wml(3pm)>,
L<Locale::Po4a::Xml(3pm)>.

=item 

Die Implementierung der Kerninfrastruktur:
L<Locale::Po4a::TransTractor(3pm)> (insbesondere zum Verständnis der
Code-Organisation wichtig), L<Locale::Po4a::Chooser(3pm)>,
L<Locale::Po4a::Po(3pm)>, L<Locale::Po4a::Common(3pm)>. Prüfen Sie bitte
auch die Datei F<CONTRIBUTING.md> im dem Quellbaum.

=back

=head1 AUTOREN

 Denis Barbier <barbier,linuxfr.org>
 Martin Quinson (mquinson#debian.org)

