Figursättning¶

Avsnitt utan indrag omformateras automatiskt för översättaren. Detta kan leda till mindre skillnader i det genererade resultatet, eftersom de omformateringsregler som används av groff inte är särskilt tydliga. Till exempel behålls ibland två mellanslag efter en parentes.

Hur som helst, skillnaden kommer bara att handla om placeringen av de extra mellanslagen i det ombrutna stycket, och jag tycker att det är värt det.

Fontspecifikation¶

Den första ändringen gäller specifikationer för teckensnittsändringar. I nroff finns det flera sätt att ange om ett visst ord ska skrivas med små bokstäver, fetstil eller kursiv stil. I texten som ska översättas finns det bara ett sätt, lånat från POD-formatet (Perl online documentation):

I<text> -- kursiv text

motsvarande \fItext\fP eller ".I text"

B<text> -- fet text

motsvarande \fBtext\fP eller ".B text"

R<text> -- roman text

motsvarande \fRtext\fP

CWE-<lt>textE-<gt> -- text med konstant bredd

motsvarande \f(CWtext\fP eller ".CW text"

Anmärkning: CW-ansiktet är inte tillgängligt för alla groff-enheter. Det rekommenderas inte att använda det. Det tillhandahålls för din bekvämlighet.

Automatisk translitterering av tecken¶

Po4a omvandlar automatiskt vissa tecken för att underlätta översättningen eller granskningen av översättningen. Här är listan över omvandlingarna:

bindestreck

Bindestreck (-) och minustecken (\-) i man-sidor translittereras alla till enkla streck (-) i PO-filen. Därefter translittereras alla streck till roff-minustecken (\-) när översättningen infogas i utdatadokumentet.

Översättare kan tvinga fram ett bindestreck genom att använda roff-tecknet '\[hy]' i sina översättningar.

icke-brytande mellanslag

Översättare kan använda fasta mellanslag i sina översättningar. Dessa fasta mellanslag (0xA0 i latin1) kommer att translittereras till ett roff-fast mellanslag ('\ ').

citat translitterationer

`` och '' translittereras respektive till \*(lq och \*(rq.

För att undvika dessa translitterationer kan översättare infoga ett roff-tecken med nollbredd (dvs. använda `\&` respektive '\&').

Att lägga till "<" och ">" i översättningar¶

Eftersom dessa tecken används för att avgränsa delar under teckensnittsmodifiering kan du inte använda dem ordagrant. Använd istället E<lt> och E<gt> (som i POD, en gång till).

Programmera inte i nroff¶

nroff är ett komplett programmeringsspråk med makrodefinitioner, villkorssatser och så vidare. Eftersom denna parser inte är en fullfjädrad nroff-tolkar kommer den att misslyckas på sidor som använder dessa funktioner (det finns cirka 200 sådana sidor på min dator).

Använd det vanliga makrosetet¶

Det finns fortfarande några makron som inte stöds av po4a::man. Detta beror endast på att jag inte har lyckats hitta någon dokumentation om dem. Här är en lista över makron som inte stöds och som används på min dator. Observera att listan inte är fullständig, eftersom programmet avbryts vid det första makrot som inte stöds. Om du har information om något av dessa makron lägger jag gärna till stöd för dem. På grund av dessa makron är cirka 250 sidor på min dator otillgängliga för 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

Dölja text från po4a¶

Ibland vet författaren att vissa delar inte är översättningsbara och inte bör extraheras av po4a. Till exempel kan en flagga acceptera ett argument other, och other kan också visas som det sista objektet i en lista. I det första fallet bör other inte vara översättningsbart. I det andra fallet bör other översättas.

I sådana fall kan författaren undvika po4a för att extrahera vissa strängar genom att använda vissa speciella groff-konstruktioner:

 .if !'po4a'hide' .B annat

(detta kräver flaggan -o groff_code=verbatim)

Ett nytt makro kan också definieras för att automatisera detta:
.de IR_untranslated
. IR \\$@
..

 .IR_untranslated \-q ", " \-\-quiet

(detta kräver flaggorna -o groff_code=verbatim och -o untranslated=IR_untranslated; med denna konstruktion är villkoret .if !'po4a'hide' inte strikt nödvändigt eftersom po4a inte kommer att analysera det interna i makrodefinitionen)

eller använda ett alias:
.als IR_untranslated IR

 .IR_untranslated \-q ", " \-\-quiet

Detta kräver flaggan -o untranslated=als,IR_untranslated.

Slutsats¶

Sammanfattningsvis: håll det enkelt och försök inte vara smart när du skriver dina man-sidor. Det finns många möjligheter i nroff, men denna parser stöder inte alla. Försök till exempel inte att använda \c för att avbryta textbearbetningen (som 40 sidor på min dator gör). Se också till att placera makroargumenten på samma rad som själva makrot. Jag vet att det är giltigt i nroff, men det skulle komplicera parsern för mycket.

En annan möjlighet är naturligtvis att använda ett annat format som är mer översättarvänligt (som POD med po4a::pod eller något av XML-familjens format, till exempel SGML), men tack vare po4a::man behövs det inte längre. Om källformatet för din dokumentation är POD eller XML kan det dock vara klokt att översätta källformatet och inte det genererade formatet. I de flesta fall kommer po4a::man att upptäcka genererade sidor och utfärda en varning. Det kommer till och med att vägra att bearbeta POD-genererade sidor, eftersom dessa sidor hanteras perfekt av po4a::pod och eftersom deras nroff-motsvarighet definierar en hel del nya makron som jag inte ville skriva stöd för. På min dator är 1432 av de 4323 sidorna genererade från POD och kommer att ignoreras av po4a::man.

I de flesta fall kommer po4a::man att upptäcka problemet och vägra att bearbeta sidan, och istället visa ett anpassat meddelande. I vissa sällsynta fall kommer programmet att slutföras utan varning, men resultatet kommer att bli felaktigt. Sådana fall kallas "buggar" ;) Om du stöter på ett sådant fall, se till att rapportera detta, tillsammans med en lösning om möjligt…