Eksperymentalny Klient Gadu-Gadu

          (C) Copyright 2001-2007 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/

    Program ekg i biblioteka libgadu zostały napisane na podstawie informacji
    uzyskanych przez badanie pakietów wysyłanych między klientem
    a serwerem oraz od osób trzecich. Autorzy nie disasemblowali
    ani nie dekompilowali oryginalnego klienta. Projekt powstał przy
    użyciu darmowych i wolnodostępnych narzędzi.

    Gadu-Gadu jest zastrzeżonym znakiem towarowym Gadu-Gadu S.A.

WYMAGANIA

    Do komunikacji z serwerami Gadu-Gadu program wymaga biblioteki libgadu,
    która jest udostępniona oddzielnie. Więcej informacji o tym jak ją pobrać
    i zainstalować, znajdziesz w pliku libgadu.txt

    Program domyślnie korzysta z biblioteki ncurses, więc powinny być
    zainstalowane odpowiednie pakiety zawierające bibliotekę oraz pliki
    nagłówkowe. Jeśli chcesz użyć starego interfejsu, do polecenia
    configure dodaj ,,--disable-ui-ncurses''. Interfejs ten wymaga
    zainstalowania biblioteki readline wraz z plikami nagłówkowymi.
    readline zwykle polega też na innych bibliotekach do obsługi
    terminala, jak np. libtermcap czy ncurses. Instalacja obu interfejsów
    naraz nie jest wskazana. Oczywiście niezbędny jest też zestaw narzędzi
    do kompilacji programów napisanych w języku C -- kompilator,
    preprocesor, linker, pliki nagłówkowe, biblioteki systemowe itd.
    Jeśli skrypt ./configure zgłosi jakieś błędy, skontaktuj się ze swoim
    administratorem.

    ekg 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.

INSTALACJA

    Rozpakować poleceniem ,,tar zxvf ekg-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/ekg
    --mandir=$HOME/ekg/share/man''. Po zainstalowaniu w ten sposób,
    program gotowy do uruchomienia będzie znajdował się w katalogu
    ekg/bin w katalogu domowym. Jeśli chcemy mieć możliwość używania
    poleceń ,,beeps_spk'' i ,,blink_leds'', służących m.in do
    manipulowania diodami LED na klawiaturze, należy przy uruchomieniu
    użyć parametru ,,--enable-ioctld''.

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

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 rozdziale
    ,,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 chcesz 
    skrócić ,,list --gone'' do ,,list -g'', ekg potraktuje to jako 
    ,,list --get''.

    Komendy można wysyłać także przez potok. By go uaktywnić, należy
    uruchomić ekg z parametrem ,,-c'' i ścieżką potoku. Ze względu na
    specyfikę potoków, wyniki poleceń wysyłane będą na terminal, na którym
    jest uruchomione ekg (tak jak normalnie). Pisać do potoku można tak
    jak do normalnego pliku (choćby poleceniem echo).

    Jeśli w linii poleceń shella podasz po nazwie programu i parametrach
    zaczynających się od myślnika coś jeszcze, to zostanie to zinterpretowane
    jako komenda wsadowa. ekg połączy się z serwerem, wykona tylko tę komendę
    i od razu wyjdzie. Jeśli na serwerze czekają na Ciebie jakieś wiadomości,
    to serwer je przyśle zaraz po połączeniu i w trybie wsadowym ekg wypisze
    je na terminal. Jeśli zamierzasz przekierować wyjście do /dev/null i nie
    masz włączonego logowania, wiadomości zginą bezpowrotnie.

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-R			kolor tekstu [3]
        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-S			przejdź do najstarszego aktywnego okna 
				(okna, które najdłużej jest aktywne)
	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
	Alt-Z			przewijanie listy kontaktów w górę
	Alt-X			przewijanie listy kontaktów w dół
	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
	F11			wybór informacji w pasku statusu

    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. By zmienić kolor tekstu, należy po Ctrl-R
	wpisać numer koloru od 0 do 15.

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) ~/.gg/config lub ~/.gg/<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 kilku lat, 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ę ekg-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://ekg.chmurka.net/
    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.

GRUPA DYSKUSYJNA

    Na serwerze news.chmurka.net istnieje prywatna grupa dyskusyjna chmurka.ekg, 
    poświęcona aplikacji. Dane serwera:

        Adres: news.chmurka.net
        Użytkownik: ekg
        Hasło: ekg

    Aby się zapisać, należy skorzystać z czytnika grup dyskusyjnych (nntp), 
    np. pine / alpine, Pan, tin, slrn.

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 <[email protected]>
	Wojciech Bojdoł <[email protected]>
	Kamil Brzeziński <[email protected]>
	Tomasz Chiliński <[email protected]>
	Marcin Chojnowski <[email protected]>
	Piotr Domagalski <[email protected]>
	Michał Dorociński <[email protected]>
	Tomasz Dudzisz <[email protected]>
	Piotr Figiel <[email protected]>
	Rafał Florek <[email protected]>
	Artur Gawryszczak <[email protected]>
	Stanisław Gurgacz <[email protected]>
	Darek Jackowski <[email protected]>
	Rafał Janiczek <[email protected]>
	Dawid Jarosz <[email protected]>
	Tomasz Jarzynka <[email protected]>
	Kuba Jermak <[email protected]>
	Jarosław Kamper <[email protected]>
	Asia Kaniewska <[email protected]>
	Wojtek Kaniewski <[email protected]>
	Maciej Korzeń <[email protected]>
	Paweł Kot <[email protected]>
	Marek Kozina <[email protected]>
	Adam Kruszewski <[email protected]>
	Piotr Kupisiewicz <[email protected]>
	Adam Ludwikowski <[email protected]>
	Jakub Martyński <[email protected]>
	Paweł Maziarz <[email protected]>
	Marcin Mikuła <[email protected]>
	Arkadiusz Miśkiewicz <[email protected]>
	Jacek Osiecki <[email protected]>
	Robert Osowiecki <[email protected]>
	Adam Osuchowski <[email protected]>
	Marcin Owsiany <[email protected]>
	Maurycy Pawłowski <[email protected]>
	Artur Pietruk <[email protected]>
	Jacek Pospychała <[email protected]>
	Paweł Pruszkowski <[email protected]>
	Jacek Rembisz <[email protected]>
	Rafal Roszak <[email protected]>
	Krzysztof Składzień <[email protected]>
	Rafał Skoczylas <[email protected]>
	Adrian Smarzewski <[email protected]>
	Walerian Sokołowski <[email protected]>
	Piotr Stolc <[email protected]>
	Tomasz Torcz <[email protected]>
	Leszek Urbański <[email protected]>
	Robert J. Woźny <[email protected]>
	Krzysztof Wójtowicz <[email protected]>
	Adam Wysocki <[email protected]>
	Piotr Wysocki <[email protected]>

$Id$