Właściwe dokumentowanie kodu źródłowego jak i programów jest jednym z filarów kultury uniksowej, jak podaje Eric Steven Raymond w “The Art of UNIX Programming”. Pierwszą aplikacją w Uniksie była platforma do przygotowywania dokumentów, wykorzystywana przez laboratoria Bell Labs do przygotowywania dokumentów patentowych. Umiejętność pracy z dokumentacją, wyszukiwania potrzebnych wiadomości jest jednym z kluczy do sukcesu w pracy z systemami unix-like.

1. Dokumentacja lokalna

1.1. man

Tradycyjnie pierwszym i podstawowym źródłem informacji o danym programie są strony podręcznika man. Nazwa ta jest skrótem angielskiego słowa manual (instrukcja obsługi). Standardowo podręcznik podzielony jest na osiem części:

1. polecenia użytkowe
2. wywołania systemowe
3. funkcje biblioteczne
4. pliki specjalne
5. formaty plików
6. gry
7. różne
8. polecenia do administracji systemem

Każda strona podręcznika podzielona jest na następujące sekcje:

• nagłówek z nazwą polecenia oraz numerem sekcji podręcznika
• nazwa polecenia, w niektórych przypadkach również pozostałych poleceń opisanych na danej stronie
• streszczenie wszystkich parametrów wykorzystywanych przez dane polecenie
• krótki opis programu
• szczegółowe informacje na temat każdego parametru

W zależności od rodzaju polecenia oraz systemu, na którym pracujemy, mogą pojawić się też takie sekcje:

• zmienne środowiskowe
• diagnostyka
• błędy i ograniczenia
• autorzy
• prawa autorskie
• pliki konfiguracyjne

Aby wyświetlić stronę man danego polecenia, w konsoli wystarczy wpisać man nazwa_polecenia. Jeżeli dane polecenie opisane jest w kilku sekcjach, należy podać też numer sekcji. Np. sekcja pierwsza podręcznika zawiera opis polecenia open, natomiast sekcja druga zawiera opis wywołania systemowego open, tak więc aby zapoznać się z dokumentacją wywołania, w konsoli należy wpisać man 2 open. Po otwartej stronie man poruszamy się za pomocą kursorów. Aby wrócić do konsoli, wystarczy wpisać :q; aby na stronie znaleźć określoną frazę poniżej miejsca, w którym jest kursor, wystarczy wpisać /fraza, powyżej — ?fraza; n powtarza ostatnie wyszukanie. Polecenie man ma dwa ciekawe parametry związane z wyszukiwaniem odpowiedniej sekcji podręcznika. Wywołania polecenia z parametrem -a wyświetli wszystkie strony dla danego polecenia, jedna pod drugą. Natomiast uruchomienie z parametrem -w wyświetli tylko numery sekcji, w których dane polecenie się pojawia.

$ man -w open
/usr/share/man/cat2/open.0
/usr/share/man/cat3p/open.0

Poszczególne sekcje rozłożone są na podkatalogi i, jak widać na powyższym przykładzie, polecenie open pojawia się w 2 i 3 sekcji podręcznika man (przykład zaczerpnięty z systemu OpenBSD 4.1).
Do przeszukiwania stron podręcznika wykorzystywane są 2 polecenia: whatis i apropos.
Whatis służy do zwięzłego objaśniania działania poszczególnych poleceń i programów.

$ whatis ls mkdir cat man df
ls (1)               - list directory contents
mkdir (1)            - make directories
cat (1)              - concatenate files and print on the standard output
man (1)              - an interface to the on-line reference manuals
man (7)              - macros to format man pages
df (1)               - report file system disk space usage

Polecenie apropos wyszukuje podaną frazę na stronach podręcznika.

$ apropos 'list directory'
dir (1)              - list directory contents
ls (1)               - list directory contents
vdir (1)             - list directory contents

Zapytania mogą być bardziej skomplikowane:

$ apropos ext3 | grep create
mke2fs (8)           - create an ext2/ext3 filesystem
mkfs.ext2 (8)        - create an ext2/ext3 filesystem
mkfs.ext3 (8)        - create an ext2/ext3 filesystem

W powyższym przykładzie wyszukiwałem strony podręcznika, które mogą zawierać informacje na temat tworzenia systemu plików ext3. Ponieważ samo zapytanie apropos ext3 zwróciło na wyjściu bardzo dużo informacji, przefiltrowałem je za pomocą polecenia grep. Oczywiście nic nie stoi na przeszkodzie, by użyć wyrażeń regularnych. Man zawiera 2 parametry zastępujące polecenia whatis i apropos. Są to odpowiednio -f oraz -k. Istnieje możliwość wydrukowania interesujących nas stron dokumentacji — służy do tego parametr -t.

$ man -t ls > ls.ps

Utworzony został plik w formacie PostScript, natomiast z parametrem -t utworzony zostanie plik w formacie DeVice Independent (DVI).

$ man -T ls > ls.dvi

1.2. info

Info jest programem służącym do przeglądania dokumentacji stworzonej w formacie GNU Texinfo. Format ten wykorzystywany jest przez Free Software Fundation. Możliwe w nim jest hipertekstowe poruszanie się po dokumentach — przeskakiwanie do poszczególnych sekcji itp. Więcej na temat tego polecenia można dowiedzieć się na jego stronie man (man info) lub wydając polecenie info info. Przeglądanie dokumentacji można zacząć od polecenia info. Do nawigacji służą następujące przyciski:

Dokumentacja w formacie Texinfo ma formę drzewa.

1.3. /usr/share/doc

Lokalizacja /usr/share/doc/ to miejsce gdzie zwyczajowo znajduje się dokumentacja w formatach innych niż man i info. Na przykład użytkownicy Ubuntu znajdą książkę “Dive into Python“, w Debianie Etch znajdzie się kolekcja dokumentów How To (niestety niektóre przewodniki są bardzo przestarzałe), a w systemie OpenBSD znaleźć można “Dokumentację uzupełniającą dla programisty” (ang. “Programmer’s Supplementary Documents“), “Podręcznik administratora systemu” (ang. “System Manager’s Manual“), “Dokumentację uzupełniającą dla użytkownika”. Powyższe podręczniki dostępne są, jeżeli podczas instalacji zostanie wybrany zestaw instalacyjny misc41.tgz.

2. Dokumentacja w Internecie

Internet oferuje wiele źródeł dokumentacji i pomocy. Znajdziemy w nim mniej i bardziej oficjalne strony, wiki, fora, grupy dyskusyjne itd. Poszukiwania informacji warto rozpocząć od katalogu linków dostępnego w opisach systemów na stronie jakilinux.org. Chciałbym przedstawić kilka stron poświęconych tematyce administracji systemami unix-like.

2.1 deweloperWorks

Serwis, za którym stoi gigant rynku IT - IBM. Znaleźć w nim można dużo artykułów poświęconych administracji systemami unix-like o różnym stopniu zaawansowania, jak np. artykuły na temat tworzenia oprogramowania. Publikacje dostępne są za darmo zarówno w wersji on-line, jak i pdf. W przypadku niektórych wymagana jest darmowa rejestracja.

2.2. Big Admin

Wortal administratorów systemów, poświęcony głównie systemom Solaris. Artykuły dostępne są za darmo, rejestracja nie jest wymagana.

2.3. OnLamp, Linuxdevcenter

Serwisy związane ze znanym wydawnictwem O’Reilly, skupione wokół O’Reilly Network. W pierwszym można znaleźć artykuły poświęcone nie tylko dystrybucjom Linuksa, ale też rodzinie BSD i programowaniu w językach PHP, Python, Perl. Rejestracja wymagana jest jedynie w przypadku komentowania; płatny jest jedynie dostęp do książek w wersji elektronicznej.

2.4. Linux Documentation Project

Jest to inicjatywa mająca na celu stworzenie zbioru dokumentacji dla dystrybucji Linuksa. Dostępne są tam przewodniki, poradniki HOWTO, zbiory najczęściej zadawanych pytań, manuale. Przewodniki są niezależne od dystrybucji, dostępne za darmo w różnych formatach.