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

po4a - raamwerk voor de vertaling van documentatie en ander materiaal

=head1 Inleiding

po4a (PO voor alles) vergemakkelijkt het onderhoud van de vertaling van
documentatie via het gebruik van het klassieke gettext-gereedschap. De
belangrijkste eigenschap van po4a is dat het de vertaling van de inhoud
loskoppelt van de structuur van het document.

Dit document dient als een inleiding tot het po4a-project met een focus op
potentiële gebruikers die zich afvragen of ze dit hulpmiddel zouden
gebruiken, en op nieuwsgierigen die willen begrijpen waarom de dingen zijn
zoals ze zijn.

=head1 Waarom po4a?

De filosofie van Vrije Software is om de technologie echt voor iedereen
beschikbaar te maken. Maar het licentie-aspect is niet het enige om in
overweging te nemen: voor niet-Engelstaligen is niet-vertaalde software
nutteloos. Daarom hebben we nog steeds wat werk te doen om software voor
iedereen beschikbaar te maken.

Door de meeste projecten wordt deze situatie goed begrepen en iedereen is nu
overtuigd van de noodzaak om alles te vertalen. Niettemin betekent het
eigenlijke vertaalwerk een geweldige inspanning voor veel individuen,
gehandicapt door kleine technische moeilijkheden.

Gelukkig wordt opensourcesoftware eigenlijk heel goed vertaald met behulp
van de gettext gereedschapssuite. Dit gereedschap wordt gebruikt om de te
vertalen tekstfragmenten uit een programma te extraheren en deze te vertalen
tekstfragmenten aan te bieden in een gestandaardiseerde indeling
(PO-bestanden genoemd, ofwel vertaalcatalogus). Een heel ecosysteem
hulpmiddelen is ontstaan om vertalers te helpen bij het daadwerkelijk
vertalen van deze PO-bestanden. Het resultaat wordt vervolgens door gettext
gebruikt om tijdens de programmauitvoering de vertaalde berichten aan de
eindgebruiker te tonen.

Met betrekking tot documentatie is de situatie nog steeds enigszins
ontgoochelend. Op het eerste gezicht lijkt het vertalen van documentatie
makkelijker dan een programma vertalen, aangezien het erop lijkt dat je
gewoon het bronbestand met de documentatie moet kopiëren en moet beginnen
met het vertalen van de inhoud. Wanneer aan de originele documentatie echter
aanpassingen gemaakt worden, wordt het bijhouden van de wijzigingen al snel
een nachtmerrie voor de vertalers. Indien deze taak manueel moet gebeuren is
ze onaangenaam en foutgevoelig.

Verouderde vertalingen zijn vaak erger dan helemaal geen
vertaling. Eindgebruikers kunnen misleid worden door documentatie die een
verouderd gedrag van het programma beschrijft. Bovendien kunnen zij niet
rechtstreeks in interactie treden met de onderhouders, omdat zij geen Engels
spreken. Daarenboven kan de onderhouder het probleem niet oplossen,
aangezien deze niet elke taal kan kennen waarin de documentatie vertaald
werd. Deze moeilijkheden, vaak veroorzaakt door slecht gereedschap, kan de
motivatie van vertaalvrijwilligers ondermijnen en zo leiden tot een verdere
verergering van het probleem.

B<Het doel van het po4a-project is om het werk van documentatievertalers te
vergemakkelijken>.  In het bijzonder maakt het documentatievertalingen
I<onderhoudbaar>.

Het idee bestaat erin de gettext-aanpak te hergebruiken en aan te passen aan
deze sector. Zoals dat met gettext het geval is, worden teksten geëxtraheerd
uit hun originele locatie en aan vertalers voorgelegd als
PO-vertaalcatalogi. De vertalers kunnen gebruik maken van het klassieke
gettext-gereedschap om het te presteren werk op te volgen, om samen te
werken en zich als team te organiseren. Daarna injecteert po4a de
vertalingen rechtstreeks in de structuur van de documentatie om vertaalde
bronbestanden te produceren die verwerkt en verspreid kunnen worden, net als
de Engelse bestanden. Elke onvertaalde paragraaf blijft in het uiteindelijke
document in het Engels staan, zodat er voor gezorgd wordt dat de
eindgebruiker nooit een verouderde vertaling te zien krijgt in de
documentatie.

Dit automatiseert het grootste deel van het zware werk van het onderhoud van
vertalingen. Te weten komen welke paragrafen bijgewerkt moeten worden, wordt
erg makkelijk, en het proces van het herordenen van elementen zonder dat er
verder iets wijzigt, verloopt volledig automatisch. Ook kan specifieke
verificatie toegepast worden om de kans op opmaakfouten, welke tot een
defect document zouden leiden, te verkleinen.

Raadpleeg ook de B<FAQ> verder in dit document, voor een meer volledige
lijst van de voor- en nadelen van deze aanpak.

=head2 Ondersteunde indelingen

Momenteel werd deze aanpak met succes toegepast voor verschillende soorten
tekstopmaakindelingen:

=over

=item man (voldragen ontleder)

De goede oude man-paginaindeling, welke door zoveel programma's gebruikt
wordt. Ondersteuning door po4a is hier erg welkom, aangezien deze indeling
enigszins moeilijk te gebruiken is en niet echt vriendelijk voor
nieuwkomers.

De module L<Locale::Po4a::Man(3pm)|Man> ondersteunt ook de mdoc-indeling,
welke door de BSD man-pagina's gebruikt wordt (deze zijn ook redelijk
gebruikelijk onder Linux).

=item AsciiDoc (voldragen ontleder)

Dit is een lichtgewicht opmaakindeling, bedoeld om het schrijven van
documentatie te vergemakkelijken. Zij wordt bijvoorbeeld gebruikt voor het
documenteren van het git-systeem. Deze man-pagina's worden vertaald met
po4a.

Zie L<Locale::Po4a::AsciiDoc> voor details.

=item pod (voldragen ontleder)

Dit is de indeling voor de Perl Online Documentatie. De computertaal en de
uitbreidingen ervan worden gedocumenteerd met behulp van deze indeling, net
als de meeste bestaande Perl-scripts. Het maakt het makkelijk om de
documentatie dicht bij de echte code te houden, door beide in te bedden in
hetzelfde bestand. Het maakt het leven van programmeurs makkelijker, maar
jammer genoeg niet dat van vertalers, tenzij u po4a gebruikt.

Zie L<Locale::Po4a::Pod> voor details.

=item sgml (voldragen ontleder)

Zelfs als deze indeling tegenwoordig wordt vervangen door XML, wordt ze nog
steeds gebruikt voor documenten van meer dan enkele schermen lang. Ze kan
zelfs gebruikt worden voor volledige boeken. Het kan een hele uitdaging zijn
om dergelijk lange documenten bij te werken. B<diff> blijkt vaak niet
bruikbaar te zijn wanneer na het bijwerken het inspringen van  de
oorspronkelijke tekst opnieuw werd uitgevoerd. Gelukkig kan po4a u na dit
proces behulpzaam zijn.

Momenteel worden enkel DebianDoc en DocBook DTD ondersteund, maar iets
anders ondersteunen is erg gemakkelijk. Het is zelfs mogelijk om zonder de
code te wijzigen po4a te gebruiken bij een onbekende SGML DTD door de nodige
informatie op te geven aan de commandoregel. Zie L<Locale::Po4a::Sgml(3pm)>
voor details.

=item TeX / LaTeX (voldragen ontleder)

De LaTeX-indeling is een heel belangrijke indeling voor documentatie in de
vrije-softwarewereld evenals voor publicaties.

De module L<Locale::Po4a::LaTeX(3pm)|LaTeX> werd getest met de
Python-documentatie , een boek en enkele presentaties.

=item text (voldragen ontleder)

De indeling Text is de basisindeling voor veel indelingen welke lange
blokken tekst bevatten, waaronder Markdown, fortunes, inleidend gedeelte van
YAML, debian/changelog en debian/control.

Dit ondersteunt de indeling die Static Site Generators, README's en andere
documentatiesystemen gebruiken en gemeen hebben. See
L<Locale::Po4a::Text(3pm)|Text> voor meer informatie.

=item xml and XHMTL (vermoedelijk voldragen ontleder)

De indeling XML is een basisindeling voor veel documentatie-indelingen.

Momenteel worden DocBook DTD (zie L<Locale::Po4a::Docbook(3pm)> voor
details) en XHTML door po4a ondersteund.

=item BibTex (vermoedelijk voldragen ontleder)

De BibTex-bestandsindeling wordt naast LaTex gebruikt voor het opmaken van
referentielijsten (bibliografieën).

Zie L<Locale::Po4a::BibTex> voor details.

=item Docbook (vermoedelijk voldragen ontleder)

Een op XML gebaseerde opmaaktaal die semantische tags gebruikt om documenten
te beschrijven.

Zie L<Locale::Po4a:Docbook> voor meer details.

=item Guide XML (vermoedelijk voldragen ontleder)

Een XML-documentatieformaat. Deze module is speciaal ontwikkeld in functie
van het ondersteunen en onderhouden van vertalingen van Gentoo
Linux-documentatie tot ten minste maart 2016 (gebaseerd op de Wayback
Machine). Gentoo is sindsdien overgestapt naar de DevBook
XML-bestandsindeling.

Zie L<Locale::Po4a:Guide> voor meer details.

=item Wml (vermoedelijk voldragen ontleder)

De Web-opmaaktaal (Web Markup Language); verwar WML niet met de WAP-spullen
die op mobiele telefoons worden gebruikt. Deze module is gebaseerd op de
Xhtml-module, die zelf weer is gebaseerd op de XmL-module.

Zie L<Locale::Po4a::Wml> voor meer details.

=item Yaml (vermoedelijk voldragen ontleder)

Een strikte superset van JSON. YAML wordt vaak gebruikt als systeem- of
configuratieproject. YAML vormt de kern van Red Hat's Ansible.

Zie L<Locale::Po4a::Yaml> voor meer details.

=item RubyDoc (vermoedelijk voldragen ontleder)

Het Ruby Document (RD) formaat, oorspronkelijk het standaard
documentatieformaat voor Ruby en Ruby-projecten voordat in 2002 werd
overgeschakeld naar RDoc, hoewel de Japanse versie van het Ruby
Referentiehandboek blijkbaar nog steeds RD gebruikt.

Zie L<Locale::Po4a::RubyDoc> voor meer details.

=item Halibut (vermoedelijk experimentele ontleder)

Een documentatieproductiesysteem, met elementen die te vergelijken zijn met
TeX, debiandoc-sgml, TeXinfo, en andere, ontwikkeld door Simon Tatham, de
ontwikkelaar van PuTTY.

Zie L<Locale::Po4a:Halibut> voor meer details.

=item Ini (vermoedelijk experimentele ontleder)

Configuratiebestandsindeling, populair geworden door MS-DOS.

Zie L<Locale::Po4a::Ini> voor meer details.

=item texinfo (zeer erg experimentele ontleder)

Alle GNU-documentatie wordt in deze indeling geschreven (het is zelfs een
vereiste om een officieel GNU-project te worden). De ondersteuning in po4a
voor L<Locale::Po4a::Texinfo(3pm)|Texinfo> zit nog steeds in zijn
beginfase. Gelieve problemen en functieverzoeken te rapporteren.

=item gemtext (zeer erg experimentele ontleder)

Het standaard platte tekstformaat van het Gemini-protocol. De extensie
C<.gmi> wordt vaak gebruikt. Ondersteuning voor deze module in po4a staat
nog in zijn kinderschoenen. Als u iets vindt, dien dan een bugrapport of een
functieverzoek in.

=item org (zeer erg experimentele ontleder)

Het documentformaat dat door de Org-modus gebruikt wordt. Ondersteuning voor
deze module in po4a staat nog in zijn kinderschoenen. Als u iets vindt, dien
dan een bugrapport of een functieverzoek in.

=item vimhelp (zeer erg experimentele ontleder)

De indeling die wordt gebruikt voor Vim-hulppagina's (en sommige
documentatie van derden voor plugins). Ondersteuning voor deze indeling in
po4a staat nog in zijn kinderschoenen. Als u iets vindt, dien dan een
bugrapport of een functieverzoek in.

=item simplepod (very highly experimental parser)

Similar to the previously mentioned I<pod>, this one adopts the new
L<Pod::Simple> as its parser.  Since it is newly created, some bugs are
expected.  If you notice any strange behavior, please let us know.
Eventually, this module will replace I<pod>.

=item Andere ondersteunde indelingen

Po4a kan ook overweg met enkele meer zeldzame of gespecialiseerde
indelingen, zoals de documentatie over compilatieopties voor de 2.4+
Linux-kernels (L<Locale::Po4a::KernelHelp>) of de diagrammen die door het
programma dia (L<Locale::Po4a::Dia>) geproduceerd worden. Een nieuwe
indeling toevoegen is vaak erg gemakkelijk en de belangrijkste taak bestaat
erin een ontleder aan te brengen voor de beoogde indeling. Zie
L<Locale::Po4a::TransTractor(3pm)> voor meer informatie hierover.

=item Niet-ondersteunde indelingen

Jammer genoeg biedt po4a nog geen ondersteuning voor verschillende
documentaie-indelingen. Voor vele zou po4a makkelijk ondersteuning kunnen
bieden. Het betreft indelingen die niet enkel voor documentatie gebruikt
worden, zoals pakketbeschrijvingen (deb en rpm), vragen van
pakketinstallatiescripts, changelogs van pakketten en alle gespecialiseerde
bestandsformaten welke gebruikt worden door programma's zoals spelscenario's
en wine-bronbestanden.

=back

=head1 Het gebruik van po4a

De eenvoudigste manier om dit gereedschap in uw project te gebruiken is door
een configuratiebestand te schrijven voor het programma B<po4a> en alleen
met dit programma te interageren. Raadpleeg de documentatie in
L<po4a(1)>. De rest van deze sectie geeft meer details voor gevorderde
gebruikers van po4a die hun inzicht willen verdiepen.

=head2 Gedetailleerd schema van de po4a-werkstroom

Zorg ervoor dat u L<po4a(1)> leest om een vereenvoudigd overzicht te krijgen
van de po4a-werkstroom vóór u aan deze overdreven gedetailleerde sectie
begint. Kom naar hier terug als u het volledige schrikwekkend plaatje wilt
zien, met bijna alle details.

In het volgende schema is F<hoofddocument.doc> een voorbeeldnaam voor de te
vertalen documentatie; F<XX.doc> is hetzelfde document, vertaald in taal XX,
terwijl F<doc.XX.po> de vertaalcatalogus van dat document is in taal
XX. Auteurs van documentatie zullen zich hoofdzakelijk bezighouden met
F<hoofddocument.doc> (dit kan een man-pagina zijn, een XML-document, een
AsciiDoc-bestand, enz.). De vertalers zullen zich hoofdzakelijk bezighouden
met het PO-bestand, terwijl de eindgebruikers uitsluitend het bestand
F<XX.doc> zullen zien.

Overgangen met vierkante haakjes zoals C<[po4a werkt po bij]>
vertegenwoordigen de uitvoering van een po4a-tool, terwijl overgangen met
accolades zoals C<{update hoofddocument.doc}> een handmatige wijziging van
de projectbestanden vertegenwoordigen.

                                   master.doc
                                       |
                                       V
     +<-----<----+<-----<-----<--------+------->-------->-------+
     :           |                     |                        :
{translation}    |          {update of master.doc}              :
     :           |                     |                        :
   XX.doc        |                     V                        V
 (optional)      |                 master.doc ->-------->------>+
     :           |                   (new)                      |
     V           V                     |                        |
  [po4a-gettextize]   doc.XX.po -->+   |                        |
          |            (old)       |   |                        |
          |              ^         V   V                        |
          |              |   [po4a updates po]                  |
          V              |           |                          V
   translation.pot       ^           V                          |
          |              |        doc.XX.po                     |
          |              |         (fuzzy)                      |
    {translation}        |           |                          |
          |              ^           V                          V
          |              |     {manual editing}                 |
          |              |           |                          |
          V              |           V                          V
      doc.XX.po --->---->+<---<-- doc.XX.po    addendum     master.doc
      (initial)                 (up-to-date)  (optional)   (up-to-date)
          :                          |            |             |
          :                          V            |             |
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V            V             V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                     [po4a updates translations]
                                                  |
                                                  V
                                                XX.doc
                                             (up-to-date)

Nogmaals, dit schema is veel te ingewikkeld. Raadpleeg L<po4a(1)> voor een
vereenvoudigd overzicht.

Het linkerdeel laat zien hoe L<po4a-gettextize(1)> kan worden gebruikt om
een bestaand vertaalproject te converteren naar de po4a-infrastructuur. Dit
script gebruikt een origineel document en zijn vertaalde tegenhanger en
tracht het overeenkomstige PO-bestand te bouwen. Een dergelijke handmatige
conversie is nogal omslachtig (zie de documentatie over
L<po4a-gettextize(1)> voor meer details), maar ze moet slechts eenmaal
gebruikt worden om uw bestaande vertalingen om te zetten. Indien u geen te
converteren vertalingen heeft, kunt u dit vergeten en u concentreren op het
rechterdeel van het schema.

In de rechterbovenhoek wordt de actie van de oorspronkelijke auteur
afgebeeld, welke de documentatie bijwerkt. Het middelste rechterdeel geeft
de automatische updates van vertaalbestanden weer. Het nieuwe materiaal
wordt geëxtraheerd en vergeleken met de bestaande vertaling. De vorige
vertaling wordt gebruikt voor de delen welke niet gewijzigd werden, terwijl
de gedeeltelijk gewijzigde delen gekoppeld worden aan de vorige vertaling
met de aanduiding "fuzzy" (onnauwkeurig), hetgeen aangeeft dat de vertaling
moet bijgewerkt worden. Nieuw of grondig gewijzigd materiaal blijft
onvertaald.

Vervolgens geeft het blok I<handmatig bewerken> de actie van de vertalers
weer, welke de PO-bestanden wijzigen om te voorzien in een vertaling voor
elk origineel tekstfragment en alinea. Dit kan gebeuren met een specifieke
editor, zoals de B<GNOME Translation Editor>, KDE's B<Lokalize> of
B<poedit>, of met een online lokalisatieplatform, zoals B<weblate> of
B<pootle>. Het resultaat van de vertaling is een aantal PO-bestanden, één
per taal. Raadpleeg de gettext-documentatie voor meer details.

Het onderste deel van de afbeelding toont hoe B<po4a> een vertaald
brondocument creëert uit het originele document F<hoofddocument.doc> en de
vertaalcatalogus F<doc.XX.po> die door de vertalers bijgewerkt werd. De
structuur van het document wordt hergebruikt, terwijl de originele inhoud
vervangen wordt door de vertaalde tegenhanger. Facultatief kan een addendum
gebruikt worden om aan de vertaling extra tekst toe te voegen. Dit wordt
vaak gebruikt om de naam van de vertaler toe te voegen aan het uiteindelijke
document. Zie hieronder voor details.

Wanneer het aanroepen wordt, werkt B<po4a> zowel de vertaalbestanden als de
vertaalde documentatiebestanden automatisch bij.

=head2 Een nieuw vertaalproject starten

Als u vanaf nul begint, hoeft u alleen maar een configuratiebestand voor
po4a te schrijven en u bent klaar. De relevante sjablonen worden aangemaakt
voor de ontbrekende bestanden, zodat uw medewerkers uw project naar hun taal
kunnen vertalen. Raadpleeg L<po4a(1)> voor een handleiding waarmee u snel
aan de slag kunt en voor alle details.

Als u een bestaande vertaling heeft, d.w.z. een documentatiebestand dat
handmatig is vertaald, kunt u de inhoud ervan in uw po4a-werkstroom
integreren met behulp van B<po4a-gettextize>. Deze taak is een beetje
omslachtig (zoals beschreven in de manpagina van het gereedschap), maar
zodra uw project is geconverteerd naar de po4a-werkstroom, wordt alles
automatisch bijgewerkt.

=head2 De vertalingen en documenten bijwerken

Eenmaal ingesteld, is het aanroepen van B<po4a> voldoende om zowel de
vertalings-PO-bestanden als de vertaalde documenten bij te werken. U kunt
C<--no-translations> doorgeven aan B<po4a> om de vertalingen niet bij te
werken (dus alleen de PO-bestanden bij te werken) of C<--no-update> om de
PO-bestanden niet bij te werken (dus alleen de vertalingen bij te
werken). Dit komt ongeveer overeen met de individuele scripts
B<po4a-updatepo> en B<po4a-translate> die nu verouderd zijn (zie "Waarom
zijn de individuele scripts verouderd" in de FAQ hieronder).

=head2 Addenda gebruiken om extra tekst toe te voegen aan vertalingen

Het toevoegen van nieuwe tekst aan de vertaling is waarschijnlijk het enige
dat op de lange termijn gemakkelijker is wanneer u bestanden handmatig
vertaalt :). Dit gebeurt wanneer u een extra onderdeel wilt toevoegen aan
het vertaalde document, waarvoor in het originele document geen
overeenkomstige inhoud bestaat. Het klassieke toepassingsgebied is erkenning
geven aan het vertaalteam en aangeven hoe vertaalspecifieke problemen gemeld
kunnen worden.

Met po4a moet u B<addendum>-bestanden opgeven, die conceptueel beschouwd
kunnen worden als patches die na verwerking toegepast worden op het
gelokaliseerde document. Elk addendum moet als apart bestand aangereikt
worden. De indeling ervan verschilt evenwel erg van klassieke patches. De
eerste regel is een I<header-regel>, die het invoegpunt van het addendum
definieert (met een helaas cryptische syntaxis -- zie hieronder), terwijl de
rest van het bestand woordelijk toegevoegd wordt op de aangegeven positie.

De header-regel moet beginnen met de tekst B<PO4A-HEADER:>, gevolgd door een
door puntkomma's gescheiden lijst van I<sleutel>B<=>I<waarde> velden.

Bijvoorbeeld, de volgende header declareert een addendum dat helemaal aan
het einde van de vertaling geplaatst moet worden.

 PO4A-HEADER: mode=eof

De zaken zijn complexer wanneer u de extra inhoud wilt toevoegen in het
midden van het document. De volgende header declareert bijvoorbeeld een
addendum dat ingevoegd moet worden na de XML-sectie welke het tekstfragment
C<Over dit document> bevat in de vertaling.

 PO4A-HEADER: position=About this document; mode=after; endboundary=</section>

Wanneer po4a tracht een addendum toe te passen, zoekt het in de praktijk
naar de eerste regel die overeenkomt met het C<position>-argument (dit kan
een reguliere expressie zijn). Vergeet niet dat po4a hier rekening houdt met
het B<vertaalde> document. Deze documentatie is in het Nederlands (en de
originele versie ervan in het Engels), maar uw regel zou er waarschijnlijk
als volgt moeten uitzien, indien u van plan bent een addendum toe te passen
op de Franse vertaling van het document.

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

Nadat in het doeldocument de C<position> gevonden werd, zoekt po4a naar de
eerstvolgende regel na deze C<position> welke overeenkomt met de opgegeven
C<endboundary>. Het addendum wordt ingevoegd net B<na> deze regel (omdat we
een I<endboundary> opgaven, d.w.z. een begrenzing die de huidige sectie
afsluit).

Exact hetzelfde effect kan bekomen worden met de volgende header, die
gelijkwaardig is:

 PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>

Hier zoekt po4a naar de eerste regel die overeenkomt met C<< <section> >> na
de regel die overeenkomt met C<Over dit document> in de vertaling en voegt
het addendum toe B<voor> die regel, omdat we een I<beginboundary> opgegeven
hebben, d.w.z. een begrenzing welke het begin van de volgende sectie
markeert. Deze header-regel vereist dus dat het addendum geplaatst wordt na
de sectie waarin C<Over dit document> voorkomt, en informeert po4a dat een
sectie begint met een regel welke de tag C<< <section> >> bevat. Dit is het
equivalent van het vorige voorbeeld, want wat u eigenlijk wilt is het
addendum in te voegen na C<< </section> >> en voor C<< <section> >>.

U kunt de invoeging I<mode> ook instellen op de waarde C<before>, met een
vergelijkbare semantiek: het combineren van C<mode=before> met een
C<endboundary> zal het addendum juist B<na> de overeenkomstige begrenzing
plaatsen, welke de laatst mogelijke begrenzing is voor de C<position>. De
combinatie van C<mode=before> met een C<beginboundary> zal het addendum
juist B<voor> de overeenkomstige begrenzing plaatsen, welke de laatst
mogelijke grensregel is vóór de C<position>.

  Mode   | Boundary kind |     Used boundary      | Insertion point compared to the boundary
 ========|===============|========================|=========================================
 'before'| 'endboundary' | last before 'position' | Right after the selected boundary
 'before'|'beginboundary'| last before 'position' | Right before the selected boundary
 'after' | 'endboundary' | first after 'position' | Right after the selected boundary
 'after' |'beginboundary'| first after 'position' | Right before the selected boundary
 'eof'   |   (none)      |  n/a                   | End of file

=head3 Aanwijzingen en kneepjes in verband met addenda

=over

=item

Denk eraan dat dit reguliere expressies zijn. Indien u bijvoorbeeld het
einde van een nroff-sectie wilt opzoeken welke eindigt met de regel C<.fi>,
moet u niet C<.fi> gebruiken als B<endboundary>, omdat dit een overeenkomst
zal opleveren met C<the [fi]le>, hetgeen duidelijk niet is wat u
verwacht. De juiste B<endboundary> in dit geval is: C<^\.fi$>.

=item

Witruimte IS belangrijk in de inhoud van de C<position> en de
begrenzingen. En dus zijn de twee volgende zinnen B<verschillend>. De tweede
zal slechts gevonden worden als er in het vertaalde document voldoende
nakomende spaties zijn.

 PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>
 PO4A-HEADER: position=About this document ; mode=after; beginboundary=<section>

=item

Hoewel ruwweg zou kunnen aangenomen worden dat deze contextzoekfunctie werkt
op elke regel van het B<vertaalde> document, werkt het in feite op de
interne gegevensreeks van het vertaalde document. Deze interne gegevensreeks
kan een tekst zijn die een volledige alinea beslaat en meerdere regels
bevat, of kan ook enkel een XML-tag zijn. Het exacte I<invoegpunt> van het
addendum moet voor of na de interne gegevensreeks komen en kan er niet
binnenin liggen.

=item

Geef het argument C<-vv> op aan B<po4a> om te zien hoe de addenda aan de
vertaling worden toegevoegd. Dit kan ook behulpzaam zijn voor het uitvoeren
van B<po4a> in debug-modus om de exacte gegevensreeks te bekijken wanneer
het addendum niet toegevoegd wordt.

=back

=head3 Voorbeelden van addenda

=over

=item

Indien u na de volgende nroff-sectie iets wilt toevoegen:

  .SH "AUTHORS"

U moet een benadering in twee stappen selecteren door B<mode = after> in te
stellen. Vervolgens moet u de zoekopdracht beperken tot de regel na
B<AUTEURS> met de reguliere expressie voor het argument B<position>. Daarna
moet u het begin van de volgende sectie (d.w.z. B<^\.SH>) laten opzoeken met
de reguliere expressie voor het argument B<beginboundary>. Het is te zeggen:

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

=item

Indien u iets wilt toevoegen vlak na een bepaalde regel (bijv. na de regel
"Copyright Grote Kerel"), gebruik dan een B<position> die met deze regel
overeenkomt, B<mode=after> en geef een B<beginboundary> op die met om het
even welke regel overeenkomt.

 PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^

=item

Indien u iets wilt toevoegen aan het einde van het document, geef dan een
B<position> op die overeenkomt met om het even welke regel van uw document
(maar enkel één regel, omdat po4a niet zal aanvaarden dat de B<position>
niet met één enkele regel overeenkomt), en geef een B<endboundary> op die
met niets overeenkomt. Gebruik hier geen eenvoudige tekenreeks, zoals
B<"EOF">, maar geef de voorkeur aan die welke minder kans maken om in uw
document voor te komen.

 PO4A-HEADER:mode=after;position=About this document;beginboundary=FakePo4aBoundary

=back

=head3 Een meer gedetailleerd voorbeeld

Origineel document (POD-indeling):

 |=head1 NAME
 |
 |dummy - a dummy program
 |
 |=head1 AUTHOR
 |
 |me

Dan zal het volgende addendum ervoor zorgen dat een sectie (in het Frans)
over de vertaler toegevoegd wordt aan het eind van het bestand ("TRADUCTEUR"
in het Frans betekent "VERTALER", en "moi" betekent "ik").

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

Om uw addendum voor de AUTEUR te plaatsen, gebruikt u de volgende header:

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

Dit werkt omdat de volgende regel die overeenkomt met de B<beginboundary>
C</^=head1/> na de sectie "NAME" (vertaald als "NAAM" in het Nederlands),
die is welke de auteurs vermeldt. Dus zal het addendum tussen de beide
secties geplaatst worden. Merk op dat indien later een andere sectie
toegevoegd wordt tussen de secties NAAM en AUTEUR, po4a de addenda ten
onrechte zal plaatsen voor de nieuwe sectie.

Om dit te vermijden, kunt u hetzelfde bereiken met behulp van
B<mode>=I<before>:

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

=head1 Hoe werkt dit?

Dit hoofdstuk geeft u een kort overzicht van de binnenkant van po4a, zodat u
met meer zelfvertrouwen ons kunt helpen het te onderhouden en te
verbeteren. Het kan u ook helpen te verstaan waarom het niet doet wat u
verwachtte en hoe u uw problemen kunt oplossen.

=head2 TransTractors en projectarchitectuur

In de kern van het po4a-project is de klasse
L<Locale::Po4a::TransTractor(3pm)|TransTractor> de gemeenschappelijke
voorouder van alle po4a-ontleders. Deze vreemde naam komt door het feit dat
het tegelijk belast is met de vertaling van het document en het extraheren
van tekstfragmenten.

Meer formeel neemt het als invoer een te vertalen document plus een
PO-bestand dat de te gebruiken vertalingen bevat en produceert het twee
aparte uitvoerbestanden: een ander PO-bestand (als resultaat van de
extractie van vertaalbare tekstfragmenten uit het invoerdocument) en een
vertaald document (met dezelfde structuur als het invoerdocument, maar
waarin alle vertaalbare tekstfragmenten vervangen werden met inhoud uit het
invoer-PO-bestand). Hier volgt een grafische voorstelling ervan:

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

Dit kleine botje vormt de kern van de hele po4a-architectuur. Als u zowel
invoer verstrekt als de uitvoer-PO negeert, krijgt u B<po4a-translate>. Als
u in plaats daarvan het uitvoerdocument negeert, krijgt u
B<po4a-updatepo>. Het programma B<po4a> gebruikt een eerste TransTractor om
een actueel uitvoer-POT-bestand te verkrijgen (waarbij de uitvoerdocumenten
buiten beschouwing worden gelaten), roept B<msgmerge -U> aan om de
vertaal-PO-bestanden op schijf bij te werken en bouwt een tweede
TransTractor met deze bijgewerkte PO-bestanden om de uitvoerdocumenten bij
te werken. Kortom, B<po4a> biedt een totaaloplossing om bij te werken wat
bijgewerkt moet worden, met behulp van één enkel configuratiebestand.

B<po4a-gettextize> gebruikt ook twee TransTractors, maar op een andere
manier: het bouwt één TransTractor per taal en bouwt vervolgens een nieuw
PO-bestand met de msgid's van het originele document als msgid's, en de
msgid's van het vertaalde document als msgstr's. Er is veel zorg nodig om te
verzekeren dat de tekenreeksen waartussen op deze manier een overeenkomst
gevonden wordt ook daadwerkelijk overeenkomen, zoals beschreven in
L<po4a-gettextize(1)>.

=head2 Indelingsspecifieke ontleders

Alle po4a-indelingsontleders zijn bovenop de TransTractor
geïmplementeerd. Sommige zijn heel eenvoudig, zoals die van Text, Markdown
en AsciiDoc. Ze laden de regels één voor één met behulp van
C<TransTractor::shiftline()>, verzamelen de inhoud van de alinea's of wat
dan ook. Zodra een tekenreeks volledig is ontleed, gebruikt de ontleder
C<TransTractor::translate()> om (1) deze tekenreeks toe te voegen aan het
uitvoer-PO-bestand en (2) de vertaling op te halen uit het
invoer-PO-bestand. De ontleder duwt het resultaat vervolgens naar het
uitvoerbestand met behulp van C<TransTractor::pushline()>.

Sommige andere ontleders zijn complexer omdat ze afhankelijk zijn van een
externe ontleder om het invoerdocument te analyseren. De Xml-, HTML-, SGML-
en Pod-ontleders zijn gebouwd bovenop SAX-ontleders. Ze declareren
terugroepfuncties naar gebeurtenissen zoals "Ik heb een nieuwe titel
gevonden met de volgende inhoud" om het uitvoerdocument bij te werken en
POT-bestanden uit te voeren op basis van de invoerinhoud met behulp van
C<TransTractor::translate()> en C<TransTractor::pushline()>. De
Yaml-ontleder is vergelijkbaar maar anders: deze serialiseert een
datastructuur geproduceerd door de ontleder YAML::Tiny. Dit is de reden
waarom de Yaml-module van po4a de referentieregels niet kan declareren: de
locatie van elke tekenreeks in het invoerbestand wordt niet bijgehouden door
de ontleder en dus kunnen we alleen "$bestandsnaam:1" opgeven als de locatie
van een tekenreeks. De SAX-georiënteerde ontleders gebruiken globale
variabelen en andere trucs om de bestandsnaam en regelnummers van
referenties op te slaan.

Een specifiek probleem ontstaat door bestandscoderingen en
BOM-markeringen. Eenvoudige ontleders kunnen dit probleem negeren omdat het
wordt afgehandeld door C<TransTractor::read()> (intern gebruikt om de regels
van een invoerdocument op te halen), maar de modules die afhankelijk zijn
van een externe ontleder moeten ervoor zorgen dat alle bestanden worden
gelezen met een geschikte PerlIO-decoderingslaag. Het eenvoudigste is om het
bestand zelf te openen en een bestandsaanduiding of rechtstreeks de
volledige tekenreeks mee te geven aan de externe ontleder. Kijk eens naar
C<Pod::read()> en C<Pod::parse()> voor een voorbeeld. De inhoud die wordt
gelezen door de TransTractor wordt genegeerd, maar een nieuwe
bestandsaanduiding wordt doorgegeven aan de externe ontleder. Het
belangrijke onderdeel is de modus C<< "<:encoding($charset)" >> die wordt
doorgegeven aan de perl-functie B<open()>.

=head2 Po-objecten

De klasse L<Locale::Po4a::Po(3pm)|Po> is verantwoordelijk voor het laden en
gebruiken van PO- en POT-bestanden. Kortom, u kunt een bestand lezen,
vermeldingen toevoegen, vertalingen ophalen met de B<gettext()>-methode,en
de PO naar een bestand schrijven. Meer geavanceerde functies, zoals het
samenvoegen van een PO-bestand met een POT-bestand of het valideren van een
bestand, worden respectievelijk aan B<msgmerge> en B<msgfmt> gedelegeerd.

=head2 Meewerken aan po4a

Zelfs als u nog nooit hebt bijgedragen aan een openbronproject, bent u
welkom: we zijn bereid om u hier te helpen en te begeleiden. po4a wordt
tegenwoordig het best onderhouden door zijn gebruikers. Omdat we te weinig
mankracht hebben, proberen we het project gastvrij te maken door de
documentatie en de automatische tests te verbeteren, zodat u met vertrouwen
kunt bijdragen aan het project. Raadpleeg het bestand CONTRIBUTING.md voor
meer details.

=head1 Openbronprojecten die po4a gebruiken

Hier volgt een zeer gedeeltelijke lijst met projecten die po4a in productie
gebruiken voor hun documentatie. Indien u wenst dat uw project wordt
toegevoegd aan de lijst, stuur dan gewoon een e-mail (of een Merge Request).

=over

=item

adduser (man): gereedschap voor het beheer van gebruikers en groepen.

=item

apt (man, docbook): pakketbeheerder in Debian.

=item

aptitude (docbook, svg): terminalgeoriënteerd pakketbeheerhulpmiddel voor
Debian

=item

L<F-Droid website|https://gitlab.com/fdroid/fdroid-website> (markdown):
installeerbare catalogus van FOSS (Free and Open Source Software - Vrije en
openbronsoftware) toepassingssoftware voor het Android-platform.

=item

L<git|https://github.com/jnavila/git-manpages-l10n> (asciidoc):
gedistribueerd versiebeheersysteem voor het volgen van wijzigingen in de
broncode.

=item

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

Dit project voorziet in een infrastructuur voor het vertalen van veel
man-pagina's naar verschillende talen, klaar om geïntegreerd te worden in
verschillende belangrijke distributies (Arch Linux, Debian en derivativen,
Fedora).

=item

L<Stellarium|https://github.com/Stellarium/stellarium> (HTML): een vrij
openbronplanetarium voor uw computer. po4a wordt gebruikt om de beschrijving
van de lucht en de hemellichamen in verschillende culturen, te vertalen.

=item

L<Jamulus|https://jamulus.io/> (markdown, yaml, HTML): een FOSS-toepassing
voor online jammen in realtime. De documentatie van de website wordt in
meerdere talen onderhouden met po4a.

=item

Ander uit te zoeken item: L<https://gitlab.com/fdroid/fdroid-website/>
L<https://github.com/fsfe/reuse-docs/pull/61>

=back

=head1 FAQ

=head2 Hoe spreekt men po4a uit?

Zelf spreek ik het uit als L<pouah|https://en.wiktionary.org/wiki/pouah>,
wat een Franse klanknabootsing is die men gebruikt voor bah :) Misschien heb
ik een vreemd gevoel voor humor :)

=head2 Waarom zijn de afzonderlijke scripts achterhaald?

B<po4a-updatepo> en B<po4a-translate> werden inderdaad uitgefaseerd ten
gunste van B<po4a>. De reden is dat, hoewel B<po4a> kan worden gebruikt als
een directe vervanging voor deze scripts, men er behoorlijk veel
codeduplicatie in aantreft. Individuele scripts bestaan uit ongeveer 150
regels code, terwijl het programma B<po4a> 1200 regels code bevat. Deze code
doet dus veel meer dan de interne onderdelen die beide gemeenschappelijk
hebben. Het dupliceren van code resulteert in bugs die in beide versies
voorkomen en waarvoor twee oplossingen nodig zijn. Een voorbeeld van een
dergelijke duplicatie zijn de bugs #1022216 in Debian en de kwestie #442 in
GitHub die exact dezelfde oplossing hadden, maar één in B<po4a> en de andere
B<po4a-updatepo>.

Op de lange termijn zou ik de individuele scripts willen laten vallen en
slechts één versie van deze code behouden. Het is zeker dat de individuele
scripts niet meer zullen worden verbeterd. Dus alleen B<po4a> zal nog nieuwe
functionaliteit krijgen. Dat gezegd hebbende, is er geen sprake van urgentie
wat de uitfasering betreft. Ik ben van plan de individuele scripts zo lang
mogelijk te behouden, en in ieder geval tot 2030. Mocht uw project in 2030
nog steeds B<po4a-updatepo> en B<po4a-translate> gebruiken, dan heeft u
mogelijk een probleem.

We kunnen op een gegeven moment ook de uitfasering van deze scripts
annuleren, als een herwerking de codeduplicatie tot nul kan reduceren. Als u
een idee heeft (of beter, een patch), is uw hulp welkom.

=head2 Hoe zit het met de andere vertaalhulpmiddelen voor documentatie die gebruik
maken van gettext?

Er zijn er een paar. Hier is een mogelijk onvolledige lijst, en er
verschijnen meer hulpmiddelen aan de horizon.

=over

=item B<poxml>

Dit gereedschap werd ontwikkeld door mensen van KDE om DocBook XML te
verwerken. Voor zover ik weet was dit het eerste programma dat te vertalen
tekstfragmenten uit documentatie extraheerde naar PO-bestanden en deze na
vertaling terug injecteerde.

Het kan enkel XML verwerken, en enkel een specifieke DTD. Ik ben erg
ongelukkig met de verwerking van lijsten welke terechtkomen in één grote
msgid. Wanneer de lijst groot wordt, is het moeilijker die brok door te
slikken.

=item B<po-debiandoc>

Dit door Denis Barbier gemaakt programma is een soort voorloper van de
SGML-module van po4a, waardoor het min of meer achterhaald werd. Zoals de
naam het zegt, verwerkt het enkel de DebianDoc DTD, hetgeen min of meer een
achterhaalde DTD is.

=item B<xml2po.py>

Wordt gebruikt door het GIMP-documentatieteam sinds 2004. Het werkt redelijk
goed, zij het, zoals de naam al doet vermoeden, alleen met XML-bestanden, en
het heeft speciaal geconfigureerde makefiles nodig.

=item B<Sphinx>

Ook het documentatieproject van Sphinx maakt veelvuldig gebruik van gettext
om zijn vertalingen te beheren. Helaas werkt dit hulpmiddel slechts voor
enkele tekstformaten, voor rest en voor markdown, hoewel het misschien wel
het enige hulpmiddel is dat dit beheren van het hele vertaalproces op zich
neemt.

=back

De belangrijkste voordelen van po4a tegenover hen zijn het gemak waarmee
extra inhoud toegevoegd kan worden (wat bij deze andere hulpmiddelen nog
moeilijker is) en de mogelijkheid een gettextize-procedure uit te voeren.

=head2 SAMENVATTING van de voordelen van een op gettext gebaseerde benadering

=over 2

=item

De vertalingen worden niet samen met het origineel opgeslagen, wat het
mogelijk maakt na te gaan of vertalingen verouderd beginnen te raken.

=item

De vertalingen worden in aparte bestanden opgeslagen, wat interferentie
tussen vertalers van verschillende talen voorkomt, zowel wanneer deze hun
patch indienen als bij de keuze van de tekstcodering van de bestanden.

=item

Intern is het gebaseerd op B<gettext> (maar B<po4a> biedt een heel
eenvoudige interface, zodat u de interne werking niet moet kennen om het te
gebruiken). Op die manier moeten we het wiel niet terug uitvinden, en omdat
dit gereedschap zo ruim gebruikt wordt, mogen we aannemen dat het min of
meer vrij van fouten is.

=item

Voor de eindgebruiker verandert er niets (behalve het feit dat vertalingen
hopelijk beter onderhouden zullen worden). Het resulterende
documentatiebestand dat verspreid wordt, is exact hetzelfde.

=item

Vertalers moeten geen nieuwe bestandsyntaxis leren en hun favoriete editor
voor PO-bestanden (zoals de PO-modus in Emacs, Lokalize of Gtranslator)
voldoet perfect.

=item

gettext biedt een eenvoudige manier om statistieken te bekomen over het
gepresteerde werk, over wat nazicht en een update nodig heeft en over wat er
nog moet gebeuren. Enkele voorbeelden zijn te vinden op deze adressen:

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

=back

Maar niet alles is rozengeur en deze aanpak heeft ook enkele nadelen waarmee
we moeten omgaan.

=over 2

=item

Addenda zijn op het eerste gezicht wat vreemd.

=item

Het is niet mogelijk om de vertaalde tekst naar uw smaak aan te passen,
zoals hier een paragraaf opsplitsen en er daar twee andere samenvoegen. Maar
in zekere zin moet het hoe dan ook als een bug gemeld worden, wanneer er een
probleem is met het origineel.

=item

Zelfs met een gemakkelijke interface blijft het een nieuw gereedschap dat
mensen moeten leren gebruiken.

Een van mijn dromen is om po4a op een of andere manier te integreren in
Gtranslator of Lokalize. Wanneer een documentatiebestand geopend wordt,
zouden de tekstfragmenten automatisch geëxtraheerd worden en een vertaald
bestand + po-bestand zouden naar schijf geschreven worden. Indien we erin
zouden slagen een MS Word(TM)-module te ontwikkelen (of minstens een
RTF-module), zouden zelfs professionele vertalers er gebruik van maken.

=back

=head1 ZIE OOK

=over

=item

De documentatie over het alles-in-één gereedschap dat u zou moeten
gebruiken: L<po4a(1)>.

=item

De documentatie van de individuele po4a-scripts: L<po4a-gettextize(1)>,
L<po4a-updatepo(1)>, L<po4a-translate(1)>, L<po4a-normalize(1)>.

=item

De extra ondersteunende scripts: L<msguntypot(1)>, L<po4a-display-man(1)>,
L<po4a-display-pod(1)>.

=item

The parsers of each formats, in particular to see the options accepted by
each of them: L<Locale::Po4a::AsciiDoc(3pm)> L<Locale::Po4a::Dia(3pm)>,
L<Locale::Po4a::Gemtext(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::Org(3pm)>, L<Locale::Po4a::Pod(3pm)>,
L<Locale::Po4a::SimplePod(3pm)>, L<Locale::Po4a::Sgml(3pm)>,
L<Locale::Po4a::TeX(3pm)>, L<Locale::Po4a::VimHelp>,
L<Locale::Po4a::Wml(3pm)>, L<Locale::Po4a::Xml(3pm)>.

=item

De implementatie van de basisinfrastructuur::
L<Locale::Po4a::TransTractor(3pm)> (in het bijzonder van belang om de
organisatie van de code te begrijpen), L<Locale::Po4a::Chooser(3pm)>,
L<Locale::Po4a::Po(3pm)>, L<Locale::Po4a::Common(3pm)>. Bekijk ook het
bestand F<CONTRIBUTING.md> in de broncodeboom.

=back

=head1 AUTEURS

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