Jak stworzyć stronę man w systemie Linux

Chcesz, aby Twój nowy program dla systemu Linux wyglądał profesjonalnie? Daj mu stronę man . Pokażemy Ci najłatwiejszy i najszybszy sposób na zrobienie tego.

Człowiek Pages

W starym dowcipie uniksowym jest ziarno prawdy: „jedynym poleceniem, które musisz znać, jest man ”. Strony man zawierają bogactwo wiedzy i powinny być pierwszym miejscem, do którego się zwracasz, gdy chcesz dowiedzieć się czegoś o poleceniu.

Dostarczenie strony man dla narzędzia lub polecenia, które napisałeś, podnosi go z użytecznego fragmentu kodu do w pełni sformatowanego pakietu Linux. Ludzie oczekują man że zostanie udostępniona strona podręcznika dla programu napisanego dla Linuksa. Jeśli natywnie wspierasz Linuksa, strona man jest obowiązkowa, jeśli chcesz, aby Twój program był traktowany poważnie.

Historycznie strony man były pisane przy użyciu zestawu makr formatujących. Kiedy wzywasz man do otwarcia strony, wywołuje on groff w celu odczytania pliku i wygenerowania sformatowanego wyjścia, zgodnie z makrami w pliku. Dane wyjściowe są przesyłane do less , a następnie wyświetlane.

Jeśli man tworzysz często stron podręcznika, napisanie jednej i ręczne wstawienie makr to ciężka praca. Czynność tworzenia strony podręcznika man która poprawnie analizuje i wygląda dobrze, może wyprzedzić twój cel, jakim jest dostarczenie zwięzłego, ale dokładnego opisu twojego polecenia.

Powinieneś koncentrować się na treści, a nie walczyć z niejasnym zestawem makr.

POWIĄZANE: Jak korzystać z polecenia man Linuksa: Ukryte tajemnice i podstawy

pandoc na ratunek

Program pandoc odczytuje pliki znaczników i generuje nowe w około 40 różnych językach znaczników i formatach dokumentów man w tym ze strony podręcznika. To całkowicie zmienia proces pisania stron podręcznika man dzięki czemu nie musisz zmagać się z hieroglifami.

Aby rozpocząć, możesz zainstalować pandoc na Ubuntu za pomocą tego polecenia:

 sudo apt-get zainstaluj pandoc 

W Fedorze potrzebne polecenie to:

 sudo dnf zainstaluj pandoc 

Na Manjaro wpisz:

 sudo pacman -Syu pandoc 

POWIĄZANE: Jak używać pandoc do konwertowania plików w wierszu poleceń systemu Linux

Sekcje człowieka Strona

strony man zawierają sekcje zgodne ze standardową konwencją nazewnictwa. Sekcje, których potrzebuje twoja strona man , są podyktowane złożonością polecenia, które opisujesz.

Większość stron podręcznika zawiera przynajmniej następujące sekcje:

• Nazwa : nazwa polecenia i zwięzła, jednowierszowa opisująca jego funkcję.
• Streszczenie : zwięzły opis wywołań, których można użyć do uruchomienia programu. Pokazują one typy akceptowanych parametrów wiersza polecenia.
• Opis : opis polecenia lub funkcji.
• Opcje : lista opcji wiersza poleceń i ich funkcji.
• Przykłady : kilka przykładów powszechnego użycia.
• Wartości wyjściowe : możliwe kody powrotu i ich znaczenie.
• Błędy : lista znanych błędów i dziwactw. Czasami jest to uzupełniane (lub zastępowane) linkiem do śledzenia problemów dla projektu.
• Autor : osoba lub osoby, które napisały polecenie.
• Prawa autorskie : Twoja wiadomość o prawach autorskich. Obejmują one również zazwyczaj rodzaj licencji, na której program jest wydawany.

Jeśli przejrzysz niektóre z bardziej skomplikowanych stron podręcznika man zobaczysz, że istnieje również wiele innych sekcji. Na przykład spróbuj man man . Nie musisz jednak uwzględniać ich wszystkich — tylko tych, których naprawdę potrzebujesz. na stronach man nie ma miejsca na przegadywanie.

Niektóre inne sekcje, które zobaczysz dość często, to:

• Zobacz też : Inne polecenia związane z tematem, które niektórzy uznają za przydatne lub istotne.
• Pliki : lista plików zawartych w pakiecie.
• Ostrzeżenia : Inne punkty, o których należy wiedzieć lub na które należy uważać.
• Historia : historia zmian polecenia.

Sekcje podręcznika

Podręcznik Linuksa składa się ze wszystkich stron podręcznika man które są następnie podzielone na następujące ponumerowane sekcje:

1. Programy wykonywalne: Lub polecenia powłoki.
2. Wywołania systemowe: Funkcje dostarczane przez jądro.
3. Wywołania bibliotek: Funkcje w bibliotekach programów.
4. Pliki specjalne.
5. Formaty plików i konwencje: Na przykład „/etc/passwd”.
6. Gry.
7. Różne: pakiety i konwencje makr, takie jak groff .
8. Polecenia administracyjne systemu: zwykle zarezerwowane dla roota.
9. Procedury jądra: zwykle nie są instalowane domyślnie.

Każda strona man musi wskazywać, do której sekcji należy, i musi być również przechowywana w odpowiedniej lokalizacji dla tej sekcji, jak zobaczymy później. Strony man dla poleceń i narzędzi znajdują się w sekcji pierwszej.

Format strony człowieka

Format makra groff nie jest łatwy do wizualnej analizy. Natomiast przecena to pestka.

Poniżej znajduje się strona podręcznika w groff .

Ta sama strona jest pokazana poniżej w przecenach.

Przednia sprawa

Pierwsze trzy linie tworzą coś, co nazywa się przednią materią . Wszystkie muszą zaczynać się znakiem procentu ( % ), bez spacji wiodących, ale jedną po niej, po której następuje:

• Pierwsza linia: zawiera nazwę polecenia, po której następuje sekcja podręcznika w nawiasach, bez spacji. Nazwa staje się lewą i man sekcją nagłówka strony podręcznika. Zgodnie z konwencją nazwa polecenia jest pisana wielkimi literami, chociaż znajdziesz wiele takich, które nie są. Wszystko, co następuje po nazwie polecenia i numerze sekcji podręcznika, staje się lewą sekcją stopki. Wygodnie jest używać tego do numeru wersji oprogramowania.
• Drugi wiersz: Nazwiska autora (autorów). Są one wyświetlane w automatycznie generowanej sekcji man strony podręcznika. Nie musisz dodawać sekcji „Autorzy” — wystarczy podać tutaj co najmniej jedno nazwisko.
• Trzecia linia: Data, która również staje się środkową częścią stopki.

Nazwa

Sekcje są oznaczone liniami zaczynającymi się od znaku liczby ( # ), który jest znacznikiem wskazującym nagłówek w przecenach. Znak liczby ( #) musi być pierwszym znakiem w wierszu, po którym następuje spacja.

Sekcja nazwy zawiera zgrabny jednowiersz, który zawiera nazwę polecenia, spację, łącznik ( - ), spację, a następnie bardzo krótki opis działania polecenia.

Streszczenie

Streszczenie zawiera różne formaty, które może przyjmować wiersz poleceń. To polecenie może zaakceptować wzorzec wyszukiwania lub opcję wiersza polecenia. Dwie gwiazdki ( ** ) po obu stronach nazwy polecenia oznaczają, że nazwa będzie pogrubiona na stronie man . Pojedyncza gwiazdka ( * ) po obu stronach jakiegoś tekstu powoduje, że strona podręcznika wyświetla man jako podkreśloną.

Domyślnie po podziale wiersza następuje pusta linia. Aby wymusić twardą przerwę bez pustej linii, możesz użyć końcowego ukośnika odwrotnego ( \ ).

Opis

Opis wyjaśnia, co robi polecenie lub program. Powinien zwięźle opisywać ważne szczegóły. Pamiętaj, że nie piszesz podręcznika użytkownika.

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 kawałki.

Opcje

Sekcja opcji zawiera opis wszystkich opcji wiersza polecenia, których można użyć z poleceniem. Zgodnie z konwencją są one wyświetlane pogrubioną czcionką, dlatego należy umieścić dwie gwiazdki ( ** ) przed i po nich. Dołącz opis tekstowy opcji w następnym wierszu i zacznij go 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 za długi, jest wyświetlany jako akapit z wcięciem, który zaczyna się w wierszu poniżej opcji wiersza polecenia.

Przykłady

Sekcja przykładów zawiera wybór różnych formatów wiersza poleceń. Zwróć uwagę, że linie opisu rozpoczynamy od dwukropka ( : ), tak jak w przypadku sekcji z opcjami.

Wyjdź z wartości

Ta sekcja zawiera listę wartości zwracanych przez polecenie, które wysyła z powrotem do procesu wywołującego. Może to być powłoka, jeśli wywołałeś ją z wiersza poleceń, lub skrypt, jeśli uruchomiłeś go ze skryptu powłoki. Również w tej sekcji rozpoczynamy linie opisu od dwukropka ( : ).

Robaki

Sekcja błędów zawiera listę znanych błędów, niedociągnięć lub dziwactw, o których ludzie powinni wiedzieć. W przypadku projektów typu open source często umieszcza się tutaj link do narzędzia do śledzenia problemów projektu, aby sprawdzić stan wszelkich błędów lub zgłosić nowe.

prawa autorskie

Sekcja dotycząca praw autorskich zawiera oświadczenie o prawach autorskich i zazwyczaj opis typu licencji, na podstawie której oprogramowanie zostało wydane.

Wydajny przepływ pracy

Możesz edytować swoją stronę man w swoim ulubionym edytorze. Większość obsługujących wyróżnianie składni będzie świadoma przecen i pokolorowania tekstu w celu wyróżnienia nagłówków, a także pogrubienia i podkreślenia. To świetnie, jeśli chodzi o to, że man patrzysz na wyrenderowaną stronę podręcznika, co jest prawdziwym dowodem w budyniu.

Otwórz okno terminala w katalogu, który zawiera twój plik przecen. Po otwarciu w edytorze okresowo zapisuj plik na dysku twardym. Za każdym razem możesz wykonać następujące polecenie w oknie terminala:

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

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

To polecenie wywołuje również pandoc w pliku markdown (tutaj nazywa się „ms.1.md”):

• Opcja -s (samodzielna) generuje pełną stronę podręcznika od góry do dołu man a man tylko tekst w formacie podręcznika.
• Opcja -t (typ wyjścia) z operatorem „man” nakazuje pandoc wygenerowanie wyjścia w formacie man . Nie powiedzieliśmy pandoc , aby wysyłał swoje dane wyjściowe do pliku, więc zostanie on wysłany na stdout .

Przesyłamy również to wyjście do man za pomocą opcji -l (plik lokalny). Mówi man , aby nie przeszukiwał bazy danych man w poszukiwaniu strony man . Zamiast tego powinien otworzyć nazwany plik. Jeśli nazwa pliku to - , man pobierze dane wejściowe ze stdin .

Sprowadza się to do tego, że możesz zapisać z edytora i nacisnąć Q, aby zamknąć man , jeśli jest uruchomiony w oknie terminala. Następnie możesz nacisnąć strzałkę w górę, a następnie Enter, aby zobaczyć wyrenderowaną wersję strony man bezpośrednio w man .

POWIĄZANE: Czym są stdin, stdout i stderr w systemie Linux?

Tworzenie Twojej strony dla mężczyzn

Po zakończeniu tworzenia strony man , musisz utworzyć jej ostateczną wersję, a następnie zainstalować ją w swoim systemie. Następujące polecenie mówi pandoc , aby wygenerował stronę podręcznika man nazwie „ms.1”:

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

Jest to zgodne z konwencją nazywania strony podręcznika man po poleceniu, które opisuje, i dołączania numeru sekcji podręcznika tak, jakby był to rozszerzenie pliku.

Tworzy to plik „ man ”, który jest naszą nową stroną podręcznika. Gdzie to położymy? To polecenie powie nam, gdzie man szuka stron man :

 manpath 

Wyniki dają nam następujące informacje:

• /usr/share/man: man standardowej biblioteki stron podręcznika. Nie dodajemy stron do tej biblioteki.
• /usr/local/share/man: To dowiązanie symboliczne wskazuje na „/usr/local/man”.
• /usr/local/man: Tutaj musimy umieścić naszą nową stronę man .

Zauważ, że różne sekcje podręcznika znajdują się w swoich własnych katalogach: man1, man2, man3 i tak dalej. Jeśli katalog dla sekcji nie istnieje, musimy go utworzyć.

W tym celu wpisujemy:

 sudo mkdir /usr/local/man/man1

Następnie kopiujemy plik „ms.1” do właściwego katalogu:

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

man oczekuje man że strony podręcznika zostaną skompresowane, więc użyjemy do ich kompresji programu gzip :

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

Aby man dodał nowy plik do swojej bazy danych, wpisz:

 sudo mandb 

Otóż ​​to! Możemy teraz nazwać naszą nową stronę podręcznika tak samo jak każdą inną man wpisując:

 mężczyzna pani 

Nasza nowa strona man została znaleziona i wyświetlona.

Wygląda jak każda inna strona podręcznika man z pogrubionym, podkreślonym i wciętym tekstem w odpowiednich miejscach.

Linie opisu, które pasują do opcji, którą opisują, pojawiają się w tym samym wierszu. Linie, które są zbyt długie, aby zmieścić się, pojawiają się pod opcją, którą opisują.

Automatycznie wygenerowaliśmy również sekcję „Autorzy”. Stopka zawiera również numer wersji oprogramowania, datę i nazwę polecenia, zgodnie z definicją z przodu.

Jeśli chcesz . . .

Gdy pandoc utworzy stronę podręcznika użytkownika man możesz również bezpośrednio edytować plik w formacie makra groff przed przeniesieniem man do katalogu strony podręcznika i za pomocą gzip go.