/*     _    _____   _   _ 
 *   / _ \ \_   _/ |  \|  \
 *  / ___/   | |   | |\_|\ \
 * <_/       |_|   |_|    \_>
 *
 * PTM FAQ v0.9.5
 * 1999 Przemek Borys
 * Napisane w oparciu o pierwotne FAQ Pawa Olszewskiego
 * Opis otrzymywania konta w CVS - Tomasz Koczko
 * Druga wersja polonizowania systemu -- opisana przez Filipa Ozimka
 *
 * Spis treci:
 * 1.  Co to jest PTM?
 * 2.  Jak zainstalowa pakiet PTM u siebie?
 * 3.  Chc przyczy si do projektu! Co zrobi?
 * 4.  O co chodzi w jzyku makr, w ktrym s pisane manuale!?
 * 5.  Przyjte konwencje tumaczenia nazw sekcji.
 * 6.  Apropos mi nie dziaa po polsku. Co zrobi?!
 * 7.  Jak wydrukowa polskie manuale w postscripcie?
 * 8.  Jak zrealizowa pomys, by nie ciga przy kadej zmianie caej
 *     paczki manuali, a tylko manuale, ktre si zmieniy?
 * 9.  Jak zainstalowa pakiet PTM na systemie Debiana?
 * 10. Sownik
 *
 * Dodatek I: Literatura
 *
 */

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

	Od jakiego czasu daje si zauway na wiecie adn tendencj do
lokalizowania (w tym tumaczenia) wszelkich pakietw. Do pakietw takich
nale rwnie strony podrcznika systemowego man -- manuale.
	PTM ma na celu tumaczenie tych stron na jzyk polski. Dosownie,
PTM oznacza Projekt Tumaczenia Manuali. Koordynuj go ja, czyli Przemek
Borys <pborys@dione.ids.pl>
	Projekt powsta w okolicach wrzenia 1998 roku, najstarsze
tumaczenie jakie udao mi si znale w bazie to 11 wrzesie 1998.
	Podobne projekty istniej na caym wiecie; wystarczy choby
przyjrze si troch anonsom na comp.os.linux.announce. Nawiasem mwic,
nasz wydaje si by narazie jednym z wikszych :)
	Pocztkowo PTM miao na celu przetumaczy standardowy zestaw
manuali z pakietu man pages. Jednak szybko okazao si, e to za mao. Wiele
z niemal we wszystkich systemach obecnych programw dostarcza swoje strony
man poza tym systemem. Dlatego w tej chwili nasze prace obejmuj waciwie
wszystko, czego przetumaczenie moe by uyteczne.

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

Trzeba wykona kilka krokw. Oto one:

a) Rozpakowa pakiet do katalogu z manualami, np. /usr/local/man.
   [Przemysaw 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 wywietla polskie znaki -- w tym
   celu trzeba wyedytowa /etc/man.config i zamieni tam wywoania groffa
   z parametrem -Tascii na -Tlatin1.
d) Naley te, o ile tego jeszcze nie masz ustawionego, zadba o to, by sam
   manual-pager obsugiwa polskie znaki. Np. dla `less' trzeba ustawi
   zmienn rodowiskow LESSCHARSET=latin1.
   Znacznie adniejszym wyciem jest jednak zmiana manual-pagera na na
   przykad pinfo :) (autoreklama -- http://zeus.polsl.gliwice.pl/~pborys/)

/*
 * 2.1 Uzupeniajcy sposb -- opisany przez Filipa Ozimka
 */

(a) mona na "sztywno" ustawia (np. w /etc/profile) zmienn MANPATH na
    "/usr/local/man/pl_PL:
anpath"
(b) albo dokona drobnych modyfikacji w /etc/manpath.config, tj. zastpi
    linie bardzo podobne to tych, nastpujcymi:

    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 dziaa, tzn. "przesania" angielskie strony
    polskimi oraz w razie braku polskiej wywietla angielsk.


/*
 * 3. Chc przyczy si do projektu! Co zrobi?
 */

	Przede wszystkim zastanw si, co chcesz tumaczy. Jeli jest ci
to obojtne -- w porzdku. Nastpnie zgo ch dziaania koordynatorowi
projektu (czyli mnie) -- na adres `Przemek Borys <pborys@dione.ids.pl>'.
Jeli masz preferencje co do tumaczenia, dobrze je zgosi, lecz wpierw
sprbuj sprawdzi, czy rzeczy o ktre prosisz nie s ju (prze)tumaczone
(sprawd na stronach www projektu). Nastpnie przydziel ci teksty do
tumaczenia i zaznacz w bazie, e si nimi zajmujesz.

Usprawnienie: Ostatnio wrzuciem baz z tumaczami do CVS. Mona si wic
ju do niej zapisywa bezporednio. Jednak i tak chciabym wiedzie co si
krci, wic zgoszenie jest mile widziane :)

	W tym momencie dobrze jest si zapisa na list dyskusyjn ptm,
wysyajc do majordomo@amg.net.pl list o treci
subscribe ptm
Wypisa si z niej mona wysyajc temu samemu robotowi polecenie
unsubscribe ptm
Na licie moesz liczy na pomoc w tumaczeniach i w innych zwizanych z
prac sprawach.
	Po przetumaczeniu tekstu, s dwie drogi do jego zaczenia do
dystrybucji projektu:
a) Zaatwi sobie konto CVS na cvs.pld.org.pl.

   "eby uzyska dostp RW trzeba wysa na pld-cvs@pld.org.pl:
   - e-adres kontaktowy,
   - imi i nazwisko
   - to co zwrci:

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

   <salt> to dwie dowolne literki. 
   <login> i <password> to chyba nie musze tumaczy .. :)"

   Po uzyskaniu dostpu RW do cvs, naley wyeksportowa sobie do rodowiska
   zmienn CVSROOT=":pserver:login@cvs.pld.org.pl:/cvsroot".
   Wtedy mona ju korzysta z CVS -- przejd do katalogu, w ktrym
   chciaby przechowywa lokaln kopi CVS (np. ~/CVS) i wydaj komend

   cvs login

   Wtedy si zalogujesz. Nastpnie wydaj komend
 
   cvs co pl_PL

   Sprawdzi (CheckOut) ona, czy w repozytorium nie ma czego nowego -- a 
   jeli bdzie, to cignie te zmiany na twj dysk. Nastpnie robisz co 
   takiego

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

   W ten sposb dodaje si pliki do repozytorium. Nastpnie trzeba je
   przesa (commit) na serwer CVS

   cvs ci pl_PL

   I gotowe. Bdziesz musia jeszcze tylko wypeni opis, co wysyasz.

b) Mniej zalecany sposb, ale jeli nie jeste w stanie uywa CVS, to
   podrzu mi przetumaczonego manuala attachmentem w poczcie.

/*
 * 4. O co chodzi w jzyku makr, w ktrym s pisane manuale!?
 */

	Manuale s pisane z wykorzystaniem makr groffa. Najwaniejsze rzeczy,
jakie o nich powinien wiedzie czonek PTM, to fakt, e makra te maj
nastpujc posta:

.X linijka tekstu

lub

\fX tekst 

gdzie X okrela zmian fontu (np. `B' wcza bold, `I' wcza kursyw, `R'
wcza standardowy font Roman -- dlatego np. czsto mona spotka "wcicia"
w tekcie, majce posta "teraz sobie co napiszemy \fBboldem\fR, a teraz
\fIkursyw\fB". Ten tekst mona napisa inaczej, np.
"teraz sobie co napiszemy
.B boldem,
a teraz
.I kursyw."
W tym drugim wypadku bdziemy jednak mieli ten problem, e zarwno
przecinek, jak i kropka nie bd napisane fontem Roman. Aby to wyeliminowa,
stosuje si inny wariant tej metody, przykad:
"teraz sobie co napiszemy
.BR boldem ,
a teraz
.IR kursyw ."
Gdy uywa si komendy ".XY", to znaczy e pierwsze sowo (lub tekst ujty w
cudzysw) po makrze naley wypisa fontem "X", a drugi fontem "Y".
	Komentarze w manualach wprowadza si sekwencj 
.\" Komentarz
	Dodatkowo, manuale zwykle dzieli si na sekcje. Do wprowadzenia
tekstu "nagwkowego", informujcego o sekcji, stosuje si makro
.SH SEKCJA
	Poza tym, czsto zdarza si, e w manualach wystpuj np. listy
(makra ".TP", i inne symbole) -- ale tumacz waciwie nie musi ju wiedzie
co one oznaczaj -- wystarczy zostawi je w spokoju. Dla dociekliwych
pozostaje zawsze dostpna dokumentacja groffa i ewentualnie man-howto lub
`man 7 man', `man 7 me' (nawiasem mwic przetumaczone w ramach PTM :).

/*
 * 5. Przyjte konwencje tumaczenia nazw sekcji.
 */

	Wikszo manuali dzieli si na sekcje. W jzyku angielskim ich
nazewnictwo jest jednolite; celowe jest zatem uczynienie tego samego dla
jzyka polskiego. Przyjlimy nastpujce tumaczenia:

NAME		NAZWA
SYNOPSIS	SKADNIA (ewentualnie STRESZCZENIE, co jest dosownym
			 tumaczeniem, lecz nie zawsze  oddaje istot
                         rzeczy)
DESCRIPTION     OPIS
FILES           PLIKI
SEE ALSO        ZOBACZ TAKE
AUTHOR          AUTOR
COPYING         KOPIOWANIE
ERRORS          BDY
BUGS            BDY (ewentualnie gdy kci si z ERRORS -- USTERKI)
ENVIRONMENT     RODOWISKO
EXAMPLES        PRZYKADY
RUNLEVELS	POZIOMY PRACY
BOOTFLAGS	FLAGI STARTOWE (ew. USTAWIENIA POCZTKOWE)
CONFORMING TO	ZGODNE Z
CAVEATS		ZASTRZEENIA/PRZESTROGI (ma to jakby znaczenie umywania 
		rk, ostrzeenia, itp.)

/*
 * 6. Apropos mi nie dziaa po polsku! Co zrobi?
 */

Apropos do dziaania potrzebuje wpisu whatis w korzeniu katalogu z
manualami. Wraz z dystrybucj powiniene dosta wpis whatis. Jeli jednak go
nie bdzie, lub bdzie 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 poradziem. Moe jakie nowe
ogonkify zadziaa.

Problem pomg mi rozwiza Staszek Ciszewski. Stworzy on po prostu
dodatkowe urzdzenie, ktre obsuguje fonty latin2.
Trzeba poata groffa (ver 1-11).
[koniec]

Niezbdna ata jest dostpna pod adresem http://ptm.linux.pl.

/*
 * 8. Jak zrealizowa pomys, by nie ciga przy kadej zmianie caej
 *    paczki manuali, a tylko manuale, ktre si zmieniy?
 */

Skorzystaj z CVS. Sposb uywania CVS jest podany w punkcie (3.) tego FAQ.
Jedyna rnica, to to, e jako uytkownik anonimowy, nie korzystasz ze
swojego wasnego konta, ale z konta `anonymous' lub `cvs'. Zamiast hasa
wciska si po prostu enter.

Przykadowy skrypt, ktry zaatwi ciganie przy zaoeniu, e masz
zainstalowanego klienta CVS:

--- cut ---
#!/bin/sh
cvs -d :pserver:cvs@cvs.pld.org.pl:/cvsroot login
cvs -z 9 -d :pserver:cvs@cvs.pld.org.pl:/cvsroot co pl_PL
cvs -d :pserver:cvs@cvs.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 mona na kadym serwerze z archiwum Debiana
w podkatalogu dists/potato/main/binary-all/doc/.

Komfortow sytuacj mamy, gdy dziaa system obsugi pakietw APT.
Wystarczy wywoa polecenia

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

i odpowiedni pakiet cignie si z sieci i zainstaluje w systemie. Pniejsza
aktualizacja ogranicza si do wydania polece

apt-get update
apt-get upgrade

A co zrobi jeli nie chcemy ciga za kadym razem caych pakietw? 
Najprociej jest wykorzysta pomys z CVS podany w punkcie 8 tego FAQ.

Do zbudowania pakietu potrzeba nam nastpujcych pakietw zainstalowanych 
w systemie: dpkg-dev, debhelper, fakeroot.

Po cigniciu najnowszych plikw z serwera CVS naley wej do katalogu
pl_PL i wykona polecenie

fakeroot debian/rules binary

Gotowe pakiety znajd si w katalogu wyej, pod odpowiednimi nazwami.
Wystarczy je ju zainstalowa jako root:

dpkg -i *.deb

/*
 * 10. Sownik
 */

W archiwum PTM znajduje si sownik, ktry ma w zaoeniach

a) pomaga tumaczom w tumaczeniu trudnych wyrae
b) ujednolica sownictwo tumacze

Szczegy implementacji sownika s opisane w samym sowniku.

/*
 * Dodatek I: Literatura :)
 */

man man..........................................Opis uywania programu man
man man.config.....................Opis pliku konfiguracyjnego programu man
man less......................Opis domylnej linuxowej przegldarki manuali
man pinfo................Opis alternatywnej (mojego autorstwa) przegldarki
man groff...................Opis programu uywanego do formatowania manuali
man troff.................Opis programu skadu tekstu, woanego przez groff
man 7 man.........................................Makra uywane w manualach
man me.....................................Makra uywane czasem w manualach
info gettext...........................Opis problemw zwizanych 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 (dostpne na mirrorach GNU)..............Opis hierarchii systemu plikw
