Provided by: po4a_0.69-1_all bug

NAAM

       po4a - raamwerk voor de vertaling van documentatie en ander materiaal

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.

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.

       Het doel van het po4a-project is om het werk van documentatievertalers te
       vergemakkelijken.  In het bijzonder maakt het documentatievertalingen 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 FAQ verder in dit document, voor een meer volledige lijst van de voor- en
       nadelen van deze aanpak.

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

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

       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 Locale::Po4a::AsciiDoc voor details.

       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 Locale::Po4a::Pod voor details.

       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. 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 Locale::Po4a::Sgml(3pm) voor details.

       TeX / LaTeX (voldragen ontleder)
           De LaTeX-indeling is een heel belangrijke indeling voor documentatie in de vrije-
           softwarewereld evenals voor publicaties.

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

       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.

       xml and XHMTL (vermoedelijk voldragen ontleder)
           De indeling XML is een basisindeling voor veel documentatie-indelingen.

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

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

           Zie Locale::Po4a::BibTex voor details.

       Docbook (vermoedelijk voldragen ontleder)
           Een op XML gebaseerde opmaaktaal die semantische tags gebruikt om documenten te
           beschrijven.

           Zie Locale::Po4a:Docbook voor meer details.

       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 Locale::Po4a:Guide voor meer details.

       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 Locale::Po4a::Wml voor meer details.

       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 Locale::Po4a::Yaml voor meer details.

       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 Locale::Po4a::RubyDoc voor meer details.

       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 Locale::Po4a:Halibut voor meer details.

       Ini (vermoedelijk experimentele ontleder)
           Configuratiebestandsindeling, populair geworden door MS-DOS.

           Zie Locale::Po4a::Ini voor meer details.

       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
           Locale::Po4a::Texinfo(3pm) zit nog steeds in zijn beginfase. Gelieve problemen en
           functieverzoeken te rapporteren.

       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
           (Locale::Po4a::KernelHelp) of de diagrammen die door het programma dia
           (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 Locale::Po4a::TransTractor(3pm) voor meer informatie hierover.

       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.

Het gebruik van po4a

       Oorspronkelijk werd po4a gebouwd rond vier scripts, welke elk een specifieke taak
       vervullen. po4a-gettextize(1) helpt bij het opstarten van vertalingen en eventueel bij het
       converteren van bestaande vertaalprojecten naar po4a. po4a-updatepo(1) reflecteert de
       wijzigingen in de originele documentatie in de overeenkomstige po-bestanden.
       po4a-translate(1) bouwt een vertaald bronbestand uit de originele documentatie en het
       overeenkomstige PO-bestand. Daarnaast is er po4a-normalize(1) dat vooral nuttig is voor
       het debuggen van de po4a-ontleders, omdat het een onvertaald document produceert vanuit
       het origineel. Het maakt het gemakkelijker om de door het parser-proces veroorzaakte
       probleempjes op te sporen.

       De meeste projecten hebben enkel de functionaliteit van po4a-updatepo(1) en
       po4a-translate(1) nodig, maar deze scripts bleken in het gebruik omslachtig en
       foutgevoelig te zijn. Indien de te vertalen documentatie opgesplitst is in verschillende
       bronbestanden, is het moeilijk om de PO-bestanden up-to-date te houden en de
       documentatiebestanden correct te bouwen. Als antwoord hierop wordt een
       alles-in-ééngereedschap aangereikt: po4a(1). Dit gereedschap vertrekt van een
       configuratiebestand dat de structuur van het vertaalproject beschrijft: de locatie van de
       PO-bestanden, de lijst van de te vertalen bestanden en de te gebruiken opties, en het
       automatiseert dit proces volledig. Wanneer u po4a(1) uitvoert, werkt het niet enkel de PO-
       bestanden bij, maar het regenereert ook de vertaalbestanden welke dit nodig hebben. Indien
       alles reeds up-to-date is, verandert po4a(1) geen enkel bestand.

       In de rest van dit onderdeel vindt u een overzicht over hoe de scriptinterface van po4a
       wordt gebruikt. De meeste gebruikers zullen er waarschijnlijk de voorkeur aan geven het
       alles-in-ééngereedschap te gebruiken, dat beschreven wordt in de documentatie van po4a(1).

   Grafisch overzicht van de po4a-scripts
       Het volgende schema geeft een overzicht van hoe elk po4a-script gebruikt kan worden. Hier
       is hoofddocument.doc een voorbeeldnaam voor de te vertalen documentatie; XX.doc is
       hetzelfde document, vertaald in taal XX, terwijl doc.XX.po de vertaalcatalogus van dat
       document is in taal XX. Auteurs van documentatie zullen zich hoofdzakelijk  bezighouden
       met hoofddocument.doc (dit kan een man-pagina zijn, een XML-document, een asciidoc-bestand
       of iets dergelijks). De vertalers zullen zich hoofdzakelijk bezighouden met het PO-
       bestand, terwijl de eindgebruikers uitsluitend het bestand XX.doc zullen zien.

                                          hoofddocument.doc
                                              |
                                              V
            +<-----<----+<-----<-----<--------+------->-------->-------+
            :           |                     |                        :
       {vertaling}      |         { update van hoofddocument.doc }         :
            :           |                     |                        :
          XX.doc        |                     V                        V
        (facultatief)   |              hoofddocument.doc ->-------->------>+
            :           |                   (nieuw)                      |
            V           V                     |                        |
         [po4a-gettextize]   doc.XX.po -->+   |                        |
                 |            (oud)       |   |                        |
                 |              ^         V   V                        |
                 |              |     [po4a-updatepo]                  |
                 V              |           |                          V
          vertaling.pot         ^           V                          |
                 |              |        doc.XX.po                     |
                 |              |         (onnauwkeurig)                 |
          { vertaling }         |           |                          |
                 |              ^           V                          V
                 |              |     {handmatig bewerken}              |
                 |              |           |                          |
                 V              |           V                          V
             doc.XX.po --->---->+<---<-- doc.XX.po    addendum     hoofddocument.doc
             (initieel)                 (up-to-date)  (facultatief)   (up-to-date)
                 :                          |            |             |
                 :                          V            |             |
                 +----->----->----->------> +            |             |
                                            |            |             |
                                            V            V             V
                                            +------>-----+------<------+
                                                         |
                                                         V
                                                  [po4a-translate]
                                                         |
                                                         V
                                                       XX.doc
                                                    (up-to-date)

       Dit schema is gecompliceerd, maar in de praktijk wordt enkel het rechterdeel gebruikt
       (waarbij po4a-updatepo(1) en po4a-translate(1) betrokken zijn) nadat het project opgezet
       en geconfigureerd is.

       Het linkerdeel laat zien hoe 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 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 acties van
       po4a-updatepo(1) 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 gerapporteerde 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 GNOME
       Translation Editor, KDE's Lokalize of poedit, of met een online lokalisatieplatform, zoals
       weblate of 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 po4a-translate(1) een vertaald brondocument
       creëert uit het originele document hoofddocument.doc en de vertaalcatalogus 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.

       Zoals voordien reeds aangegeven werd, combineert het programma po4a(1) de effecten van de
       aparte scripts en werkt de PO-bestanden en het vertaalde document bij in één beweging. De
       onderliggende logica blijft dezelfde.

   Beginnen met een nieuwe vertaling
       Indien u po4a(1) gebruikt, bestaat er geen specifieke stap voor het starten van een
       vertaling. U moet gewoon de talen vermelden in het configuratiebestand en de ontbrekende
       PO-bestanden worden automatisch gecreëerd. Natuurlijk moet de vertaler dan voor de
       vertaling zorgen van alle inhoud uit uw documenten. po4a(1) creëert ook een POT-bestand,
       hetgeen een PO-sjabloonbestand is. Potentiële vertalers kunnen uw project naar een nieuwe
       taal vertalen door dit bestand te hernoemen en te zorgen voor de vertaling ervan in hun
       taal.

       Indien u verkiest om de individuele scripts apart te gebruiken, moet u po4a-gettextize(1)
       als volgt gebruiken om het POT-bestand te creëren. Dit bestand kan dan gekopieerd worden
       naar XX.po om een nieuwe vertaling te starten.

         $ po4a-gettextize --format <indeling> --master <hoofddocument.doc> --po <vertaling.pot>

       Het hoofddocument wordt als invoer gebruikt, terwijl het POT-bestand de uitvoer van dit
       proces is.

   Wijzigingen in het originele document integreren
       Het script dat daarvoor gebruikt moet worden is po4a-updatepo(1) (raadpleeg de erbij
       horende documentatie voor details):

         $ po4a-updatepo --format <indeling> --master <nieuw_hoofddocument.doc> --po <oud_doc.XX.po>

       Het hoofddocument wordt gebruikt als invoer, terwijl het PO-bestand bijgewerkt wordt: het
       wordt gebruikt als invoer en als uitvoer.

   Een vertaald document genereren
       Als u klaar bent met de vertaling, wilt u de vertaalde documentatie nemen en deze samen
       met het origineel verdelen naar de gebruikers. Daarvoor moet u het programma
       po4a-translate(1) als volgt gebruiken:

         $ po4a-translate --format <indeling> --master <hoofddocument.doc> --po <doc.XX.po> --localized <XX.doc>

       Zowel het hoofddocument als de PO-bestanden worden als invoer gebruikt, terwijl het
       gelokaliseerde bestand de uitvoer is van dit proces.

   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 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 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 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 "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 "position"-argument (dit kan een reguliere expressie zijn).
       Vergeet niet dat po4a hier rekening houdt met het 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 "position" gevonden werd, zoekt po4a naar de eerstvolgende
       regel na deze "position" welke overeenkomt met de opgegeven "endboundary". Het addendum
       wordt ingevoegd net na deze regel (omdat we een 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=Over dit document; mode=after; beginboundary=<section>

       Hier zoekt po4a naar de eerste regel die overeenkomt met "<section"> na de regel die
       overeenkomt met "Over dit document" in de vertaling en voegt het addendum toe voor die
       regel, omdat we een 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 "Over dit document" voorkomt, en informeert po4a dat een sectie
       begint met een regel welke de tag "<section"> bevat. Dit is het equivalent van het vorige
       voorbeeld, want wat u eigenlijk wilt is het addendum in te voegen na "</section"> en voor
       "<section">.

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

         Modus   | Soort begrenzing |     Gebruikte begrenzing      | Invoegpunt tegenover begrenzing
        ========|===============|========================|=========================================
        'before'| 'endboundary' | laatste voor 'position' | Juist na de geselecteerde begrenzing
        'before'|'beginboundary'| laatste voor 'position' | Juist voor de geselecteerde begrenzing
        'after' | 'endboundary' | eerste na 'position' | Juist na de geselecteerde begrenzing
        'after' |'beginboundary'| eerste na 'position' | Juist voor de geselecteerde begrenzing
        'eof'   |   (geen)      |  n.v.t.                   | Einde van het bestand

       Aanwijzingen en kneepjes in verband met addenda

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

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

            PO4A-HEADER: position=Over dit document; mode=after; beginboundary=<section>
            PO4A-HEADER: position=Over dit document ; mode=after; beginboundary=<section>

       •   Hoewel ruwweg zou kunnen aangenomen worden dat deze contextzoekfunctie werkt op elke
           regel van het 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 invoegpunt van het addendum moet voor of na de interne gegevensreeks komen
           en kan er niet binnenin liggen.

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

       Voorbeelden van addenda

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

             .SH "AUTEURS"

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

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

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

            PO4A-HEADER:mode=after;position=Copyright Grote Kerel, 2004;beginboundary=^

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

            PO4A-HEADER:mode=after;position=Over dit document;beginboundary=VerzonnenPo4aBegrenzing

       Een meer gedetailleerd voorbeeld

       Origineel document (POD-indeling):

        |=head1 NAAM
        |
        |dummy - een dummy-programma
        |
        |=head1 AUTEUR
        |
        |ik

       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=NAAM;beginboundary=^=head1

       Dit werkt omdat de volgende regel die overeenkomt met de beginboundary /^=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 mode=before:

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

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.

       De po4a-architectuur is objectgeoriënteerd. De klasse Locale::Po4a::TransTractor(3pm) is
       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:

          Invoerdocument --\                             /---> Uitvoerdocument
                            \      TransTractor::       /       (vertaald)
                             +-->--   parse()  --------+
                            /                           \
          Invoer-PO --------/                             \---> Uitvoer-PO
                                                                (geëxtraheerd)

       Dit kleine botje vormt de kern van de hele po4a-architectuur. Indien u de invoer-PO en het
       uitvoerdocument weglaat, krijgt u po4a-gettextize. Indien u de beide invoerdocumenten
       geeft en de uitvoer-PO negeert, krijgt u po4a-translate. De po4a aanroept tweemaal
       TransTractor en aanroept msgmerge -U tussen deze aanroepen van TransTractor in, om een
       totaaloplossing te bieden met één configuratiebestand. Raadpleeg
       Locale::Po4a::TransTractor(3pm) voor meer details.

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

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

       •   apt (man, docbook): pakketbeheerder in Debian.

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

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

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

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

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

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

FAQ

   Hoe spreekt men po4a uit?
       Zelf spreek ik het uit als 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 :)

   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.

       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.

       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.

       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.

       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.

       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.

   SAMENVATTING van de voordelen van een op gettext gebaseerde benadering
       • De vertalingen worden niet samen met het origineel opgeslagen, wat het mogelijk maakt na
         te gaan of vertalingen verouderd beginnen te raken.

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

       • Intern is het gebaseerd op gettext (maar 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.

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

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

       • 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/

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

       • Addenda zijn… vreemd op het eerste gezicht.

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

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

ZIE OOK

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

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

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

       •   De ontleders (parsers) voor elke indeling, in het bijzonder om te zien welke opties
           voor elke van hen mogelijk zijn: Locale::Po4a::AsciiDoc(3pm) Locale::Po4a::Dia(3pm),
           Locale::Po4a::Guide(3pm), Locale::Po4a::Ini(3pm), Locale::Po4a::KernelHelp(3pm),
           Locale::Po4a::Man(3pm), Locale::Po4a::RubyDoc(3pm), Locale::Po4a::Texinfo(3pm),
           Locale::Po4a::Text(3pm), Locale::Po4a::Xhtml(3pm), Locale::Po4a::Yaml(3pm),
           Locale::Po4a::BibTeX(3pm), Locale::Po4a::Docbook(3pm), Locale::Po4a::Halibut(3pm),
           Locale::Po4a::LaTeX(3pm), Locale::Po4a::Pod(3pm), Locale::Po4a::Sgml(3pm),
           Locale::Po4a::TeX(3pm), Locale::Po4a::Wml(3pm), Locale::Po4a::Xml(3pm).

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

AUTEURS

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