Provided by: po4a_0.73-2ubuntu1_all 
NAAM
Locale::Po4a::Man - man-pagina's van/naar PO-bestanden converteren
BESCHRIJVING
Het doel van het project po4a (PO voor alles) is om de vertaalwerkzaamheden (en interessanter nog, het
onderhoud van vertalingen) te vergemakkelijken met behulp van gettext-hulpmiddelen in domeinen waarin
deze niet meteen verwacht worden, zoals documentatie.
Locale::Po4a::Man is een module ter ondersteuning van de vertaling van documentatie in de nroff-indeling
(de taal die voor man-pagina's gebruikt wordt) naar andere [menselijke] talen.
VERTALEN MET PO4A::MAN
Deze module doet er alles aan om het leven van de vertaler gemakkelijker te maken. Daarvoor is de tekst
die aan vertalers wordt voorgelegd geen letterlijke kopie van de tekst van de man-pagina. De ruwere
onderdelen van de nroff-indeling worden inderdaad verborgen gehouden, zodat vertalers ze niet kunnen
verknoeien.
Regelafbreking
Op paragrafen die niet inspringen wordt ten behoeve van vertalers automatisch regelafbreking toegepast.
Dit kan leiden tot een aantal minimale verschillen in de gegenereerde uitvoer, omdat de regels voor
regelafbreking welke door groff gebruikt worden, niet erg duidelijk zijn. Bijvoorbeeld worden twee
spaties na een haakje soms behouden.
Hoe dan ook zit het verschil enkel in de positie van de extra spaties in de inspringende alinea, en ik
denk dat het dit waard is.
Lettertypespecificatie
De eerste wijziging betreft specificaties voor het wijzigen van lettertypes. In nroff zijn er
verschillende manieren om aan te geven of een bepaald woord moet geschreven worden in klein, vet of
schuin lettertype. In de te vertalen tekst is er slechts één manier, ontleend aan de POD-indeling (de
indeling voor onlinedocumentatie van Perl):
I<tekst> -- schuine tekst
het equivalent van \fItekst\fP of ".I tekst"
B<tekst> -- tekst in het vet
het equivalent van \fBtekst\fP of".B tekst"
R<tekst> -- tekst in Romeins lettertype
het equivalent van \fRtekst\fP
CW<tekst> -- tekst met constante breedte
het equivalent van \f(CWtekst\fP of ".CW tekst"
Opmerking: niet voor alle groff-apparaten is het lettertype CW beschikbaar. Het gebruik ervan wordt niet
aanbevolen. Het is bedoeld voor uw gemak.
Automatisch omzetten van lettertekens
Po4a doet een automatische omzetting van sommige lettertekens om de vertaling en het nazicht ervan te
vergemakkelijken. Hier volgt de lijst van omzettingen:
koppeltekens
Koppeltekens (-) en mintekens (\ -) in man-pagina's worden allemaal omgezet naar eenvoudige streepjes
(-) in het PO-bestand. Daarna worden alle streepjes omgezet naar roff-mintekens wanneer de vertaling
ingevoegd wordt in het uitvoerdocument.
Vertalers kunnen een koppelteken afdwingen door in hun vertaling het roff-letterteken '\[hy]' te
gebruiken.
spatie zonder regelafbreking
Vertalers kunnen in hun vertaling gebruik maken van spaties waarbij geen regelafbreking mag toegepast
worden. Deze spaties zonder regelafbreking (0xA0 in latin1) zullen naar roff omgezet worden als een
spatie zonder regelafbreking ('\ ').
omzetting van aanhalingstekens
`` en '' worden respectievelijk omgezet naar \*(lq en \*(rq.
Om deze omzettingen te voorkomen kunnen vertalers een roff-teken met een breedte nul invoegen (met
name door respectievelijk `\&` of '\&' te gebruiken).
In vertalingen '<' en '>' gebruiken
Aangezien deze tekens worden gebruikt om delen af te bakenen waarvoor een wijziging van het lettertype
van toepassing is, kunt u ze niet letterlijk gebruiken. Gebruik in de plaats daarvan E<lt> en E<gt>
(nogmaals zoals in POD).
MOGELIJKE OPTIES BIJ DEZE MODULE
De volgende opties zijn specifiek voor deze module:
debug
Debuggen activeren voor sommige interne mechanismen van deze module. Gebruik de broncode om na te
gaan voor welke delen debuggen mogelijk is.
verbose
De hoeveelheid verstrekte informatie verhogen.
groff_code
Deze optie controleert het gedrag van de module wanneer deze een sectie .de, .ie of .if tegenkomt. Ze
kan de volgende waarden hebben:
fail
Dit is de standaardwaarde. De module zal mislukken wanneer een sectie .de, .ie of .if
aangetroffen wordt.
verbatim
Geeft aan dat de secties .de, .ie en .if als zodanig moeten worden gekopieerd van het origineel
naar het vertaalde document.
translate
Geeft aan dat de secties .de, .ie of .if ter vertaling aangeboden zullen worden. Gebruik deze
optie alleen als er een vertaalbaar tekstfragment in een van deze secties staat. Anders zou u de
voorkeur moeten geven aan verbatim.
generated
Deze optie geeft aan dat het bestand gegenereerd werd en dat po4a niet moet proberen te achterhalen
of de man-pagina vanuit een andere indeling gegenereerd werd. Deze optie is verplicht om po4a te
gebruiken op gegenereerde man-pagina's. Merk op dat het vertalen van gegenereerde pagina's in plaats
van bronpagina's vaak kwetsbaarder is, en dus een slecht idee.
mdoc
Deze optie is enkel nuttig voor mdoc-pagina's.
Hiermee selecteert men een meer strikte ondersteuning voor de mdoc-indeling door po4a op te dragen de
sectie 'NAME' niet te vertalen. mdoc-pagina's waarvan de sectie 'NAME' vertaald wordt, krijgen geen
header en footer.
Volgens de man-pagina groff_mdoc zijn de secties NAME, SYNOPSIS en DESCRIPTION verplicht. Er zijn
geen problemen bekend met een vertaalde sectie SYNOPSIS of DESCRIPTION, maar u kunt deze secties ook
op deze manier aanduiden:
-o mdoc=NAME,SYNOPSIS,DESCRIPTION
Dit mdoc-probleem kan ook opgelost worden met een addendum zoals dit:
PO4A-HEADER:mode=before;position=^.Dd
.TH DOCUMENT_TITLE 1 "Month day, year" OS "Section Name"
De volgende opties bepalen het gedrag van een door de gebruiker gedefinieerde macro (met een .de-verzoek)
of van een klassieke macro welke niet door po4a ondersteund wordt. Zij hebben als argument een door
komma's gescheiden lijst met macro's. Bijvoorbeeld:
-o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX
Opmerking: indien een macro niet ondersteund wordt door po4a en als u van mening bent dat het om een
standaard roff-macro gaat, signaleer dit dan aan het team ontwikkelaars van po4a.
untranslated
untranslated Geeft aan dat deze macro (en zijn argumenten) niet vertaald moet worden.
noarg
noarg is zoals untranslated, behalve dat po4a zal verifieren dat er geen argument meegegeven werd aan
deze macro.
translate_joined
translate_joined geeft aan dat po4a de argumenten van de macro ter vertaling moet voorleggen.
translate_each
Met translate_each zullen de argumenten ook ter vertaling voorgelegd worden, met dat verschil dat elk
argument afzonderlijk zal vertaald worden.
no_wrap
Deze optie krijgt als argument een lijst van door komma's gescheiden paren van begin:einde, waarbij
begin en einde commando's zijn welke het begin en het einde afbakenen van een sectie waarvoor de
regelafbreking niet overgedaan moet worden.
Opmerking: er wordt geen test uitgevoerd om ervoor te zorgen dat een einde-commando met zijn
begin-commando overeenkomt. Elk einde-commando beëindigt de no_wrap-modus. Indien u een begin-macro
(respectievelijk einde-macro) heeft, welke geen einde-macro (respectievelijk begin-macro) heeft, kunt
u als tegenhanger een bestaand einde (als fi) of een bestaand begin (als nf) opgeven. Deze macro's
(en hun argumenten) zullen niet vertaald worden.
inline
Deze optie specificeert een lijst met door komma's gescheiden macro's die geen splitsing van de
huidige alinea mogen veroorzaken. Het te vertalen tekstfragment bevat dan foo <.bar baz qux> quux,
waarbij bar het commando is dat ongesplitst moet blijven, en baz qux zijn argumenten.
unknown_macros
Deze optie geeft aan hoe po4a zich moet gedragen wanneer een onbekende macro wordt aangetroffen.
Standaard faalt po4a met een waarschuwing. Deze kan de volgende waarden hebben: failed (gefaald) (de
standaardwaarde), untranslated, noarg, translate_joined, or translate_each (zie hierboven voor een
uitleg bij deze waarden).
MAN-PAGINA'S SCHRIJVEN WELKE COMPATIBEL ZIJN MET PO4A::MAN
Deze module is nog erg beperkt, en zal dat ook altijd zijn, want het is geen echte interpreter voor
nroff. Een echte nroff-interpreter maken, wat auteurs de mogelijkheid zou bieden om alle bestaande
macro's te gebruiken en er zelfs nieuwe te definiëren in hun pagina's, zou mogelijk zijn, maar dit wilden
we niet. Dit zou te moeilijk zijn en we dachten dat het niet nodig was. We denken dat als auteurs van
man-pagina's hun producten vertaald willen zien, ze zich misschien moeten aanpassen om het werk van
vertalers te vergemakkelijken.
En dus heeft de man-paginaontleder die in po4a geïmplementeerd werd, enkele bekende beperkingen, welke we
niet echt geneigd zijn te verbeteren en welke een aantal valkuilen vormen die u zult moet vermijden als u
wilt dat vertalers zich om uw documentatie bekommeren.
Programmeer niet in nroff
nroff is een volledige programmeertaal met macrodefinities, conditionele bewerkingen, enz. Omdat deze
ontleder geen volwaardige nroff-interpreter is, zal hij falen bij pagina's welke van deze voorzieningen
gebruik maken (Op mijn computer staan ongeveer 200 dergelijke pagina's).
Gebruik de gewone macroset
Er zijn nog steeds enige macro's die niet ondersteund worden door po4a::man. Dit is enkel omdat ik er
geen enkele documentatie over kon vinden. Hier volgt de lijst van niet-ondersteunde macro's die op mijn
computer gebruikt worden. Merk op dat deze lijst niet exhaustief is, omdat het programma faalt bij de
eerste niet-ondersteunde macro die het tegenkomt. Indien u enige informatie heeft over sommige van deze
macro's, ben ik graag bereid er ondersteuning voor toe te voegen. Omwille van deze macro's zijn ongeveer
250 pagina's op mijn computer niet toegankelijk voor po4a::man.
.. ." .AT .b .bank
.BE ..br .Bu .BUGS .BY
.ce .dbmmanage .do .En
.EP .EX .Fi .hw .i
.Id .l .LO .mf
.N .na .NF .nh .nl
.Nm .ns .NXR .OPTIONS .PB
.pp .PR .PRE .PU .REq
.RH .rn .S< .sh .SI
.splitfont .Sx .T .TF .The
.TT .UC .ul .Vb .zZ
Tekst verborgen houden voor po4a
Soms weet de auteur dat sommige delen niet vertaalbaar zijn en niet geëxtraheerd zouden moeten worden
door po4a. Bijvoorbeeld kan het zijn dat een optie het argument other kent en dat other ook voorkomt als
laatste item van een lijst. In het eerste geval zou other niet-vertaalbaar moeten zijn. Maar in het
tweede geval zou other wel vertaald mogen worden.
In een dergelijk geval kan de auteur vermijden dat po4a bepaalde tekstfragmenten extraheert, door gebruik
te maken van enkele speciale groff-constructen:
.if !'po4a'hide' .B other
(dit vereist de optie -o groff_code=verbatim)
Er kan ook een nieuwe macro gedefinieerd worden om dit te automatiseren:
.de IR_untranslated
. IR \\$@
..
.IR_untranslated \-q ", " \-\-quiet
(dit vereist de opties -o groff_code=verbatim en -o untranslated=IR_untranslated; met dit construct is de
voorwaarde .if !'po4a'hide' niet strikt noodzakelijk, omdat po4a de binnenkant van de macrodefinitie niet
zal ontleden)
of door een alias te gebruiken:
.als IR_untranslated IR
.IR_untranslated \-q ", " \-\-quiet
Dit vereist de optie -o untranslated=als,IR_untranslated.
Besluit
Bij wijze van samenvatting voor dit onderdeel zou men kunnen zeggen: hou het eenvoudig en tracht niet de
slimmerik uit te hangen bij het schrijven van uw man-pagina's. Er zijn veel dingen mogelijk in nroff,
welke niet ondersteund worden door deze ontleder. Probeer bijvoorbeeld niet te spelen met \c om de
tekstverwerking te onderbreken (zoals 40 pagina's op mijn computer doen). En zorg ervoor de
macroargumenten op dezelfde regel te plaatsen als de macro zelf. Ik weet dat dergelijke zaken toegestaan
zijn in nroff, maar het zou de ontleder te complex maken om daarmee om te gaan.
Een andere mogelijkheid is natuurlijk om een andere indeling te gebruiken die meer vertalervriendelijk is
(zoals POD en daarvoor po4a::pod gebruiken, of een indeling uit de XML-familie, zoals SGML), maar dankzij
po4a::man is dat niet meer nodig. Dit gezegd zijnde, als de oorspronkelijke indeling van uw documentatie
POD of XML is, kan het verstandiger zijn de vertaling vanuit deze oorspronkelijke indeling te laten
gebeuren en niet vanuit deze gegenereerde indeling. In de meeste gevallen zal po4a::man gegenereerde
pagina's ontdekken en een waarschuwing geven . Het zal zelfs weigeren om uit POD gegenereerde pagina's te
verwerken, omdat dergelijke pagina's perfect afgehandeld kunnen worden door po4a::pod, en omdat voor hun
nroff-tegenhanger een heleboel nieuwe macro's gedefinieerd worden waarvoor ik geen ondersteuning wilde
schrijven. Op mijn computer werden 1432 van de 4323 pagina's uit POD gegenereerd en deze zullen door
po4a::man genegeerd worden.
In de meeste gevallen zal po4a::man het probleem ontdekken en de pagina weigeren te verwerken en een
passende melding geven. In enkele zeldzame gevallen zal het programma de verwerking wel uitvoeren zonder
te waarschuwen, maar zal de uitvoer fout zijn. Zulke gevallen worden "bugs" genoemd ;) Indien u een
dergelijk geval tegenkomt, meld het dan zeker, samen met een reparatie, mocht dat kunnen…
STATUS VAN DEZE MODULE
Deze module kan gebruikt worden voor de meeste van de bestaande man-pagina's.
Enkele tests worden regelmatig uitgevoerd op Linux-computers:
• een derde van de pagina's wordt geweigerd omdat deze gegenereerd werden vanuit een andere indeling
(bijv. POD of SGML) die door po4a ondersteund wordt.
• 10% van de overige pagina's worden verworpen met een foutmelding (bijv. omdat een groff-macro niet
ondersteund wordt).
• Voorts wordt minder dan 1% van de pagina's stilzwijgend aanvaard door po4a, maar met belangrijke
problemen (d.w.z. ontbrekende woorden, of toevoeging van extra woorden)
• De andere pagina's worden gewoonlijk verwerkt zonder grotere verschillen dan verschillen in
spatiëring of regelafbreking (problemen met lettertypes in minder dan 10% van de verwerkte pagina's).
ZIE OOK
Locale::Po4a::Pod(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)
AUTEURS
Denis Barbier <barbier@linuxfr.org>
Nicolas François <nicolas.francois@centraliens.net>
Martin Quinson (mquinson#debian.org)
COPYRIGHT EN LICENTIE
Copyright © 2002-2008 SPI, Inc.
Dit programma is vrije software; u kunt het verder verspreiden en/of aanpassen onder de bepalingen van de
GPL v2.0 of recenter (zie het bestand COPYING).
perl v5.38.2 2024-08-28 LOCALE::PO4A::MAN.3PM(1)