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

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…