Zawijanie tekstu¶

Teksty niewciętych akapitów są automatycznie zawijane dla wygody tłumacza. Może to prowadzić do niewielkich różnic w wygenerowanym pliku wyjściowym, ponieważ reguły zawijania tekstu używane przez groffa nie są jasne - na przykład czasami groff zachowuje dwie spacje występujące po nawiasie.

Tak czy owak, różnica będzie dotyczyła tylko rozmieszczenia dodatkowych spacji w zawiniętym tekście akapitu.

Określanie czcionki¶

Pierwsza zmiana dotyczy specyfikacji zmian czcionek. W nroffie istnieje kilka sposobów określenia, że podane słowo powinno być napisane czcionką małą, wytłuszczoną lub kursywą. W tekście do przetłumaczenia można to zrobić tylko na jeden sposób, zapożyczony z formatu POD (formatu dokumentacji Perla):

I<tekst> -- kursywa

odpowiednik \fItekst\fP lub ".I tekst"

B<tekst> -- tekst wytłuszczony

odpowiednik \fBtekst\fP lub ".B tekst"

R<tekst> -- tekst zwykłą czcionką

odpowiednik \fRtekst\fP

CW<tekst<gt> -- tekst o stałej szerokości

odpowiednik \f(CWtekst\fP lub ".CW tekst"

Uwaga: CW nie jest dostępne dla wszystkich urządzeń groffa. Używanie go nie jest zalecane. Jest dostarczone dla wygody użytkownika.

Automatyczna transliteracja znaków¶

Po4a automatycznie zamienia niektóre znaki, aby ułatwić tłumaczenia lub przeglądanie tłumaczeń. Lista takich transliteracji:

łączniki

Łączniki (-) i znaki minusa (\-) w stronach podręcznika ekranowego są wszystkie transliterowane do zwykłych myślników (-) w pliku PO. Kiedy tłumaczenia są zapisywane w pliku wynikowym wszystkie myślniki są zamieniane na znaki minusa (\-).

Tłumacze mogą wymusić wstawienie łącznika, używając w swoich tłumaczeniach kodu "\[hy]" groffa.

spacje nierozdzielające

Tłumacze mogą używać nierozdzielających spacji w swoich tłumaczeniach. Takie spacje nierozdzielające (0xA0 w latin1) będą przetłumaczone jako spacje nierozdzielające roff ("\ ").

transliteracje cudzysłowów

`` i '' są odpowiednio zamieniane na \*(lq i \*(rq.

Aby uniknąć tych transliteracji, tłumacze mogą umieścić zerowej szerokości znak roffa (np. używając odpowiednio `\&` lub '\&').

Wstawianie "<" i ">" w tłumaczeniach¶

Ponieważ znaki te są używane do oddzielania części objętych zmianą czcionki, nie można ich używać wprost. Zamiast nich trzeba użyć E<lt> i E<gt> (jak w POD, po raz kolejny).

Nie programuj w nroffie¶

nroff jest kompletnym językiem programowania z definicjami makr, instrukcjami warunkowymi itd. Ponieważ parser nie jest pełnowartościowym interpreterem nroffa, zwróci błąd podczas przetwarzania stron zawierających te właściwości. (Na moim komputerze jest około 200 takich stron).

Używaj prostego zbioru makr¶

Wciąż istnieje kilka makr, których po4a nie obsługuje. Dzieje się tak dlatego, że nie znalazłem żadnej dokumentacji tych makr. Poniżej jest lista nieobsługiwanych makr znalezionych na moim komputerze. Proszę zauważyć, że ta lista nie jest pełna, ponieważ program kończy się, zwracając błąd, już po napotkaniu pierwszego nieznanego makra. Jeśli masz jakieś informacje o niektórych z nich, z przyjemnością dopiszę ich obsługę. Z powodu tych makr około 250 stron na moim komputerze nie jest dostępnych dla 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

Ukrywanie tekstu przez po4a¶

Czasem autor wie, że niektóre części strony podręcznika nie powinny być tłumaczone, więc nie powinny być przetwarzane przez po4a. Na przykład opcja może pobierać argument other oraz other może się także pojawić jako ostatni element listu. Pierwsze other nie powinno być tłumaczone, a drugie - powinno.

W takim przypadku, aby po4a pominęło takie komunikaty, autor może użyć specjalnych konstrukcji groffa:

 .if !'po4a'hide' .B other

(wymaga to podania opcji -o groff_code=verbatim)

Aby to zautomatyzować, można zdefiniować nowe makro: .de IR_untranslated
. IR \\$@
..

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

(wymaga to podania opcji -o groff_code=verbatim i -o untranslated=IR_untranslated; przy tej konstrukcji warunek .if !'po4a'hide' staje się zbędny, ponieważ po4a nie przetwarza wnętrza definicji makra)

lub używając aliasu:
.als IR_untranslated IR

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

Wymaga to podania opcji -o untranslated=als,IR_untranslated.

Wniosek¶

Podsumowując tę sekcję, pamiętaj, żeby tworzyć proste strony podręcznika ekranowego i nie starać się być zbyt pomysłowym. Roff pozwala na wiele rzeczy, które nie są obsługiwane przez parser. Na przykład: nie rób bałaganu, używając \c do przerwania przetwarzania tekstu (jak to robi 40 stron podręcznika na moim komputerze). Albo: argumenty makr umieszczaj w tej samej linii, co samo makro. Wiem, że nroff dopuszcza rozdzielanie makr i ich argumentów, ale obsługiwanie tego zbytnio by skomplikowało parser.

Oczywiście inną możliwością jest użycie innego formatu, bardziej przyjaznego tłumaczom (jak POD używający po4a::pod albo jednego z rodziny XML, np. SGML), ale nie jest to potrzebne dzięki po4a::man. Jeśli formatem źródłowym Twojej dokumentacji jest POD lub XML, to byłoby mądre, aby przetłumaczyć źródłowy format, a nie ten wygenerowany. W większości wypadków po4a::man rozpozna wygenerowane strony i wypisze odpowiednie ostrzeżenie. A nawet odmówi przetwarzana stron wygenerowanych przez POD, ponieważ te strony są perfekcyjnie obsługiwane przez po4a::pod i ponieważ ich odpowiednik nroffa generuje wiele nowych makr, których nie chcę obsługiwać. Na moim komputerze 1432 spośród 4323 stron jest wygenerowanych z formatu POD i będzie zignorowanych przez po4a::man.

W większości wypadków, po4a::man wykryje problem i odmówi przetwarzania strony, wypisując odpowiedni komunikat. W kilku rzadkich wypadkach, program zakończy się bez żadnego ostrzeżenia, ale plik wynikowy będzie niepoprawny. Takie sytuacje są nazywane "błędami";) Jeśli spotkasz się z taką sytuacją, proszę to zgłosić wraz z odpowiednią poprawką, jeśli to możliwe…