Tworzenie strony podręcznika

Koziołek

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

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 <samp>man</samp>.
W tym artykule opisze jak wykonać własną stronę podręcznika.

Krótko o poleceniu man

Polecenie <samp>man</samp> 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 <samp>$MANPATH</samp>. Nie w każdym systemie jest jednak ona skonfigurowana. W razie czego można sprawdzić te informacje w pliku konfiguracyjnym <samp>/etc/man.config</samp>.

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 <samp>manX</samp>, 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 <samp>manl</samp> 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 <samp>nroff</samp>;

$ 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()
<samp>nroff</samp> 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 <samp>.P</samp> 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 <samp>.nf</samp>. 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 <samp>.TD 5</samp> i następnie <samp>.TD 10</samp> to w cięcie będzie miało 15 kolumn. * .IP "wyrażenie"- nowy akapit w którym <samp>wyrażenie</samp> (umieszczone w tej samej linii <samp>.IP</samp>) w pierwszym wierszu nie jest wcięte, a każdy kolejny wiersz jest wcięty i wyrównany do tego <samp>wyrażenia</samp> przydatne przy tworzeniu list. * .HP - to samo co <samp>.IP</samp> 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 <samp>man</samp> i po kropce * numeru lub litery wskazującej czego dotyczy podręcznik. Patrz Krótko o poleceniu man.

0 komentarzy