Eksperymentalny Klient Gadu-Gadu

          (C) Copyright 2001-2003 Autorzy (pełna lista poniżej)

LICENCJA

    Program jest udostępniony na zasadach licencji GPL v2, której treść
    załączono w pliku src/COPYING. Niektóre pliki mogą być objęte inną
    licencją zgodną z GPL v2. Fakt ten jest odnotowany na początku pliku.

    Wyjątkiem od licencji GPL v2 jest możliwość kompilacji, konsolidacji
    i używania programu z biblioteką OpenSSL autorstwa Projektu OpenSSL
    (The OpenSSL Project) dostępną pod adresem http://www.openssl.org/
    
INSTALACJA

    Rozpakować poleceniem ,,tar zxvf ekg2-XXX.tar.gz'' (gdzie XXX to wersja
    programu lub data wykonania snapshotu), wejść do utworzonego katalogu.
    Jeśli mamy uprawnienia administratora na danej maszynie, wywołujemy
    ,,./configure'', potem ,,make'' i z prawami roota ,,make install''.
    Jeśli chcemy zainstalować program w katalogu domowym, do polecenia
    configure dodajemy parametry ,,--prefix=$HOME/ekg2
    --mandir=$HOME/ekg2/share/man''. Po zainstalowaniu w ten sposób,
    program gotowy do uruchomienia będzie znajdował się w katalogu
    ekg2/bin w katalogu domowym. 

    Proste? Proste. Po pierwszym uruchomieniu EKG2 powie, jak go
    skonfigurować.

    Program korzyst domyślnie z pluginu wyjściowego ncurses. Interfejs
    readline w chwili obecnej nie jest gotowy do użycia. Do instalacji 
    konieczne jest zainstalowanie wszelkich narzędzi wymaganych do tego:
    kompilator, preprocesor, linker, pliki nagłówkowe, biblioteki itd.
    Jeżeli ./configure pokaże jakieś błędy skontaktuj się ze swoim 
    administratorem.

    ekg2 powinien działać na większości systemów uniksowych, jak Linux,
    *BSD, SunOS, IRIX itp. lecz czasami przy dodawaniu nowych funkcji
    nie sposób sprawdzić ich zachowania na wszystkich popularnych
    systemach. W takim wypadku przydatne są informacje o błędach z
    dokładnym wskazaniem systemu i architektury.

UŻYCIE

    Jest na tyle intuicyjne, że nie powinno sprawić problemów (wszyscy
    betatesterzy poradzili sobie bez jakiejkolwiek dokumentacji).
    Interfejs jest wzorowany na irssi. Dopełnianie tabem jest dostępne w
    większości komend. Komendy można wywoływać skrótami, o ile są one
    jednoznaczne. Wysyłanie wiadomości komendą ,,msg'', otwarcie okna 
    rozmowy komendą ,,query''. Informacje o rozmówcach ,,find'' w oknie
    rozmowy. Szukanie tą samą komendą, ale z różnymi parametrami. ,,help''
    Twoim przyjacielem. Jeśli dana komenda ma różne opcje, pomaga
    ,,help <komenda>''. By wysłać kilkulinijkową wiadomość w interfejsie
    ncurses, wciśnij Ctrl-Enter. W readline zamiast treści wpisz ,,\''
    (backslash) i zakończ linią z samą kropką (szczegóły poniżej, w rodziale
    ,,KLAWIATURA'').

    Program można skonfigurować pod wieloma względami, a wszystkie możliwe
    ustawienia, które zmienia się poleceniem ,,set'', są opisane w pliku
    vars.txt. Pomoc dotyczącą poszczególnych ustawień można uzyskać także
    poprzez polecenie ,,help set <zmienna>''.

    Jeśli dana komenda przyjmuje ,,--parametr'', można użyć również
    skrótu ,,-p'', gdy nie powoduje to niejednoznaczności. Uwaga!
    Brana pod uwagę jest zwykle pierwsza litera, więc jeśli wpiszesz
    ,,list --gone'', ekg potraktuje to jako ,,list --get''.

    Komendy można wysyłać także przez potok lub internet. Wymagana jest do tego
	wtyczka remote control. Ładowanie /plugin +rc ustawienie potoku: 
	/set rc:remote_control pipe:/home/user/named_pipe


KLAWIATURA

    Jeśli nie masz doświadczenia w obsługiwaniu programów z emacsową
    filozofią obsługi klawiatury, oto lista obsługiwanych klawiszy:

	Up, Down		przeglądanie historii poleceń
	Left, Right		poruszanie się po aktualnej linii
        Ctrl-A, Home		idź na początek linii
	Ctrl-B			pogrubiona czcionka [3]
        Ctrl-D, Delete		usuń znak pod kursorem
        Ctrl-H, Backspace	usuń znak przed kursorem
        Ctrl-I, Tab		dopełnianie
	Ctrl-K			usuwa tekst od kursora do końca linii
        Ctrl-L			czyszczenie/odświeżanie ekranu
        Ctrl-M, Enter		zatwierdzenie linii
        Ctrl-Q			odblokowanie terminala
        Ctrl-S			zablokowanie terminala
	Ctrl-T			pochyła czcionka [3]
	Ctrl-V			pozwala wpisać dowolny znak [2]
        Ctrl-U			usunięcie aktualnej linii
        Ctrl-W, Alt-Backspace	usunięcie słowa przed kursorem
        Ctrl-Y			wklejenie ostatnio usuniętego bloku
        Ctrl-Z			przeniesienie programu w tło
	Ctrl-_			podkreślona czcionka [3]
	Alt-B			słowo do tyłu
	Alt-D			usunięcie słowa za kursorem
	Alt-F			słowo do przodu
	Alt-cyfra		przełączenie do podanego okna
	F1			pomoc
	F2			krótka lista dostępnych i zajętych
	F12 lub Alt-`		przełączenie do okna debugowania

    Lista ta obejmuje klawisze obsługiwane przed interfejs readline
    i ncurses, i nie zawiera kombinacji specyficznych dla tego pierwszego.
    
    Interfejs readline obsługuje również inne kombinacje klawiszy. Dokładna
    lista znajduje się w stronie manuala ,,readline'' w rozdziale ,,DEFAULT
    KEY BINDINGS''. Dodatkowo:

        Ctrl-D			zamyka rozmowę i anuluje wprowadzanie
	                        wiadomości wielolinijkowej

    Interfejs ncurses obsługuje kilka dodatkowych kombinacji:

	Page Up, Page Down	przewijanie ekranu
	Ctrl-F, Ctrl-G		j.w.
	Alt-A			przejdź do pierwszego aktywnego okna
	Alt-N			utwórz nowe okno
	Alt-K			zamknij aktualne okno
	Alt-G			ignoruj aktualnego rozmówcę
	Alt-Q do Alt-P		przełącza do okna 11 do 20
	Ctrl-Fn			przełącza do podanego okna (konsola FreeBSD)
	Ctrl-Enter		przejście do trybu wielolinijkowego
	Ctrl-P			poprzednie okno
	Ctrl-N			kolejne okno
	F3			włącza lub wyłącza listę kontaktów [1]
	F4			kolejna grupa w liście kontaktów

    Po wejściu do trybu wielolinijkowego poruszamy się za pomocą kursorów
    i zatwierdzamy ponownym wciśnięciem Ctrl-Enter. By anulować, wciskamy
    Esc i czekamy chwilę. Jeśli kombinacja ta nie jest obsługiwana przez
    terminal, można używać Alt-Enter lub wcisnąć Esc i zaraz po nim Enter.

    Dodatkowo, określonym kombinacjom klawiszy można przypisać różne
    komendy za pomocą polecenia ,,bind''.

    Ze względu na niestandardowe zachowanie niektórych typów terminali,
    mogą wystąpić problemy z kombinacją Alt-Shift-O lub Alt-O przy
    włączonym Caps Locku.

    [1] Klawisz F3 zmienia wartość zmiennej ,,contacts''. Jeśli wartość tej
        zmiennej była równa 0, wciśnięcie klawisza zmienia jej wartość na 2.
	Jeśli była równa 1, kolejne wciśnięcia F3 będą zmieniały wartość
	z 1 na 0 i z 0 na 1. 

    [2] Po wciśnięciu Ctrl-V należy wcisnąć klawisz, który chcemy wkleić.
        Dzięki temu możliwe jest wpisanie znaków typu Escape, Ctrl-L czy
	Ctrl-U.

    [3] W miejscu wciśnięcia klawisza pojawi się znak oznaczający kod
        klawisza w negatywie.

PLIK KONFIGURACYJNY

    Kolejność ładowania plików konfiguracyjnych jest następująca:
    1) /etc/ekg.conf (lub z innego katalogu wskazanego przez opcję
       --sysconfdir przekazaną skryptowi ./configure),
    2) ~/.ekg/config lub ~/.ekg/<profil>/config,
    3) /etc/ekg-override.conf

    Dzięki temu administrator może wymusić pewne opcje na klientach
    użytkowników, jak na przykład ,,server'' czy ,,proxy''. Globalne
    pliki konfiguracyjne można ignorować przez uruchomienie klienta
    z opcją ,,-N''.

GDZIE SZUKAĆ POMOCY

    Dobra rada numer jeden: zanim zaczniesz narzekać, że czegoś nie ma,
    przeczytaj plik TODO.

    Dobra rada numer dwa: plik ULOTKA mówi, co znajduje się w którym pliku
    dokumentacji.

    Dobra rada numer trzy: zanim zaczniesz narzekać, że czegoś nie ma,
    poszukaj w pliku ChangeLog.

    Dobra rada numer cztery: jeśli jesteś nowym użytkownikiem, nie pytaj
    się, czy coś da się zrobić, albo że przydałoby się. Program jest
    rozwijany od ponad roku, wielu ludzi korzysta z niego na co dzień,
    więc większość ,,bajerów'', o których możesz pomyśleć, na pewno jest
    już w programie.

WYSYŁANIE SMSÓW

    ekg korzysta z zewnętrznego programu do wysyłania smsów. Nie ma
    najmniejszego sensu dublowania tej funkcji, skoro i tak większość
    ma już zainstalowane odpowiednie skrypty/programy/cokolwiek.
    Wystarczy podać ścieżkę do takiego programu w zmiennej
    ,,sms_send_app''. Powinien przyjmować numer telefonu za pierwszy
    parametr i wiadomość za drugi. Ten ze strony http://ceti.pl/~miki/
    spełnia podane wymagania.

SYNTEZA MOWY

    ekg potrafi korzystać z zewnętrznej aplikacji do syntezy mowy, by
    odczytywać wszystko, co trafia na ekran. Wystarczy ustawić zmienną
    ,,speech_app'' na nazwę programu czytającego tekst z stdin. Jej
    ustawienie spowoduje również zmianę wyglądu programu, by wyświetlane
    komunikaty stały się łatwiejsze do wymówienia. Przykładowe ustawienia,
    gdy korzystamy z programu ,,powiedz'', to:

	set speech_app powiedz
	set make_window 0
	set display_sent 0
	set display_ack 3

    Program ,,powiedz'' można pobrać z
    http://cvs.pld.org.pl/SOURCES/powiedz_0.2.tgz

ZNANE PROBLEMY

    Jeśli nie możesz wpisywać polskich liter w interfejsie readline,
    dopisz do pliku /etc/inputrc lub ~/.inputrc następujące linie:

	set meta-flag on
	set convert-meta off
	set output-meta on

ROZPOZNAWANIE PŁCI

    Krótka wersja: Jeśli ekg źle rozpoznaje płeć, wpisz imię do listy
    kontaktów. W większości przypadków pomoże. No tak, nie masz pojęcia,
    jak to zrobić? ,,list pseudonim -f imię''. Pomogło? Świetnie. Nie
    pomogło? Czytaj dalej.

    Długa wersja: Jedną z najbardziej kontrowersyjnych cech programu jest
    automatyczne rozpoznawanie płci na podstawie ostatniej litery imienia
    lub gdy jest ono nieznane, pseudonimu. Gdy ostatnią literą jest ,,a'',
    ekg uznaje, że dana osoba jest kobietą. Na przykład, jeśli Twój znajomy
    ma pseudonim ,,Kuba'', wpisz do listy kontaktów imię ,,Jakub''.
    Problemy mogą wystąpić z rzadko spotykanymi imionami typu Barnaba
    czy Mercedes. W takim wypadku należy do imienia dopisać (chociażby
    po ukośniku lub w nawiasie) literę ,,a'' dla kobiet lub inną niż
    ,,a'' dla mężczyzn.

ZGŁASZANIE BŁĘDÓW

    Jeśli zauważysz jakiś błąd, sprawdź najnowszą wersję. Większość
    błędów jest poprawiana w ciągu jednego lub dwóch dni od chwili
    pojawienia się. Przy zgłaszaniu błędu, zaznacz, w której wersji
    występuje.

    Nie pisz o sprawach, które są już wymienione w pliku TODO, bo doskonale
    wiemy, że coś trzeba poprawić.

    Zaznacz, co to za system, jaka dystrybucja, jaka wersja.
    
    Jeśli błąd jest powtarzalny i związany z siecią, przejdź do okna debug
    i przyślij to, co zostaje tam wyświetlone przed samym wystąpieniem
    błędu (zwykle ~20 linijek wystarczy). Możesz też skorzystać z ukrytego
    polecenia ,,_debug_dump'', które zapisze ostatnie linie z debug do
    pliku lub też przed uruchomieniem ekg wpisać nazwę pliku, do którego
    przekierowany będzie debug, do zmiennej systemowej ,,EKG_DEBUG''.

    Jeśli program powoduje naruszenie ochrony pamięci i powstaje plik
    ,,core'', postępuj zgodnie z instrukcjami pokazanymi na ekranie --
    uruchom ,,gdb ekg core'', przyślij to, co się pojawi. Potem wydaj
    polecenie ,,bt'' i jego wynik również załącz do listu. Jeśli błąd
    może mieć coś wspólnego z siecią, wyślij utworzony plik ,,debug''.

    Jeśli program się zawiesi, nie reaguje na nic i zajmuje 100% czasu
    procesora, w innym oknie terminala wydaj polecenie ,,strace -p <pid>'',
    gdzie <pid> to numer procesu ekg (uzyskasz go poleceniem ,,ps x'')
    i wyślij ostatnie 20 linii.

    Informację o błędzie należy przesyłać na listę ekg2-users (nie trzeba
    się na nią zapisywać, szczegóły niżej), ponieważ w ten sposób dostaną
    ją (prawie) wszyscy autorzy kodu. Możliwe też, że któryś z użytkowników
    natknął się na to samo i wie, jak sobie z tym poradzić.

ŹRÓDŁA

    Snapshoty kodu są dostępne pod adresem http://ekg2.org/download.php
    Jeśli nie wystąpi żadne trzęsienie ziemi, brak prądu ani barykady na
    drogach, powinny być robione co 24 godziny, wieczorem.

    Poza snapshotami, co jakiś czas będą umieszczane na serwerze kolejne
    wersje klienta. Ze względu na organizację prac nad programem, w praktyce
    nie będą się one różnić znacznie od snapshotów. Przed wydaniem każdej
    wersji wstrzymane będzie dodawanie nowych opcji, by skupić się na
    usuwaniu błędów. Poza tym, ułatwi to pracę niektórym osobom zajmującym
    się tworzeniem paczek dla dystrybucji -- zamiast uaktualniania ich do
    nowych snapshotów, będą miały możliwość pakowania ,,stabilnych'' wersji.

    Część kodu jest ładnie udokumentowana, część nie. Komentarze czasami
    są bardzo głupie, ale jeśli się do trzeciej rano siedzi nad dziwnym
    segfaultem, ciężko się pohamować. Jeśli napiszesz jakiegokolwiek
    klienta, frontend czy coś takiego, daj znać -- odnośnik do projektu
    zostanie umieszczony na stronie ekg.

LISTA DYSKUSYJNA

    Istnieje lista dyskusyjna dla użytkowników ekg o adresie 
    ekg-users@lists.ziew.org. Aby się zapisać, należy wejść na 
    stronę o adresie:
	    
	http://lists.ziew.org/mailman/listinfo/ekg2-users
	
    oraz postępować według instrukcji tam zawartych.
    
AUTORZY

    Wymienione osoby miały mniejszy lub większy wpływ na rozwój biblioteki
    i klienta. Niektórzy pisali kod, pomagali analizować protokół, testowali
    na różnych systemach, inni podsyłali patche i bugreporty. Jeśli ktoś
    został pominięty, niech da znać. W każdym razie za to, jak wygląda ekg,
    odpowiedzialni są (w porządku alfabetycznym):

	Marek Antoniak <kfazi@kfazi.polnet.trzepak.pl>
	Wojciech Bojdoł <wojboj@htcon.pl>
	Tomasz Chiliński <chilek@chilan.com>
	Marcin Chojnowski <martii@obgyn.edu.pl>
	Piotr Domagalski <szalik@szalik.net>
	Michał Dorociński <zwierzak@venus.ci.uw.edu.pl>
	Tomasz Dudzisz <eileen@ds1.agh.edu.pl>
	Piotr Figiel <feeg@psychodelic.org>
	Rafał Florek <raf@regionet.regionet.pl>
	Artur Gawryszczak <gawrysz@camk.edu.pl>
	Stanisław Gurgacz <fig@pd21.tarnobrzeg.sdi.tpnet.pl>
	Darek Jackowski <ascent@home.pl>
	Rafał Janiczek <jojo@dexter.zst.bytom.pl>
	Dawid Jarosz <dawjar@poczta.onet.pl>
	Tomasz Jarzynka <tomee@cpi.pl>
	Kuba Jermak <kooba@irc.pl>
	Jarosław Kamper <jack@jack.eu.org>
	Asia Kaniewska <kj_asia@wp.pl>
	Wojtek Kaniewski <wojtekka@irc.pl>
	Maciej Korzeń <maciekk@linux.sky.pl>
	Paweł Kot <pkot@linuxnews.pl>
	Marek Kozina <klith@irc.pl>
	Adam Kruszewski <phantom@linux.bydg.org>
	Piotr Kupisiewicz <deli@rzepaknet.us>
	Adam Ludwikowski <adam.ludwikowski@wp.pl>
	Jakub Martyński <jakub@ceto.pl>
	Paweł Maziarz <drg@go2.pl>
	Marcin Mikuła <meecash@meecash.prv.pl>
	Arkadiusz Miśkiewicz <misiek@pld.org.pl>
	Jacek Osiecki <joshua@ceti.pl>
	Robert Osowiecki <magic.robson@rassun.art.pl>
	Adam Osuchowski <adwol@polsl.gliwice.pl>
	Maurycy Pawłowski <maurycy@kocham.cie.gov.pl>
	Artur Pietruk <arturp@plukwa.net>
	Jacek Pospychała <tri10o@bsod.org>
	Paweł Pruszkowski <arim@botrm.org>
	Jacek Rembisz <jr178783@zodiac.mimuw.edu.pl>
	Rafal Roszak <rmrmg@wp.pl>
	Krzysztof Składzień <coxoc@coxoc.org>
	Rafał Skoczylas <nils@secprog.org>
	Adrian Smarzewski <adrians@aska.com.pl>
	Walerian Sokołowski <ws171913@yahoo.com>
	Piotr Stolc <socrtp@sedez.iq.pl>
	Tomasz Torcz <zdzichu@irc.pl>
	Leszek Urbański <tygrys@moo.pl>
	Robert J. Woźny <speedy@ziew.org>
	Krzysztof Wójtowicz <misiolek@misiolki.prv.pl>
	Piotr Wysocki <wysek@linux.bydg.org>
	 
$Id$