.\" Copyright (c) 1997 Mariusz Krawczyk
.\" Uogonkowienie i korekta formatowania: Andrzej Krzysztofowicz
.\" 
.TH CPL 7 "28 sierpnia 1997" "ConvPL"
.SH NAZWA
cpl \- konwerter standardów polskich znaków v2.07
.SH SKŁADNIA
.B cpl
.I nn
.RI [ konwersja ]
.RB [ - ]
.RI [ plik1.txt ]
.RI [ plik2.txt " ... ]"

.SH OPIS
Parametr
.RB nn
to dwie cyfry/litery, określające standard 
.I źródłowy 
(pierwsza) i 
.I docelowy 
(druga) przeprowadzanej konwersji.
Parametr
.B konwersja
określa rodzaj opcjonalnie stosowanej konwersji
zakończenia linii pomiedzy DOSem a Unixem i Amigą.

.SH PRZYKŁADY
.TP
.B cpl 14 tekst1.txt
\- plik tekst1.txt (Mazovia -> ISO-Latin-2)
.TP
.B cpl 14 *.txt
\- wszystkie pliki z rozszerzeniem .txt
.TP
.B cpl 14 tekst1.txt *.doc
\- plik tekst1.txt i wszystkie .doc

.SH "OBSŁUGIWANE STANDARDY"
Dostępne standardy (podajemy dwie cyfry/litery):
.TP
.B 0:
bez polskich liter (ASCII, CP473)
.TP
.B 1:
Mazovia
.TP
.B 2:
FidoMazovia
.TP
.B 3:
IBM Latin 2 (CP852)
.TP
.B 4:
ISO Latin 2 (ISO-8859-2)
.TP
.B 5:
DHN
.TP
.B 6:
CSK
.TP
.B 7:
Cyfromat (IINTE-ISIS)
.TP
.B 8:
IEA
.TP
.B 9:
LOGIC
.TP
.B a:
Microvex
.TP
.B b:
Amiga PL
.TP
.B c:
CP/J (Elwro 800 Junior)
.TP
.B d:
Amiga FAT
.TP
.B e:
Windows 3.x/95 (CP1250)
.TP
.B f:
Amiga XJP
.TP
.B g:
Ventura
.TP
.B h:
Macintosh
.TP
.B i:
TeX PL
.TP
.B j:
Corel 2.0
.TP
.B k:
Atari Calamus
.TP
.B l:
FX
.TP
.B m:
KWK
.TP
.B n:
MS Works
.TP
.B o:
ATM

.SH SKRÓTY
Zamiast najczęściej stosowanych konwersji można stosować skróty. Podajemy
wówczas tylko jedną literę:
.TP
.B A:
Mazovia na IBM Latin 2
.TP
.B B:
IBM Latin 2 na Mazovię
.TP
.B C:
Mazovia na ASCII
.TP
.B D:
IBM Latin 2 na ASCII
.TP
.B F:
FidoMazovia na Mazovię
.PP
Dowolność konwersji jest całkowita, z jednym wyjątkiem. Standard ASCII nie
może być standardem źródłowym konwersji (przyczyna jest oczywista - żeby nie
pokaszanić całego tekstu - ale jest od tej reguły wyjątek! patrz
.BR UWAGI ).

.SH "KONWERSJA ZAKOŃCZEŃ LINII"
.I ConvPL 
umożliwia równoległą konwersję pomiędzy tekstem spod DOSa, a tekstem
spod Uniksa czy Amigi. Rodzaj docelowej konwersji określają parametry:
.TP
.B \-: 
konwersja do tekstu Uniksa (Amigi)  -> NL
.TP
.B \=: 
konwersja do tekstu DOSa            -> CR+LF
.PP
Zmieniłem występujące w poprzednich wersjach oznaczenia tych parametrów
(/, \\), ponieważ ukośnik odwrotny jest znakiem specjalnym pod Uniksami. Nowe
ustawienia można równie łatwo zapamiętać: pod Uniksem koniec linii to jeden
znak (NL), więc jedna kreska: "-"; pod DOSem są to dwa znaki (CR+LF), stąd
dwie kreski: "=". Logiczne ;)

.SH "PRACA W TRYBIE FILTRU"
.I ConvPL
może pracować również w trybie filtru. Podanie znaku "-" zamiast
nazw plików spowoduje pobranie tekstu ze standardowego urządzenia wejścia 
- stdin (klawiatura) i zapisanie go do standardowego wyjścia - stdout 
(monitor, terminal, drukarka). Przykłady:
.TP
.B cpl A \-
\- każda linia wpisywana z klawiatury będzie
pojawiała się poniżej po wciśnięciu
.IR <Enter> ,
znaki z kodu Mazovia będą
zamieniane na IBM Latin 2
.TP
.B cpl 13 <joke.txt >prn
\- konwersja pliku joke.txt i wysłanie
wyników bezpośrednio na drukarkę (DOS); często sam z tego korzystam, bo na
moim PC pod DOSem mam Mazovię, a na drukarce CP852.
.PP
Jeśli nie chcemy zaśmiecać sobie dysku, wydajemy nastepujące polecenia:
.TP
.BR "cpl A - <joke.txt >nul " (MSDOS)
lub 
.B >/dev/null
(Unix) ;)))
.PP
Tryb filtru umożliwia również przetwarzanie tekstu w potoku (pipe).
.br 
.I Przykład:
.TP
.BR "type joke1.txt | cpl 14- - >joke3.txt " (MSDOS)
Plik 
.I joke1.txt
zostanie przepuszczony przez konwersję Mazovia -> ISO-Latin-2,
a końce linii zostaną zamienione na modłę uniksową. Wynik zostanie 
zapisany do pliku
.IR joke3.txt .
.PP
Zwróć uwagę na obecność dwóch minusów w linii poleceń - każdy pełni inną
funkcję. Pierwszy, połączony z opisem konwersji ("14-"), włącza konwersję
zakończeń linii. Drugi, samodzielny, włącza tryb filtru.
.TP
.BR "cat joke.txt1 joke2.txt | cpl 14- - >joke3.txt " (Unix)
Przyjmując, że pliki 
.I joke.txt 
i
.I joke2.txt 
są napisane oryginalnie w Mazovii i pod MSDOSem, takie polecenie spowoduje 
połączenie obu plików, konwersję całości z Mazovii na ISO Latin 2, i przy
okazji z CR+LF -> NL, a następnie zapis do pliku 
.IR joke3.txt .
.PP
Uruchamiając
.I ConvPL
w tym trybie należy uważać na pomyłki takie jak ta:
.TP
.B cpl A joke.txt >prn
Tekst zostanie przekonwertowany zgodnie z regułą 13 (skrót "A"), ale na
drukarkę nie zostanie wysłany, gdyż
.I ConvPL
będzie go zapisywał do pliku
.I joke.txt
a nie na standardowe wyjście. W rzeczywistości powyższe (błędne)
polecenie oznacza:
.br
.B konwertuj plik joke.txt, zapisując wynik pod tą samą nazwą,
zaś na drukarkę wysyłaj wyjście przez program
normalnie wyswietlane na ekranie, czyli komunikaty.
.PP
Polecenie poniższe spowoduje najprawdopodobniej uszkodzenie oryginalnego
pliku, więc należy się go wystrzegać:
.TP
.BR "cpl A - <joke.txt >joke.txt " (obie nazwy takie same!)
Po prostu, system straci głowę próbując równocześnie czytać i pisać
do pliku, a ucierpi na tym tenże plik.
.PP
.I Pamiętajmy:
aby uruchomić ConvPL w trybie filtru, potok danych musi
przychodzić z stdin i wychodzić na stdout (a nie częściowo z pliku, częściowo
z potoku). Jeśli nie wiesz o co chodzi, to poczytaj o potokach, filtrach oraz
roli symboli <, |, > itp. w poleceniach DOSa i Uniksa.

.SH UWAGI
Od wersji 2.01 istnieje możliwość wykonywania konwersji zakończeń linii
bez zmiany standardu polskich znaków. Wystarczy jako standard źródłowy
podać ASCII - "0" (do tej pory było to niedopuszczalne), zaś jako drugi
parametr opcję konwersji zakończeń linii "-" lub "=".  Drugi parametr,
podany zgodnie z konwencją i określający standard docelowy jest w tym
wypadku ignorowany. A zatem, każdy z poniższych przykładów ma takie samo
działanie:
.TP
.B cpl  0- joke.txt
.TP
.B cpl 00- joke.txt
.TP
.B cpl 02- joke.txt
.PP
czyli konwersję zakończeń linii do pojedynczych NL, bez naruszania
polskich liter.
.TP 
.B Komentarz do standardów
Za definicję Amiga PL dziekuję Marcinowi Kądziołce <2:484/15.16@fidonet>.
.IP
Definicje dodane w wersji 1.75 udostępnił mi Edwin Wierszelis
<2:482/16@fidonet>, autor konwertera KPN.
.IP
.I Standard ASCII 
to oczywiście zwykłe literki ASCII, zastępujące odpowiednie
polskie znaki. Taki tekst zwie się zwykle "polskawym", a standard określa
jako CP473 (oryginalna, amerykańska strona kodowa).
.IP
.I FidoMazovia 
jest półformalnym (jak cała reszta ;) standardem, przyjętym 
w środowisku sieci Fido. Jedyna różnica w stosunku do klasycznej Mazovii
to zamiana znaku c' (141) na c-cedilla (135), wynikająca ze względów
technicznych.
.IP
.I Standard IBM Latin 2 (CP852) 
jest lansowany przez Micro$oft wraz z systemem
MSDOS. Wraz z kolejnym "systemem" - Windows wyszedł na świat standard
strony kodowej 1250 (CP1250). Znany też jako Windows-EE, czyli strona
kodowa dla Europy Wschodniej.
.IP
.I ISO-8859-2 
znany też jako 
.I ISO Latin 2 
jest standardem rozpowszechnionym
zwłaszcza w systemach uniksowych i pracujących pod X-window. Jest również
standardem zalecanym przez Polskie Normy oraz uznanym za obowiązujacy
w polskojęzycznym WWW oraz w polskim UseNecie.
.IP
Standard 
.I FAT 
jest jednym z amigowskich dialektów, znalezionym w diskmagu
FAT przez Edwina Wierszelisa.
.IP
Standard
.I DHN
jest rozpowszechniony wraz z polskim ChiWriterem.
.IP
Niektóre standardy pochodza z Polskiej Strony Ogonkowej 
.IR http://www.uci.agh.edu.pl/ogonki/ , 
na której można znaleźć wiele cennych informacji na temat polskich liter.
.TP 
.B Konwersja tekstu Unix<->DOS:
Pod Uniksem każda linijka tekstu kończy się znakiem NL (new line) o kodzie
0xa, równoznacznym DOSowemu LF (line feed). Pod DOSem zakończenie linii
stanowi para znaków CR+LF, czyli 0xd,0xa. Parametr "-" wymusza zakończenie
linii znakiem NL, zaś "=" - parą CR+LF. Brak określonego kierunku konwersji
nie spowoduje żadnej zmiany końców linii w pliku wynikowym. Parametry
konwersji zakończeń linii dodaje się "na trzeciego" do parametrów konwersji
standardów.
.TP 
.B Kod źródłowy
Program był z powodzeniem kompilowany Borlandem 3.1, gcc 2.7.2 pod Linuksem
(a.out, ELF), oraz DJGPP pod DOSem (gcc 2.6.3). Proszę o kontakt w razie 
wystąpienia niekompatybilności kodu źródłowego w innych systemach.
Wersja 2.04 i wyższe są na razie kompilowalne tylko pod Linuksem (i być może
innymi Uniksami).
.TP 
.B Licznik linii:
Typowy "wodotrysk". Zwalnia pracę o ok. 30%. Standardowo wyłączony, w celu
włączenia trzeba przekompilować źródła bez opcji NO_LINE_COUNT. Licznik jest
zawsze wyłączony podczas pracy w trybie stdin/stdout (czyli zazwyczaj jako
filtr itp.).
.TP 
.B Znane błędy:
Tekst nie może zawierać znaku ASCII 0 (^@), 
który jest używany jako znacznik końca pliku.

.SH "INNE OPCJE"
.TP
.BR \-? ", " \-h ", " --help:
wyświetlają listę wszystkich dostępnych parametrów, składnię linii poleceń
itp.
.TP
.BR \-V ", " --version:
wyświetla (na stdout) numer wersji CPL
.TP
.BR \-L ", " --licencja:
wyświetlają licencję użytkowania programu.
.TP
.BR \-S ", " --standard:
wyświetlają tabelkę wszystkich obsługiwanych standardów polskich znaków.
.\" .SH "W PLANACH"
.\" .sp
.\" .B 'spolszczanie' cyrylicy
.\" .sp
.\" .B kody wieloznakowe

.SH "ZOBACZ TAKŻE"
.BR qpl (7) 

.SH AUTORZY
.TP
.B Paweł Krawczyk 
\- wlaściciel praw autorskich programu
.B cpl
.br
.I <kravietz@pipeta.chemia.pk.edu.pl>
.TP
.B Mariusz Krawczyk
\- twórca pliku manual-a, czyli tego
.br
.I <scorpio@astra.mech.pk.edu.pl>
