Blog

Dobra dokumentacja to jeden z filarów sukcesu każdego projektu. Istotne jest, aby zawierała jak najświeższe informacje oraz żeby wprowadzanie zmian nie wiązało się ze zbyt dużym narzutem czasowym. Dzisiaj postaram się przybliżyć, jak prosta automatyzacja oraz korzystanie z dostępnych narzędzi pomaga tworzyć dokumentację w formie man pages.

Często, gdy szukamy rozwiązania jakiegoś problemu technicznego związanego z oprogramowaniem, napotykamy użytkownika lub wpis w FAQ odsyłający do dokumentacji (najczęściej za pomocą skrótu RTFM! – czyli Read The… Friendly Manual, choć „F” w tym skrócie często przybiera bardziej nieparlamentarne zabarwienie). Niestety jakość udostępnianych stron pomocy często pozostawia wiele do życzenia, a rozwiązania częstych problemów można znaleźć dopiero po przebrnięciu przez długie i nieprzystępnie napisane listy poszczególnych przełączników. W tym artykule postaram się przybliżyć, jak wykorzystać polecenie man do prowadzenia własnej dokumentacji, która faktycznie będzie pozwalała zakrzyknąć „RTFM!”.

Trochę o poleceniu man

Standardowym sposobem pozyskiwania wiedzy na temat działania programów w systemach uniksopodobnych, jest czytanie stron podręcznika systemowego, do którego dostęp daje polecenie man. Jest to jeden z najstarszych sposobów na interakcję z dokumentacją systemową (niedługo będzie kończyć 50 lat!). Myślę więc, że nie ma sensu przeciągać wstępu, ponieważ pisanie man $NAZWA_POLECENIA jest już od dawna wryte w pamięć mięśniową każdego administratora.

Dla przypomnienia wspomnę jednak, że podręcznik systemowy jest podzielony na sekcje tematyczne. Jedne z najważniejszych to:

• 1 – Programy wykonywalne lub polecenia powłoki
• 5 – Formaty plików i konwencje, np. /etc/passwd
• 8 – Polecenia do administracji systemem.

Strony dokumentacji są formatowane przy użyciu polecenia troff, które jest stosunkowo starym formatem. Jego zaletą jest to, że w prosty sposób można do niego skonwertować dokument przygotowany np. w markdown. Więcej na temat formatowania przy użyciu troff można znaleźć na stronie podręcznika man(7)

Konfiguracja własnej sekcji man

Aby nie konfliktować z już istniejącymi sekcjami podręcznika, skonfigurujemy lokalny katalog, w którym będą znajdowały się strony sekcji, którą sami stworzymy. Zakładamy tutaj, że stworzona zostanie sekcja dla użytkownika, ale nic nie stoi na przeszkodzie, aby stworzyć współdzielony na serwerze ogólny katalog z dostępem dla wszystkich użytkowników. W tym celu skorzystamy z dwóch zmiennych:

• MANPATH – lista ścieżek, w których szukane są strony manuala
• MANSECT – kolejność sekcji podczas wyszukiwania strony.

Nowa sekcja, którą stworzymy, będzie nazywać się el. Będzie można z niej skorzystać przez wywołanie:

$ man el $NAZWASTRONY

Pierwszym krokiem pozwalającym na skorzystanie z tej sekcji, jest stworzenie lokalnego katalogu:

NAZWA_SEKCJI=el
mkdir -p ~/man/man$NAZWA_SEKCJI
echo "Lokalna dokumentacja" >> ~/man/man$NAZWA_SEKCJI/intro.$NAZWA_SEKCJI

Jak widać, wystarczy podmienić za zmienną inną nazwę i można stworzyć zupełnie nową sekcję o innej nazwie. Dodatkowo stworzyliśmy pierwszą (bardzo toporną) stronę dokumentacji, która zwyczajowo zawiera opis sekcji, do której należy.

Teraz, aby móc skorzystać ze stworzonej sekcji, wystarczy, że poinformujemy mana, gdzie ma szukać. Do tego wystarczy dodać do konfiguracji powłoki, na przykład w .bashrc, dwie deklaracje zmiennych.

# Ścieżka przeszukiwania dla man
MANPATH="$MANPATH:~/man"

# Kolejność przeszukiwania sekcji
MANSECT="1:1p:8:2:3:3p:4:5:6:7:9:0p:n:l:p:o:1x:2x:3x:4x:5x:6x:7x:8x:el"

By wydobyć aktualną wartość dla zmiennej MANSECT, można skorzystać na przykład z poniższej komendy:

$ grep "^[^#]" /etc/man_db.conf | grep SECTION | awk -F'\t' '{print $3;}' | sed 's/ /:/g'
1:1p:8:2:3:3p:4:5:6:7:9:0p:n:l:p:o:1x:2x:3x:4x:5x:6x:7x:8x

Teraz można już dostać się do naszej lokalnej sekcji:

 

Można się oczywiście zastanowić, czy lokalna dokumentacja nie powinna być pierwszym źródłem informacji i odpowiednio dodać nową sekcję na początek w zmiennej MANSECT.

Niemniej, teraz pozostaje już tylko ułatwić pisanie dokumentacji w sposób, który pozwala na formatowanie tekstu.

Pisanie stron lokalnej dokumentacji

Świetnym narzędziem do konwersji formatów tekstowych jest Pandoc, dzięki któremu będziemy mogli skonwertować napisany w markdown tekst do formatu odpowiedniego dla mana.

Poniżej prezentujemy szkielet strony dokumentacji. W tym wypadku postaramy się poprawić wcześniej utworzoną stronę intro:

---
title: INTRO
section: el
date: "2019-08-14"
footer: Linux
header: "Lokalna dokumentacja"
author:
- groot@guardians-of-galaxy
- starlord@guardians-of-galaxy
...

# NAZWA

intro - opis sekcji el

## OPIS

W tej sekcji można znaleźć rozwiązania problemów napotkanych przy utrzymaniu
lokalnych serwisów oraz lokalną dokumentację dla programów zainstalowanych w
systemie.

Początek pliku stanowi YAML, który zawiera metadane dla pandoca, w celu wygenerowania poprawnej linijki tytułowej dla mana. Ogranicznikami tego bloku są --- oraz .... Poszczególne dane można znaleźć w pliku template, z którego korzysta konwerter. Plik dla stron man można znaleźć w /usr/share/pandoc 1.12.3.1/data/templates/default.man, z dokładnością co do wersji pandoca. Warto zwrócić uwagę, że dzięki zdefiniowaniu informacji o autorach ta informacja zostanie dynamicznie dodana na koniec naszej strony podręcznika.

Mając tak przygotowany plik, możemy go skonwertować, wywołując:

pandoc --standalone -t man intro.el.markdown -o ~/man/manel/intro.el

Bardzo istotne jest to, aby nie zapomnieć o dodaniu opcji --standalone. W przeciwnym wypadku strona nie będzie się poprawnie wyświetlać.

Teraz naszym oczom powinna ukazać się strona podręcznika, która wygląda już dużo lepiej:

 

Dalsze usprawnienia tworzenia dokumentacji

W tym momencie pewnie można by już zakończyć opis tworzenia dokumentacji w ten sposób, ale kim byłby informatyk, gdyby nie próbował zautomatyzować swojego workflow? W tym celu przedstawię krótkie, acz przydatne funkcje, które można umieścić w swoim .bashrc.

Po pierwsze, tworzenie nowej strony ze szkieletu wydaje się być pierwszym zadaniem wartym przyspieszenia.

manpage_new(){
    cat << MANPAGE > ~/man/$1.el.md
---
title: $(perl -E 'say uc $ARGV[0]' $1)
section: el
date: "2019-08-14"
footer: Linux
header: "Lokalna dokumentacja"
...
# NAZWA

# OPIS
MANPAGE
}

W ten sposób nową stronę możemy utworzyć przez wywołanie:

$ new_manpage hello

Kolejnym krokiem może być automatyzacja otwierania pliku do edycji:

manpage_edit(){
    ${EDITOR:-vim} ~/man/$1.el.md
}

Po edycji nowo utworzonego pliku ostatnim wymaganym elementem będzie generacja pliku w formacie troff:

manpage_gen(){
    pandoc -s -f markdown -t man ~/man/$1.el.md -o ~/man/manel/$1.el
}

Łącząc stworzone funkcje, można w bardzo szybki sposób stworzyć nową stronę w dokumentacji lokalnej.

Podsumowanie

Mam nadzieję, że eksploracja tego dość starego już narzędzia zachęci naszych czytelników do własnych poszukiwań nowych zastosowań programów, które uznajemy za pewnik. Szczególnie jeśli jedną z maksym ich powstania było (parafrazując) „rób jedną rzecz, ale dobrze”. W tym przypadku myślę, że włączenie lokalnych stron man do pracy np. zespołu deweloperskiego, może okazać się prostym sposobem na dzielenie się wiedzą na temat systemów, z którymi na co dzień przychodzi nam pracować. Dziękujemy za poświęcenie czasu na lekturę tekstu oraz zachęcamy do zapisania się na nasz newsletter.