/*     _    _____   _   _ 
 *   / _ \ \_   _/ |  \|  \
 *  / ___/   | |   | |\_|\ \
 * <_/       |_|   |_|    \_>
 *
 * PTM FAQ v1.0.6
 * 1999-2000 Przemek Borys
 * Napisane w oparciu o pierwotne FAQ Pawła Olszewskiego
 * Opis otrzymywania konta w CVS: Tomasz Kłoczko
 * Druga wersja polonizowania systemu: Filipa Ozimek
 * Sprawy Debianowe: Piotr Roszatycki
 * Skrypt add2ptm, sprawa .so, identyfikacja źródeł,
 * Jak tłumaczyć Info: Wojtek Kotwica
 * Ispell, skrypty i zmienne środowiskowe: Paweł Wilk
 *
 * Spis treści:
 * 1.    Co to jest PTM?
 * 2.    Jak zainstalować pakiet PTM u siebie? (por. też p. 18)
 * 3.    Chcę przyłączyć się do projektu! Co zrobić?
 * 4.    O co chodzi w języku makr, w którym są pisane manuale!?
 * 5.    Przyjęte konwencje tłumaczenia nazw sekcji.
 * 6.    Apropos mi nie działa po polsku. Co zrobić?!
 * 7.    Jak wydrukować polskie manuale w postscripcie?
 * 8.    Jak zrealizować pomysł, by nie ściągać przy każdej zmianie całej
 *       paczki manuali, a tylko manuale, które się zmieniły?
 * 9.    Jak zainstalować pakiet PTM na systemie Debiana?
 * 10.   Słownik
 * 11.   Odświeżanie zawartości manuali
 * 12.   Skrypty i zmienne środowiskowe
 * 12.1  add2ptm
 * 12.2  heniu
 * 13.   Po co jest plik ispell.sprawdzane?
 * 14.   Apropos/whatis pokazują, że jest tłumaczenie, a mimo to zamiast
 *       niektórych polskich wyświetlane są angielskie strony manuala. 
 *       Co zrobić?
 * 15.   Dla tłumaczy: Linux czy Linuks
 * 16.   Dla tłumaczy: spolszczanie nazwy X Window System
 * 17.   Identyfikacja źródeł
 * 18.   Instalowanie dokumentacji info
 * 19.   Dla tłumaczy: na co uważać w plikach Texinfo
 * 20.   Kwestie prawne: czy pytać autorów podręczników o zgodę na tłumaczenie?
 * Dodatek I: Literatura
 *
 */

/*
 * 1. Co to jest PTM?
 */

	Od jakiegoś czasu daje się zauważyć na świecie ładną tendencję do
lokalizowania (w tym tłumaczenia) wszelkich pakietów. Do pakietów takich
należą również strony podręcznika systemowego man -- potocznie "manuale".
	PTM ma na celu tłumaczenie tych stron na język polski. Dosłownie,
PTM oznacza Projekt Tłumaczenia Manuali. Koordynuję go ja, czyli Przemek
Borys <pborys@dione.ids.pl>
	Projekt powstał w okolicach września 1998 roku, najstarsze
tłumaczenie, jakie udało mi się znaleźć w bazie to 11 wrzesień 1998.
	Podobne projekty istnieją na całym świecie; wystarczy choćby
przyjrzeć się trochę anonsom na comp.os.linux.announce. Nawiasem mówiąc,
nasz wydaje się być na razie jednym z większych :)
	Początkowo PTM miało na celu przetłumaczyć standardowy zestaw
manuali z pakietu man pages. Jednak szybko okazało się, że to za mało. Wiele
z niemal we wszystkich systemach obecnych programów dostarcza swoje strony
man poza tym systemem. Dlatego w tej chwili nasze prace obejmują właściwie
wszystko, czego przetłumaczenie może być użyteczne. Dodatkowo, poczynając od
lipca roku 2000, PTM z inicjatywy Wojtka Kotwicy zaczyna również prace nad
polonizowaniem dokumentacji info (dotyczy to przede wszystkim przypadków,
gdzie jest ona na dziś dzień autorytatywnym źródłem informacji).
	Obecnie oficjalną stroną projektu jest

	http://ptm.linux.pl

/*
 * 2. Jak zainstalować pakiet PTM u siebie?
 */

Trzeba wykonać kilka kroków. Oto one:

a) Rozpakować pakiet do katalogu z manualami, np. /usr/local/man.
   [Przemysław Sztoch]
   man'y standardowo w RH sa w /usr/man, a nie jak napisaliscie w FAQ
   /usr/local/man.
   [koniec komentarza]
   Tak naprawdę jest to kwestia konfiguracji programu `man'. (ad PB)
b) Ustawić zmienną środowiskową $LANG na wartość pl_PL. W bash robi to
   komenda

   export LANG=pl_PL

c) Skonfigurować program `man' tak, aby wyświetlał polskie znaki -- w tym
   celu trzeba wyedytować /etc/man.config i zamienić tam wywołania groffa
   z parametrem -Tascii na -Tlatin1. (W innych dystrybucjach, np. Slackware 7
   może to być w pliku /usr/lib/man/conf.)
d) Jeśli chcesz, by wyrazy były przenoszone z jednej linii na drugą w
   polskiej konwencji łamania, skopiuj z /usr/lib/texmf/tex/generic/hyphen/
   plik pohyph.tex do pliku /usr/lib/groff/tmac/hyphen.pl. Następnie
   w /usr/lib/groff/tmac/troffrc ustaw makra
  .\" Set the hyphenation language to PL'.
  .do hla pl
  .\" Load hyphenation patterns from yphen.pl' (in the tmac directory).
  .do hpf hyphen.pl
e) Należy też, o ile tego jeszcze nie masz ustawionego, zadbać o to, by sam
   manual-pager obsługiwał polskie znaki. Np. dla `less' trzeba ustawić
   zmienną środowiskową LESSCHARSET=latin1.
   Znacznie ładniejszym wyściem jest jednak zmiana manual-pagera na na
   przykład pinfo :) (autoreklama -- http://zeus.polsl.gliwice.pl/~pborys/)
f) Pamiętaj o odpowiednich prawach zapisu/odczytu katalogu z manualami, oraz
   samych manuali (odczytać je powinien móc każdy).

/*
 * 2.1 Uzupełniający sposób -- opisany przez Filipa Ozimka
 */

(a) można na "sztywno" ustawiać (np. w /etc/profile) zmienną MANPATH na
    "/usr/local/man/pl_PL:$MANPATH"
(b) albo dokonać drobnych modyfikacji w /etc/manpath.config, tj. zastąpić
    linie bardzo podobne to tych, następującymi:

    MANPATH_MAP     /bin                    /usr/local/man/pl_PL/
    MANPATH_MAP     /usr/bin                /usr/local/man/pl_PL/
    MANPATH_MAP     /sbin                   /usr/local/man/pl_PL/
    MANPATH_MAP     /usr/sbin               /usr/local/man/pl_PL/
    MANPATH_MAP     /usr/local/bin          /usr/local/man/pl_PL/
    MANPATH_MAP     /usr/local/sbin         /usr/local/man/pl_PL/
    MANPATH_MAP     /usr/X11R6/bin          /usr/local/man/pl_PL/
    MANPATH_MAP     /usr/bin/X11            /usr/local/man/pl_PL/
    MANPATH_MAP     /usr/games              /usr/local/man/pl_PL/
    MANPATH_MAP     /opt/bin                /usr/local/man/pl_PL/
    MANPATH_MAP     /opt/sbin               /usr/local/man/pl_PL/

    oraz dodać

    MANDATORY_MANPATH                       /usr/local/man/pl_PL

    oraz

    MANDB_MAP       /usr/local/man/pl_PL/   /var/catman/pl_PL

    Ten manewr skutecznie u mnie działa, tzn. "przesłania" angielskie strony
    polskimi oraz w razie braku polskiej wyświetla angielską.

/*
 * 2.2 Uzupełniający sposób bazujący na CVSie -- opisany przez Jarosława
 *     Kampera
 */

Opisana metoda pozwala nie tylko zainstalować najnowsze tłumaczenia manuali,
ale również późniejsze odświeżania już istniejącej bazy poprzez pobieranie 
tylko naniesionych poprawek. Do korzystania z CVS niezbędne jest zainstalowanie 
pakietu cvs dostępnego w każdej dystrybucji (chyba) lub ze strony domowej 
http://www.cyclic.com/. Sposób używania CVS opisany jest w pkt 3 tego FAQ.
Po pobraniu zawartości z repozytorium pl_PL należy dodać do zmiennej $MANPATH 
(znajdującej się np. w /etc/profile) ciąg $HOME/CVS/pl_PL (zakładając, że 
właśnie tam składujemy manuale z repozytorium), najlepiej na początku zmiennej 
$MANPATH, wpisując pełną (dostępną) ścieżkę katalogu 
(np. u mnie /home/jack/CVS/pl_PL) oddzielając nowy wpis ":" na końcu od 
pozostałych argumentów zmiennej.

UWAGA: aby wprowadzona nowa wartość zmiennej $MANPATH "zadziałała" należy się 
wylogować i zalogować ponownie.

/*
 * 3. Chcę przyłączyć się do projektu! Co zrobić?
 */

	Przede wszystkim zastanów się, co chcesz tłumaczyć. Jeśli jest ci
to obojętne -- w porządku. Następnie zgłoś chęć działania koordynatorowi
projektu (czyli mnie) -- na adres `Przemek Borys <pborys@dione.ids.pl>'.
Jeśli masz preferencje co do tłumaczenia, dobrze je zgłosić, lecz wpierw
spróbuj sprawdzić, czy rzeczy, którymi chcesz się zająć nie są już 
(prze)tłumaczone (sprawdź na stronach www projektu). Następnie przydzielę
ci teksty do tłumaczenia i zaznaczę w bazie, że się nimi zajmujesz.

	Ostatnio wrzuciłem bazę z tłumaczami do CVS (patrz niżej). Można się
więc już do  niej zapisywać bezpośrednio, bez konsultacji ze mną. Plik z bazą
tłumaczy to `zasoby/robotnicy', w którym umieszczane są pliki, nad którymi 
dana osoba pracuje. Jeśli tłumaczysz manuale, umieszczasz nazwę manuala.
Jeśli info, umieszczasz nazwę plik.texi. Mimo tego odhumanizowania mechanizmu
zapisów, postaraj się jednak poinformować mnie co robić -- są sytuacje, kiedy
jako koordynator muszę mieć rozeznanie, co gdzie się dzieje.

	W tym momencie dobrze jest się zapisać na listę dyskusyjną ptm,
wysyłając do majordomo@amg.net.pl list o treści
subscribe ptm
Wypisać się z niej można wysyłając temu samemu robotowi polecenie
unsubscribe ptm
Na liście możesz liczyć na pomoc w tłumaczeniach i w innych związanych z
pracą sprawach.
	Po przetłumaczeniu tekstu, są dwie drogi do jego załączenia do
dystrybucji projektu:
a) Załatwić sobie konto CVS na cvs.pld.org.pl. CVS to mechanizm `Concurent
Versions System', dający w sieci swego rodzaju katalog (taki jak normalne
katalogi na twoim dysku), do którego mają dostęp wszyscy pracujący nad
projektem. Katalog ten daje możliwość synchronizacji z twoją lokalną kopią
tych danych i umożliwia ich aktualizację oraz wprowadzanie zmian, które
pochodzą od ciebie. CVS posiada oczywiście jeszcze inne możliwości, ale te
wydają się najistotniejsze.

   "Żeby uzyskać dostęp RW trzeba wysłać na pld-cvs@pld.org.pl:
   - e-adres kontaktowy,
   - imię i nazwisko
   - to co zwróci:

   $ echo -n "<login>:"; perl -e 'print crypt "<password>", "<salt>"; print "\n";'

   <salt> to dwie dowolne literki. 
   <login> i <password> to chyba nie musze tłumaczyć .. :)"

   Po uzyskaniu dostępu RW do cvs, należy wyeksportować sobie do środowiska
   zmienną CVSROOT=":pserver:login@cvs.pld.org.pl:/cvsroot".
   Wtedy można już korzystać z CVS -- przejdź do katalogu, w którym
   chciałbyś przechowywać lokalną kopię CVS (np. ~/CVS) i wydaj komendę

   cvs login

   Wtedy się zalogujesz. Następnie wydaj komendę
 
   cvs co pl_PL

   Sprawdzi (CheckOut) ona, czy w repozytorium nie ma czegoś nowego -- a 
   jeśli będzie, to ściągnie te zmiany na twój dysk. Następnie robisz coś 
   takiego

   cd ~/CVS/pl_PL/man[1-9]
   cp /sciezka/gdzie/masz/przetłumaczony_manual .
   cvs add przetłumaczony_manual
   cd ~/CVS

   W ten sposób dodaje się pliki do repozytorium. Następnie trzeba je
   przesłać (commit) na serwer CVS

   cvs ci pl_PL

   I gotowe. Będziesz musiał jeszcze tylko wypełnić opis, co wysyłasz.

b) Mniej zalecany sposób, ale jeśli nie jesteś w stanie używać CVS, to
   podrzuć mi przetłumaczonego manuala jako załącznik w poczcie.

/*
 * 4. O co chodzi w języku makr, w którym są pisane manuale!?
 */

	Manuale są pisane z wykorzystaniem makr groffa. Najważniejsze rzeczy,
jakie o nich powinien wiedzieć członek PTM, to fakt, że makra te mają
następującą postać:

.X linijka tekstu

lub

\fX tekst 

gdzie X określa zmianę fontu (np. `B' włącza bold, `I' włącza kursywę, `R'
włącza standardowy font Roman -- dlatego np. często można spotkać "wcięcia"
w tekście, mające postać "teraz sobie coś napiszemy \fBboldem\fR, a teraz
\fIkursywą\fR". Ten tekst można napisać inaczej, np.

teraz sobie coś napiszemy
.B boldem,
a teraz
.I kursywą.

W tym drugim wypadku będziemy jednak mieli ten problem, że zarówno
przecinek, jak i kropka nie będą napisane fontem Roman. Aby to wyeliminować,
stosuje się inny wariant tej metody, przykład:

teraz sobie coś napiszemy
.BR boldem ,
a teraz
.IR kursywą .

Gdy używa się komendy ".XY", to znaczy że pierwsze słowo (lub tekst ujęty w
cudzysłów) po makrze należy wypisać fontem "X", a drugi fontem "Y".
Jeśli występuje więcej słów, to wystąpi naprzemienne użycie fontów:

.RI ( opcje )

lewy nawias zwykłym fontem, słowo 'opcje' kursywą, prawy nawias ponownie
zwykłym fontem.

Makra typu ".X" działają na tylko początku wiersza, makra "\fX" w dowolnym
miejscu tekstu.

Komentarze obejmujące pojedynczy wiersz wprowadza się sekwencją 

.\" Komentarz

	Istnieją też inne, zwykle kilkuznakowe makra formatujące.
	Większe partie tekstu (np.kilka wierszy) najprościej komentować
przy użyciu makra ".ig" koniec komentarza wyznaczany jest wówczas makrem ".."

.ig 
komentarz z wielu wierszy; powinny być pominięte,
np. dlatego, że odnoszą się do poprzedniej wersji opisywanego programu
..

	Dodatkowo, manuale zwykle dzieli się na sekcje. Do wprowadzenia
tekstu "nagłówkowego", informującego o sekcji, stosuje się makro

.SH SEKCJA

	Poza tym, często zdarza się, że w manualach występują np. listy
(makra ".TP", i inne symbole) -- ale tłumacz właściwie nie musi już wiedzieć
co one oznaczają -- wystarczy zostawić je w spokoju. Dla dociekliwych
pozostaje zawsze dostępna dokumentacja groffa i ewentualnie man-howto lub
`man 7 man', `man 7 me' (nawiasem mówiąc przetłumaczone w ramach PTM :).

/*
 * 5. Przyjęte konwencje tłumaczenia nazw sekcji.
 */

	Większość manuali dzieli się na sekcje. W języku angielskim ich
nazewnictwo jest jednolite; celowe jest zatem uczynienie tego samego dla
języka polskiego. Przyjęliśmy następujące tłumaczenia:

NAME		NAZWA
SYNOPSIS	SKŁADNIA (ewentualnie STRESZCZENIE, co jest dosłownym
			 tłumaczeniem, lecz nie zawsze  oddaje istotę
                         rzeczy)
DESCRIPTION     OPIS
FILES           PLIKI
SEE ALSO        ZOBACZ TAKŻE
AUTHOR          AUTOR
COPYING         KOPIOWANIE
ERRORS          BŁĘDY
BUGS            BŁĘDY (ewentualnie gdy kłóci się z ERRORS -- USTERKI)
ENVIRONMENT     ŚRODOWISKO
EXAMPLES        PRZYKŁADY
RUNLEVELS	POZIOMY PRACY
BOOTFLAGS	FLAGI STARTOWE (ew. USTAWIENIA POCZĄTKOWE)
CONFORMING TO	ZGODNE Z
CAVEATS		ZASTRZEŻENIA/PRZESTROGI (ma to jakby znaczenie umywania 
		rąk, ostrzeżenia, itp.)
USAGE		UŻYTKOWANIE
RETURN VALUE	WARTOŚĆ ZWRACANA

/*
 * 6. Apropos mi nie działa po polsku! Co zrobić?
 */

Apropos do działania potrzebuje wpisu whatis w korzeniu katalogu z
manualami. Wraz z dystrybucją powinieneś dostać wpis whatis. Jeśli jednak go
nie będzie lub będzie nieaktualny, uruchom skrypt makewhatis, dostarczany z
dystrybucją.

/*
 * 7. Jak wydrukować polskie manuale w postscripcie?
 */

[Pisze Jarek Woloszyn]
Ja sobie z ogonkify jakiś czas temu nie poradziłem. Może jakieś nowe
ogonkify zadziała.

Problem pomógł mi rozwiązać Staszek Ciszewski. Stworzył on po prostu
dodatkowe urządzenie, które obsługuje fonty latin2.
Trzeba połatać groffa (ver 1-11).
[koniec]

Niezbędna łata jest dostępna pod adresem http://ptm.linux.pl.

Alternatywą do drukowania manuali w postscripcie jest drukowanie ich z
formatu ASCII (man problem | colcrt > plik.do.wydruku). Traci się jednak
pewne elementy składu, jak np. pogrubienia, podkreślenia, itp.
Pogrubienia w wielu wypadkach można zachować, drukując plik bez
filtrowania nadstukiwań przez colcrt (man problem > plik.do.wydruku).

/*
 * 8. Jak zrealizować pomysł, by nie ściągać przy każdej zmianie całej
 *    paczki manuali, a tylko manuale, które się zmieniły?
 */

Skorzystaj z CVS. Sposób używania CVS jest podany w punkcie (3.) tego FAQ.
Jedyna różnica, to to, że jako użytkownik anonimowy, nie korzystasz ze
swojego własnego konta, ale z konta `anonymous' lub `cvs'. Zamiast hasła
pisze się `cvs'. Ponadto, trochę modyfikuje się adres serwera CVS.

Przykładowy skrypt, który załatwi ściąganie przy założeniu, że masz
zainstalowanego klienta CVS:

--- cut ---
#!/bin/sh
cvs -d :pserver:cvs@anoncvs.pld.org.pl:/cvsroot login
cvs -z 9 -d :pserver:cvs@anoncvs.pld.org.pl:/cvsroot co pl_PL
cvs -d :pserver:cvs@anoncvs.pld.org.pl:/cvsroot logout
--- cut ---

/*
 * 9. Jak zainstalować pakiet PTM na systemie Debiana?
 */
 
Najprostsza odpowiedź brzmi - zainstalować pakiety manpages-pl_*.deb oraz
manpages-pl-dev_*.deb. Znaleźć je można na każdym serwerze z archiwum Debiana
w podkatalogu pool/main/m/manpages-pl/ .

Komfortową sytuację mamy, gdy działa system obsługi pakietów APT.
Wystarczy wywołać polecenia

apt-get install manpages-pl
apt-get install manpages-pl-dev

i odpowiedni pakiet ściągnie się z sieci i zainstaluje w systemie. Późniejsza
aktualizacja ogranicza się do wydania poleceń

apt-get update
apt-get upgrade

A co zrobić, jeśli nie chcemy ściągać za każdym razem całych pakietów? 
Najprościej jest wykorzystać pomysł z CVS podany w punkcie 8 tego FAQ.

Do zbudowania pakietu potrzeba nam następujących pakietów zainstalowanych 
w systemie: dpkg-dev, debhelper, fakeroot.

Po ściągnięciu najnowszych plików z serwera CVS należy wejść do katalogu
pl_PL i wykonać polecenie

fakeroot debian/rules binary

Gotowe pakiety znajdą się w katalogu wyżej, pod odpowiednimi nazwami.
Wystarczy je już zainstalować jako root:

dpkg -i *.deb

/*
 * 10. Słownik
 */

W archiwum PTM znajduje się słownik, który ma w założeniach

a) pomagać tłumaczom w tłumaczeniu trudnych wyrażeń
b) ujednolicać słownictwo tłumaczeń

Szczegóły implementacji słownika są opisane w samym słowniku.

/*
 * 11. Odświeżanie zawartości manuali
 */

Manuale z czasem mogą się trochę dezaktualizować. Dlatego trzeba je
odświeżać. Dobrze jest w tym celu trzymać oryginalną angielską wersję
manuala, a w wypadku gdy dostaniemy nową, wykonać

diff -c stara.wersja.angielska nowa.wersja.angielska

i nanieść poprawki do tłumaczenia. Teoretycznie różnica kontekstowa 
(diff -c) powinna być na tyle czytelna, że nie powinno być problemów.

W tym momencie dodam jeszcze, że warto w tłumaczeniach wstawiać wersję
programu, który się tłumaczy. Ułatwia to później aktualizację.

/*
 * 12. Skrypty i zmienne środowiskowe
 */

Dawno, dawno temu, gdy repozytoria przypominały Pola Elizejskie i gdy
śnieg był jeszcze biały a powietrze czyste... wtedy był porządek w
module pl_PL. Lecz kilka miesięcy potem developerzy chytrzy zaczęli 
mieszać, kombinować i reorganizować! I nie było to niczym złym, 
lecz wychowani w coraz brudniejszym świecie chaosu nieświadomie czynili 
porutę wewnątrz owych zasobów. Wtedy to, właściwego czasu i na właściwej 
dyskusyjnej liście zstąpił z niebios koordynator nasz wszechmogący i 
zarządził Nowy Ład! I łaska zstąpiła na dyrektoria i na pliki nasze. 
Tak, że posłał swego sługę Siefcę by za daną przez Archanioła Wysokiej
Jakości (ang. HQ) zgodą uczyił odpowiednią strukturę podług danego mu 
zamysłu. A więc wziął zasoby w swoje skodowane ręce i zaczął je 
dostosowywać do planu Pana - dzień pierwszy i ostatni zarazem.

Skrypty i pliki ulokowane zostały w dodatkowym katalogu 'zasoby' 
wewnątrz modułu, o którym mowa była na początku tej przypowieści. 
Od tego też czasu wszystkie skrypty wspomagające i raportujące przyjęły 
następujący standard w postaci zmiennych środowiskowych, które 
translatorzy dobroduszni powinni wyeksportować w swej sesji na chwałę 
projektu i na zgodę z ich upodobaniem:

PTM_EMAIL       - zawierającą twój adres e-mail, który jest (będzie)
                  użyty do identyfikacji w pliku robotnicy
PTM_NAME        - zawierającą twoje imię i nazwisko
PTM_PL_DIR      - zawierającą położenie katalogu pl_PL
PTM_DICT_DIR    - zawierającą położenie katalogu pl_DICT 
                  (jeśli używasz i sprawdzasz podręczniki)

PRZYKŁAD do umieszczenia w .bash_profile :

-------------------------------------------------

PTM_EMAIL="jankow@gdziestam.pl"
PTM_NAME="Jan Kowalski"
PTM_PL_DIR="~/cvs/pl_PL"
PTM_DICT_DIR="~/cvs/pl_DICT"

export PTM_EMAIL PTM_NAME PTM_PL_DIR PTM_DICT_DIR

--------------------------------------------------

Zmienne owe użyteczne się stają, gdy z innej niż oryginalna
lokacji skrypty wołać raczysz.

 * 12.1 Skrypt add2ptm

W archiwum PTM znajduje się skrypt mający za zadanie nieco ułatwiać
tłumaczom zadanie rezerwowania plików do tłumaczenia. Rezerwowane manuale
wpisywane są do pliku 'robotnicy' po identyfikatorze tłumacza. 
Oczywiście, zapisy te pozostają również po wykonaniu pracy.
Skrypt jest stosunkowo prosty, ale
a) nie umożliwia rezerwacji plików osobom, których nie ma jeszcze na
   liście tłumaczy :(,
b) należy pamiętać, by nie dostosowywać do swoich danych egzemplarza
   w lokalnym katalogu CVS. Został on umieszczony w repozytorium tylko
   dla wygody dystrybucji. Powinno się korzystać z odpowiednio zmienionej
   kopii umieszczonej w prywatnym katalogu, poza strukturą synchronizowanego
   repozytorium CVS.
[sekcję dołączono ze względu na zdarzające się nieporozumienia - HQ]

 * 12.2 Skrypt heniu
 
Heniu to prosty, nieinteraktywny skrypt raportujący, którego zadaniem jest
wspomagać tłumaczy znajdując logiczne więzi między pakietami a stronami
podręczników, które do nich należą. Informacje o tym jakie podręczniki 
należą do konkretnych pakietów heniu pobiera z plików położonych w
pl_PL/zasoby/pakiety. Korzysta także z pliku pl_PL/zasoby/ispell.sprawdzane
aby dowiedzieć się więcej o stanie podręcznika. Oto opcje z jakimi możesz
go zawołać:

heniu -g	poda ci wszystkie gotowe pakiety
heniu -n	powie ci jakie pakiety są niedokończone
heniu -q nazwa	wyświetli informacje o stanie pakietu o podanej nazwie
heniu -m nazwa	wyświetli informacje o stanie podanego podręcznika
heniu		wyświetli informacje o stanie wszystkich pakietów

Przykład zapytania o pakiet rlinetd:

> [koder@szarik koder]$ heniu -q rlinetd
> Heniu v.0.04 (GPL) by P.Wilk <siewca@dione.ids.pl>
> 
> Raport stanu pakietu.
> --------------------------------------------------
> PAKIET: rlinetd
> 
> Do przetłumaczenia:
> rlinetd.conf.5 (istnieje lokalnie)
> 
> Do sprawdzenia:         (nic)

Zauważmy zapis 'istnieje lokalnie'. Jeśli takie coś pojawi się u ciebie
to znaczy, że dany podręcznik nie został przesłany na serwer CVS i
traktujemy go jako nieprzetłumaczony.

Przykład zapytania o rlinetd.conf.5:

> [koder@szarik koder]$ heniu -m rlinetd.conf.5
> Heniu v.0.04 (GPL) by P.Wilk <siewca@dione.ids.pl>
> 
> Raport stopnia gotowości podręcznika.
> --------------------------------------------------
> PODRĘCZNIK: rlinetd.conf.5
> 
> W pakiecie:     rlinetd
> Przetłumaczony: ??? (istnieje tylko lokalnie).
> Sprawdzony:     NIE


/*
 * 13. Po co jest plik ispell.sprawdzane?
 */

Żeby manuale były poprawne ortograficznie powstało repozytorium o nazwie
pl_DICT. Znajdują się w nim słowniki do programu Ispell, odpowiednie narzędzia,
a także skrypcik 'manspell', który po ustawieniu paru zmiennych będzie odwalał
całą brudną robotę za Ciebie. Wymaganiem jest posiadanie w miarę nowego
(wersja 3.1.18 3.1.20) Ispella. Właśnie jednym z zadań manspella jest 
umieszczanie odpowiednich adnotacji w tym pliku. More info: pl_DICT/FAQ .
To była reklama. :-) [siefca]

/*
 * 14. Apropos/whatis pokazują, że jest tłumaczenie, a mimo to zamiast
 *     niektórych polskich wyświetlane są angielskie strony manuala. Co zrobić?
*/

Przykład dla 'zless': upewnij się jak wyszukiwana jest właściwa wersja manuala

man -w zless

Wystąpienie w odpowiedzi dwu wierszy, z których pierwszy wskazuje na polską
wersję (i opisuje błąd), zaś drugi na oryginalną, objawia problem czytnika
stron man. Występuje on np. w dystrybucji SuSE i spowodowany jest ograniczoną
interpretacją makra .so. Wykonuje ono wyświetlenie innej strony manuala zamiast
wskazanej.
Możliwe rozwiązania:
a) (zalecane) zmień pakiet man na lepszy,
b) nie przejmuj się. Na podstawie whatis/apropos, 'man -w' lub nagłówka
   wyświetlanego oryginału wywołaj sam właściwą stronę (np. dla zless jest to
   zmore),
c) znajdź plik źródłowy sprawiający kłopoty (/usr/man/pl_PL/man1/zless.1)
   i zmień zawartość typu
      .so zmore.1
   dopisując odpowiedni podkatalog:
      .so man1/zmore.1
   Zauważ, że jest to bardzo kłopotliwe. Plików man tego rodzaju jest więcej,
   będziesz zapewne okresowo aktualizował pakiet PTM, a ponadto żądanie .so
   z podanym podkatalogiem nie jest poprawnie obsługiwane przez popularnego
   Midnight Commandera.

/*
 * 15. Dla tłumaczy: Linux czy Linuks
 */

Do ok. 1998 sprawa była jasna, wszyscy pisali `Linux'. Następnie, po latach
spokoju na grupie pl.comp.os.linux zaczęła się na ten temat burza.

Według polskich reguł odmiany, Linux we wszystkich odmienionych formach
powinien być pisany przez `ks'. Jednak historycznie zakorzeniona odmiana nie
podlega tej regule. W wyniku tej rozbieżności, wiele osób pisze tę nazwę
przez `ks', a wiele przez `x'.

Z uwagi na brak występowania formy `ks' w dawnych czasach, po długich
dyskusjach udało się wypracować pewien kompromis. Odmiana `x' jest obecnie
archaiczna i dążąc do usystematyzowania języka  w dokumentacjach powinna być
stosowana forma `ks'.

Na poparcie tezy, że forma `x' jest archaiczna, a nie błędna, można przyjąć
wiele argumentów. Jednymi z ważniejszych są te, że początkowo nikt nie znał
i nie używał formy `ks'. Nawet książki. I to nie tylko techniczne.
Literatura piękna również nie znała tak całkiem zasad odmiany słów kończących
się na `x' (por. `Opowieści o pilocie Pirxie'). Znani mi poloniści
jeszcze w 1998 roku musieli SPRAWDZAĆ w podręcznikach jak odmienić słowo
`Hortex'. Wszystko to kumuluje się na stwierdzenie, że słowo `linux'
weszło do języka polskiego na drodze niezręczności słowotwórczej, lecz w
tamtych czasach nie była ona rażąca. A ponieważ używano jej potem przez
wiele lat w niezmienionej formie, łącząc z nią nierzadko ideologie
opensource i pracę `pod sztandarem Linuxa', należy uszanować tradycję i nie
uznawać tej odmiany za błąd. W języku polskim zdarzało się już
niejednokrotnie wprowadzanie nazw bez przestrzegania zasad, a jednak nikt
tych słów później na siłę nie prostował. Przykład jaki nasunął mi się przy
tej argumentacji to imię `Mojżesz', które w Biblii przetłumaczono z języka
obcego nie zważając na zasadę pisania `rz' po `j'.

Nie należy natomiast pisać `Linuks' w mianowniku.
W wypadku używania form `x' nie należy tez używać żadnych apostrofów czy
myślników w formach takich, jak `Linuxa', `Linuxowi'.

/*
 * 16.   Dla tłumaczy: spolszczanie nazwy X Window System
 */

Oficjalna nazwa tego systemu to "X Window System", "X Window" lub "X". Po
polsku oznacza to mniej więcej tyle co System Okna X. Okna, nie okien. Choć
w potocznej mowie sens jest podobny, w technicznej jest drobna różnica.
X Window System oznacza dawanie jakiegoś interfejsu tworzenia okna i jego
obsługi. Nie oznacza on jednak, że są tam jakieś konkretne okienka.

Wynika z tego, że nadawanie tej nazwie podtekstu liczby mnogiej (X Windows,
X-y) jest nie do końca poprawne (w szczególności nie jest "poprawne
politycznie", gdyż środowiska ludzi używających X często nie chcą być mylone
z innym produktem z "Windows" w nazwie :).

/*
 * 17. Identyfikacja źródeł
 */

Zdarza się, że różne pakiety posługują się poleceniami o tych samych nazwach.
Chcąc utrzymać tłumaczenie kilku plików o tych samych nazwach oryginału,
przyjęliśmy w takich przypadkach dodawanie pojedynczej litery na końcu nazwy.
I tak np. 'id.1' opisuje polecenie id z pakietu GNU (standardowe), zaś
'id.1s' zastępujące je polecenie z pakietu 'shadow'.
Zaleca się tłumaczom podawanie opisanej w manualu wersji oraz, w razie
wątpliwości, również nazwy pakietu. Nawet jeżeli oryginał ich nie podawał.
Informację tę najlepiej umieścić w nagłówku .TH lub ewentualnie w formie
komentarza (.\") na początku pliku.

/*
 * 18.   Instalowanie dokumentacji info
 */

PTM tłumaczy również dokumentację texinfo programów. Póki co nie ma jej
jeszcze praktycznie wcale gotowej, ale przedstawię tu teoretyczne możliwości
jej instalacji:
Napierw trzeba ją oczywiście skompilować do postaci info. W najprostszym
przypadku robimy `makeinfo plik.texi'.
Po skompilowaniu, gotowe pliki info kopiujemy np. do katalogu
/usr/info/pl_PL. Teraz zaczyna się zabawa: jeśli używasz do czytania
dokumentacji texinfo programu `pinfo', wystarczy ustawić zmienną
środowiskową $LANG na `pl_PL' (pinfo szuka w katalogach info podkatalogów
nazwanych $infodir/$LANG).
W przypadku programu `info' sprawa jest inna: nie obsługuje on locali, ale
od czego moja nieskromna inwencja twórcza :) Można zrobić następujący trik:

export $INFOPATH="/usr/info/pl_PL:/usr/info:/usr/local/info:/usr/share/info:"

rozumiecie ideę ;)

/*
 * 19.   Dla tłumaczy: na co uważać w plikach Texinfo
 */

Instrukcje texinfo zaczynają się od "małpy" (@). Podwojona daje literał "@".
Wiersze przetwarzane są podobnie jak w groffie czy TeX-u (nieco podobnie jak
w HTML-u). Można swobodnie łamać zbyt długie wiersze - zmiana akapitu nastąpi
w miejscu pustego wiersza. Wymuszone łamanie wiersza robimy poleceniem "@*".
"@page" dotyczy tylko postaci drukowanej i wymusza zmianę strony, zaś
"@group"-"@end group" wymuszenie wystąpienia wierszy razem na stronie.

Instrukcja "@c foo.." oznacza komentarz, podobnie działa para "@ignore"
i "@end ignore".

Pary "@ifinfo"-"@end ifinfo" i "@iftex"-"@end iftex" ograniczają tekst, który
ma pojawić sie tylko, odpowiednio, w pliku Info albo, w dokumencie drukowanym.
Konstrukcja typu "@set BOOK książka" nadaje wartość zmiennej. Wartość
ta będzie wykorzystana przez @value{BOOK}. Tu należy uważać, gdyż stosowane
są rozwiązania typu:
  @ifinfo
  @set BOOK Info file
  @end ifinfo
  @iftex
  @set BOOK book
  @end iftex
  ...
  In this @value{BOOK}....

"@node" określa węzeł struktury:
  @node Drugi, następny, poprzedni, macierzysty
podczas, gdy "@chapter", "@section" itp. tytuł danej części:
  @chapter Drugi podrozdział
Nazwy węzłów tłumaczymy. Muszą być niepowtarzalne w ramach dokumentu.
Używane są ponadto jako argumenty instrukcji odnośników @ref{},
@pxref{}, @xref{} oraz w menu, po lewej:
  @menu
  * Pierwszy:: Miłe złego początki
  * Drugi::    Kontynuujemy naukę
  @end menu
Opisy w prawej stronie menu, podobnie jak kolejny parametr @ref{} nie muszą
odpowiadać tytułowi odpowiedniego węzła. Jest to tekst, jaki pojawi się jako
odnośnik. Przy odsyłaczach należy uważać na gramatykę - @xref{} i pxref{}
poprzedzane są odpowiednio przez 'See', 'see', co nie zawsze
da się ładnie wepchnąć w naszą składnię. @ref{} nie daje przedrostka.
Z powodu "*Note" wszystkie te konstrukcje są kłopotliwe przy formacie Info.

Węzeł "Top" reprezentuje wierzchołek dokumentu - jego nazwy nigdy nie
tłumaczymy. Podobnie nie tłumaczymy nazwy węzła (dir), oznaczającego
wierzchołek struktury złożonej ze wszystkich zainstalowanych plików Info
(zawarty jest on w pliku /usr/info/dir, uzupełnianym ręcznie lub skryptem
wg "@direntry").
"@bye" oznacza koniec przetwarzania dokumentu. Reszta nie jest przetwarzana.

/*
 * 20.   Kwestie prawne: czy pytać autorów podręczników o zgodę na tłumaczenie?
 */

Jeśli dokumentacja jest rozprowadzana w ramach pakietów GNU, to nie ma
problemu i można tłumaczyć.  Zachowujemy oczywiście stare copyrighty.

W przypadku pozostałych dokumentacji -- jeśli licencja jest niejasna; lepiej
zapytać. Jeśli nie ma jej w ogóle -- również należy prosić o zgodę.

/*
 * Dodatek I: Literatura :)
 */

man man..........................................Opis używania programu man
man man.config.....................Opis pliku konfiguracyjnego programu man
man less......................Opis domyślnej linuxowej przeglądarki manuali
man pinfo................Opis alternatywnej (mojego autorstwa) przeglądarki
man groff...................Opis programu używanego do formatowania manuali
man troff.................Opis programu składu tekstu, wołanego przez groff
man 7 man.........................................Makra używane w manualach
man me.....................................Makra używane czasem w manualach
info gettext...........................Opis problemów związanych z localami
Locale MiniHowto................................Opis locali w postaci HOWTO
Man-Page MiniHowto.....................................Jak pisać strony man
http://www.agh.edu.pl/ogonki..Jak uzyskać polskie litery na swojej maszynie
FHS (dostępne na mirrorach GNU)..............Opis hierarchii systemu plików
http://www2.linuxjournal.com/lj-issues/issue6/2840.html....Wstęp do Texinfo
[p]info texinfo...........................Opis systemu dokumentacji Texinfo