Jak stworzyć stronę man w systemie Linux

Chcesz, aby twój nowy program działający na systemie Linux miał profesjonalny wygląd? Daj mu stronę z dokumentacją. W tym artykule pokażemy ci najprostszy i najszybszy sposób na osiągnięcie tego celu.

Strony z dokumentacją

W znanym żarcie o Uniksie kryje się ziarno prawdy: „jedynym poleceniem, które musisz znać, jest man”. Strony z dokumentacją zawierają ogromną ilość informacji i powinny być pierwszym miejscem, gdzie szukasz wiedzy na temat konkretnego polecenia.

Oferując stronę z dokumentacją dla swojego narzędzia lub polecenia, przekształcasz je z użytecznego fragmentu kodu w pełnoprawny pakiet dla systemu Linux. Użytkownicy oczekują, że każdy program napisany dla tego systemu będzie miał dołączoną stronę z dokumentacją. W przypadku programów natywnie wspierających Linux, posiadanie takiej strony jest niezbędne, jeśli chcesz, by twój projekt był traktowany poważnie.

Dawniej, pisanie stron z dokumentacją odbywało się z użyciem zestawu makr formatowania. Kiedy wywołujesz komendę man, uruchamia ona program groff, który przetwarza plik i generuje odpowiednio sformatowane dane wyjściowe. Wynik jest następnie przesyłany do programu less, skąd jest wyświetlany dla użytkownika.

Jeśli nie tworzysz często stron z dokumentacją, ręczne wstawienie makr może być dość żmudne. Opracowanie strony, która jest prawidłowo sformatowana i czytelna, może być bardziej skomplikowane, niż się wydaje, przy jednoczesnym zachowaniu zwięzłości i precyzji opisu polecenia.

Skup się na treści, a nie na walce z mało znanym zestawem makr.

Pandoc na ratunek

Program pandoc potrafi czytać pliki w formacie Markdown i generować nowe dokumenty w około czterdziestu różnych językach znaczników oraz formatach, w tym stronach man. Dzięki temu znacznie ułatwia proces pisania strony z dokumentacją, eliminując konieczność zmagań z trudnymi do zrozumienia makrami.

Aby rozpocząć, możesz zainstalować pandoc na systemie Ubuntu, wykonując poniższe polecenie:

sudo apt-get install pandoc

Dla systemu Fedora polecenie to:

sudo dnf install pandoc

Dla Manjaro użyj polecenia:

sudo pacman -Syu pandoc

Sekcje strony z dokumentacją

Strony z dokumentacją mają ustalone sekcje zgodnie z powszechnie stosowanymi konwencjami. Sekcje, które powinny być zawarte w twojej stronie, zależą od złożoności opisywanego polecenia.

Większość stron z dokumentacją zawiera przynajmniej następujące sekcje:

• Nazwa: nazwa polecenia oraz krótki opis jego funkcji.
• Streszczenie: krótki opis możliwych wywołań, jakie mogą być użyte do uruchomienia programu, w tym typy akceptowanych argumentów wiersza poleceń.
• Opis: szczegółowy opis polecenia lub funkcji.
• Opcje: lista dostępnych opcji wiersza poleceń i ich opis.
• Przykłady: kilka przykładów typowego użycia.
• Wartości wyjściowe: możliwe kody powrotne oraz ich znaczenie.
• Błędy: lista znanych problemów i nietypowych zachowań, często uzupełniona linkiem do narzędzia do śledzenia problemów projektu.
• Autor: osoba lub osoby odpowiedzialne za stworzenie polecenia.
• Prawa autorskie: informacje dotyczące praw autorskich oraz typ licencji, na podstawie której program jest udostępniany.

Przeglądając bardziej złożone strony z dokumentacją, można zauważyć, że zawierają one również inne sekcje. Na przykład, sprawdź man man. Nie musisz jednak uwzględniać wszystkich sekcji – jedynie te, które są naprawdę potrzebne. Strony z dokumentacją nie są miejscem na zbędne rozważania.

Inne sekcje, które często występują, to:

• Zobacz też: inne powiązane polecenia, które mogą być użyteczne.
• Pliki: lista plików zawartych w pakiecie.
• Ostrzeżenia: inne kwestie, które warto mieć na uwadze.
• Historia: historia zmian w poleceniu.

Sekcje podręcznika

Podręcznik systemu Linux składa się ze wszystkich stron z dokumentacją, które są podzielone na ponumerowane sekcje:

• Programy wykonywalne: polecenia powłoki.
• Wywołania systemowe: funkcje dostarczane przez jądro.
• Wywołania bibliotek: funkcje dostępne w bibliotekach programowych.
• Pliki specjalne.
• Formaty plików i konwencje: na przykład „/etc/passwd”.
• Gry.
• Różne: pakiety i konwencje makr, takie jak groff.
• Polecenia administracyjne systemu: zazwyczaj zarezerwowane dla użytkownika root.
• Procedury jądra: często nieinstalowane domyślnie.

Każda strona z dokumentacją musi wskazywać swoją sekcję oraz być przechowywana w odpowiednim miejscu, co omówimy później. Strony man dla poleceń i narzędzi są zazwyczaj umieszczane w sekcji pierwszej.

Format strony z dokumentacją

Format makr groff nie jest łatwy do wizualnej analizy, podczas gdy Markdown jest znacznie bardziej przystępny.

Poniżej znajduje się przykładowa strona z dokumentacją w formacie groff.

Ta sama strona jest pokazana poniżej w formacie Markdown.

Materiał wstępny

Pierwsze trzy wiersze tworzą to, co nazywamy materiałem wstępnym. Każdy z nich musi zaczynać się od znaku procenta (%), bez spacji wiodących, a po nim:

• Pierwsza linia: zawiera nazwę polecenia, a po niej sekcja instrukcji w nawiasach, bez spacji. Nazwa staje się lewą i prawą częścią nagłówka strony. Zgodnie z konwencją, nazwa polecenia jest zapisywana wielkimi literami, choć wiele z nich nie jest. Wszystko, co następuje po nazwie polecenia i numerze sekcji, staje się lewą częścią stopki. Jest to przydatne do umieszczenia numeru wersji oprogramowania.
• Druga linia: nazwisko autora (lub autorów), które będą wyświetlane w automatycznie generowanej sekcji autorów strony. Nie musisz dodawać sekcji „Autorzy” – wystarczy wpisać co najmniej jedno nazwisko.
• Trzecia linia: data, która także staje się częścią stopki.

Nazwa

Sekcje są oznaczane liniami zaczynającymi się od znaku liczby (#), który wskazuje nagłówek w formacie Markdown. Znak liczby musi być pierwszym znakiem w wierszu, po którym następuje spacja.

Sekcja nazwy zawiera krótką, jednoliniową informację, która składa się z nazwy polecenia, spacji, myślnika (-), spacji, a następnie krótkiego opisu funkcji polecenia.

Streszczenie

Streszczenie zawiera różne formaty, które mogą być używane w wierszu poleceń. To polecenie może akceptować wzorzec wyszukiwania lub opcję z wiersza poleceń. Dwie gwiazdki (**) umieszczone po obu stronach nazwy polecenia sprawiają, że zostaje ona pogrubiona na stronie z dokumentacją. Pojedyncza gwiazdka umieszczona po obu stronach tekstu powoduje, że jest on wyświetlany jako podkreślony.

Domyślnie, po podziale wiersza następuje pusty wiersz. Aby wymusić twardą przerwę bez pustej linii, możesz użyć ukośnika odwrotnego na końcu wiersza.

Opis na stronie z dokumentacją wyjaśnia, co robi dane polecenie lub program. Powinien zwięźle przedstawiać istotne szczegóły. Pamiętaj, że nie piszesz instrukcji obsługi.

Użycie dwóch znaków liczbowych (##) na początku wiersza tworzy nagłówek drugiego poziomu. Możesz ich użyć, aby podzielić opis na mniejsze sekcje.

Sekcja opcji zawiera opis wszystkich opcji wiersza poleceń, które można stosować z danym poleceniem. Zgodnie z konwencją, opcje są pogrubione, więc należy umieścić przed nimi dwie gwiazdki (**). Opis opcji powinien zaczynać się od dwukropka (:), po którym następuje spacja.

Jeśli opis jest wystarczająco krótki, man wyświetli go w tym samym wierszu, co opcja wiersza poleceń. Jeśli jest zbyt długi, pojawi się jako akapit w nowym wierszu z wcięciem, które zaczyna się poniżej opcji.

Sekcja przykładów zawiera różne formaty użycia wiersza poleceń. Zauważ, że linie opisu zaczynamy od dwukropka (:), tak jak w sekcji opcji.

Sekcja wartości wyjściowych przedstawia kody zwracane przez polecenie, które są przekazywane do wywołującego proces. Może to być powłoka, jeśli wywołujesz ją z wiersza poleceń, lub skrypt, jeśli uruchamiasz go z innego skryptu powłoki. Opisy w tej sekcji również zaczynamy od dwukropka (:).

Sekcja błędów przedstawia znane problemy, pułapki lub inne dziwactwa, o których użytkownicy powinni być świadomi. Dla projektów typu open source często umieszcza się tu link do narzędzia do śledzenia problemów, aby sprawdzić stan zgłoszonych błędów lub dodać nowe.

Sekcja dotycząca praw autorskich zawiera informacje o prawach autorskich oraz zazwyczaj typ licencji, na podstawie której oprogramowanie jest wydawane.

Efektywny przepływ pracy

Możesz edytować swoją stronę z dokumentacją w preferowanym edytorze. Większość edytorów obsługujących podświetlanie składni wyróżnia nagłówki oraz pogrubiony i podkreślony tekst. To świetne, ale pamiętaj, że nie patrzysz na rzeczywistą wyrenderowaną stronę z dokumentacją, która jest prawdziwym testem jakości.

pandoc ms.1.md -s -t man | /usr/bin/man -l -

Po wpisaniu tego polecenia możesz użyć strzałki w górę, aby je powtórzyć, a następnie nacisnąć Enter.

To polecenie wywołuje również pandoc, przetwarzając plik markdown (tu nazwany „ms.1.md”):
Opcja -s (samodzielna) generuje kompletną stronę dokumentacji od początku do końca, zamiast tylko tekstu w formacie man.

Opcja -t (typ wyjścia) z operatorem „man” instruuje pandoc, aby wygenerował dane wyjściowe w formacie man. Nie kazaliśmy pandocowi zapisywać danych wyjściowych do pliku, więc zostaną one wysłane na standardowe wyjście.

Przekierowujemy również dane wyjściowe do man za pomocą opcji -l (plik lokalny). Mówi to manowi, aby nie przeszukiwał bazy danych man w poszukiwaniu strony z dokumentacją, lecz otworzył wskazany plik. Jeśli plik ma nazwę „-„, man pobierze dane wejściowe ze standardowego wejścia.

Oznacza to, że po zapisaniu w edytorze możesz nacisnąć Q, aby zamknąć man, gdy działa w terminalu. Następnie możesz użyć strzałki w górę i nacisnąć Enter, aby zobaczyć wyrenderowaną wersję swojej strony z dokumentacją w man.

Tworzenie strony z dokumentacją

pandoc ms.1.md -s -t man -o ms.1

To polecenie instruuje pandoc, aby wygenerował stronę z dokumentacją o nazwie „ms.1”:

manpath

Wyniki polecenia dostarczają następujące informacje:
/usr/share/man: standardowa lokalizacja dla stron z dokumentacją. Nie dodajemy nowych stron do tej biblioteki.
/usr/local/share/man: to dowiązanie symboliczne wskazujące na „/usr/local/man”.

/usr/local/man: to miejsce, gdzie musimy umieścić naszą nową stronę z dokumentacją.

Zauważ, że różne sekcje podręcznika są przechowywane w osobnych katalogach: man1, man2, man3 itd. Jeśli katalog dla danej sekcji nie istnieje, musimy go utworzyć.

sudo mkdir /usr/local/man/man1

Aby to zrobić, wpisujemy:

sudo cp ms.1 /usr/local/man/man1

Następnie kopiujemy plik „ms.1” do odpowiedniego katalogu: man oczekuje, że strony z dokumentacją będą skompresowane, więc użyjemy gzip do ich kompresji.

sudo gzip /usr/local/man/man1/ms.1

Na koniec, aby zaktualizować bazę danych man, wpisujemy:

sudo mandb

Wpisujemy polecenie:

man ms

Teraz możemy wywołać naszą nową stronę z dokumentacją, jak każdą inną, wpisując:

man ms w oknie terminala.

Oto górna sekcja nowej strony dokumentacji.

Środkowa sekcja nowej strony dokumentacji.

Dolna sekcja nowej strony dokumentacji.

Automatycznie wygenerowana sekcja „Autorzy” zawiera również numer wersji oprogramowania, datę oraz nazwę polecenia, zgodnie z definicją na początku.

Jeśli masz jakiekolwiek pytania lub potrzebujesz dodatkowych informacji, nie wahaj się skontaktować.