Mamy już gotowy skrypt. Chcemy oddać go światu. Należy jeszcze dopisać dokumentację...

1 Wstęp
2 Krótko o poleceniu man
3 Podział podręczników
4 Uniwersalna struktura podręcznika
5 Podstawowa składnia
6 Upiększanie tekstu
7 Inne przydatne polecenia
8 Instalacja podręcznika

Wstęp

Standardowym sposobem dystrybucji dokumentacji w systemach rodziny UNIX są strony manuala. Wpisując w linii poleceń:

$ man man 

Otwarta zostanie odpowiednia strona podręcznika dotycząca w tym przypadku polecenia man.
W tym artykule opisze jak wykonać własną stronę podręcznika.

Krótko o poleceniu man

Polecenie man służy do wyświetlania sformatowanych stron podręcznika. Same strony są to pliki tekstowe w których używana jest specjalna składnia. Co do zasady listę katalogów zawierających strony podręcznika przechowuje zmienna $MANPATH. Nie w każdym systemie jest jednak ona skonfigurowana. W razie czego można sprawdzić te informacje w pliku konfiguracyjnym /etc/man.config.

Podział podręczników

Linux jest bardzo rozbudowanym systemem. Dlatego też w celu ułatwienia przeszukiwania bazy manuali podzielono ją na kilka kategorii. Każda kategoria znajduje się w osobnym podkatalogu w katalogu z podręcznikami. Podkatalogi mają nazwę stworzoną według wzorca manX, gdzie X:

• 0 - Pliki nagłówkowe.
• 1 - Polecenia standardowe.
• 2 - Wywołania systemowe i komunikaty jądra.
• 3 - Standardowe funkcje biblioteki c.
• 4 - Urządzenia specjalne.
• 5 - Formaty plików i używane konwencje.
• 6 - Gry i gadżety.
• 7 - Różności w tym standardy ISO, SQL.
• 8 - Polecenia roota.
• 9 - Dokumentacja jądra.
• n - Dokumentacja TCL/Tk.
• l - Polecenia lokalne.

Nas interesować będzie przede wszystkim manl jako najlepiej pasujący do naszych zadań.

Uniwersalna struktura podręcznika

Otwierając dowolna stronę podręcznika można zauważyć, że został on napisany i podzielony na rozdziały zgodnie z pewna konwencją. Poniższa lista zawiera listę elementów, które są obecne w większości podręczników. Elementy napisane pogrubioną czcionką są obowiązkowe (nic się nie stanie jak ich nie będzie, ale twój podręcznik będzie bezużyteczny albo bardzo trudny do przeczytania):

• Name
• Synopsis
• Configuration
• Description
• Options
• Exit Status
• Return Value
• Errors
• Environment
• Files
• Versions
• Conforming to
• Notes
• Bugs
• Author
• Example
• See also

Co do zasady podręczniki tworzone są w języku angielskim. Jednak nie będziemy się wygłupiać i w tym artykule podręcznik będzie po polsku, ale bez polskich znaków. W zależności od wersji systemu operacyjnego obsługa polskich znaków może wyglądać różnie.

Podstawowa składnia

Składnia strony podręcznika nie jest skomplikowana, ale dość rygorystyczna. Podstawowymi elementami są:

• .TH - oznacza tytuł dokumentu widoczny w prawym i lewym górny oraz prawym dolnym rogu ekranu.
• .SH - oznacza sekcję wymienioną w poprzednim punkcie. Można to rozumie jako rozdział.
• .SS - oznacza podrozdział.
• .P - oznacza nowy akapit. Tekst w tej samej linii za tym znakiem będzie ignorowany.

Popatrzmy zatem na przykładowy plik manuala w którym wykorzystujemy te elementy:

.TH polecenie

.SH NAME
Nazwa naszego programu

.SH SYNOPSIS
polecenie

.SH DESCRIPTION
Opis dzialania naszego programu.
.P 
Dodatkowe informacje w nowym akapicie.
.SS Dodatkowe informacje
Dla konsoli Ziutka

.SH ERRORS
Nie ma bledow

.SH BUGS
Bugow tez nie ma

.SH AUTHOR
Koziolek

By obejrzeć jak będzie wyglądała nasza strona wystarczy w konsoli uruchomić program nroff;

$ nroff -man manual 

polecenie()                                                        polecenie()



NAME
       Nazwa naszego programu


SYNOPSIS
       polecenie


DESCRIPTION
       Opis dziaÅania naszego programu.

       Dodatkowe informacje w nowym akapicie.

   Dodatkowe informacje
       Dla konsoli Ziutka


ERRORS
       Nie ma bledow


BUGS
       Bugow tez nie ma


AUTHOR
       Koziolek




                                                                   polecenie()

nroff jest to program, który oryginalnie służył do formatowania tekstu dla drukarek i konsoli w systemie UNIX.

Upiększanie tekstu

Suchy tekst podręcznika nie jest ciekawy. Zazwyczaj chcemy nadać niektórym słowom dodatkowe style takie jak pogrubienia czy pochyłość. Służą do tego polecenia:

• .B - tekst do końca linii jest pogrubiony.
• .I - tekst do końca linii jest pochyły.
• .R - powrót do normalnej czcionki.

alternatywna składnia:

• \fB
• \fI
• \fR

Polecam czytelnikowi poeksperymentowanie z tymi poleceniami.

Inne przydatne polecenia

Poniżej lista przydatnych poleceń:

• .br - przełamanie linii. W przeciwieństwie do .P nie dodaje pustego wiersza.
• .nf - wyłącza formatowanie tekstu. Przydatne jeżeli chcemy umieścić sformatowany tekst np. kod źródłowy. Wyłącza też domyślny sposób dzielenia słów.
• .fi - wyłącza .nf. Przywraca formatowanie.
• ./" - komentarz. Tekst w linii za tym ciągiem nie będzie wyświetlany.
• .TP X - wcięcie o X kolumn. Wcięcia się sumują. Zatem jeżeli w pliku użyjemy .TD 5 i następnie .TD 10 to w cięcie będzie miało 15 kolumn.
• .IP "wyrażenie"- nowy akapit w którym wyrażenie (umieszczone w tej samej linii .IP) w pierwszym wierszu nie jest wcięte, a każdy kolejny wiersz jest wcięty i wyrównany do tego wyrażenia przydatne przy tworzeniu list.
• .HP - to samo co .IP z ta różnicą, że wyrównanie jest stosowane tylko do pierwszego słowa.

Instalacja podręcznika

Wystarczy, jako root, skopiować plik do katalogu z podręcznikami i nadać prawa do odczytu dla wszystkich. Nazwa musi składać się z:

• nazwy, która będzie wykorzystywana przez man i po kropce
• numeru lub litery wskazującej czego dotyczy podręcznik. Patrz Krótko o poleceniu man.