Chcesz, aby Twój nowy program dla systemu Linux wyglądał profesjonalnie? Daj mu stronę podręcznika. Pokażemy Ci najłatwiejszy i najszybszy sposób, aby to zrobić.
Spis treści:
Strony podręcznika
W starym żartach o Uniksie jest jądro prawdy „the tylko polecenie, którego potrzebujesz wiedzieć, to człowiek ”. Strony podręcznika zawierają bogactwo wiedzy i powinny być pierwszym miejscem, w którym chcesz się dowiedzieć o poleceniu.
Udostępnienie strony podręcznika dla narzędzia lub polecenia, które napisałeś, podnosi je z użytecznego fragmentu kodu do w pełni uformowanego pakietu Linuksa. Ludzie oczekują, że zostanie udostępniona strona podręcznika systemowego dla programu napisanego dla systemu Linux. Jeśli natywnie wspierasz Linuksa, strona podręcznika jest obowiązkowa, jeśli chcesz, aby program był traktowany poważnie.
W przeszłości strony podręcznika były pisane przy użyciu zestawu makr formatujących. Kiedy wzywasz mana do otwarcia strony, wywołuje on groff przeczytaj plik i wygeneruj sformatowane dane wyjściowe, zgodnie z makrami w pliku. Wyjście jest przesyłane potokiem do less, a następnie wyświetlane dla Ciebie.
O ile nie tworzysz często stron podręcznika systemowego, napisanie jednej i ręczne wstawienie makr jest ciężką pracą. Czynność polegająca na utworzeniu strony podręcznika, która poprawnie analizuje i wygląda dobrze, może przekroczyć twój cel, dostarczając zwięzły, ale dokładny opis polecenia.
Powinieneś skoncentrować się na swoich treściach, a nie walczyć z mało znanym zestawem makr.
pandoc na ratunek
Plik program pandoc czyta pliki markdown i generuje nowe w około 40 różnych językach znaczników i formatach dokumentów, łącznie ze stroną man. Całkowicie przekształca proces pisania strony podręcznika, więc nie musisz zmagać się z hieroglifami.
Aby rozpocząć, możesz zainstalować pandoc na Ubuntu za pomocą tego polecenia:
sudo apt-get install pandoc
W Fedorze polecenie, którego potrzebujesz, jest następujące:
sudo dnf install pandoc
Na Manjaro wpisz:
sudo pacman -Syu pandoc
Sekcje strony człowieka
Strony podręcznika zawierają sekcje zgodne ze standardową konwencją nazewnictwa. Sekcje, których potrzebuje twoja strona podręcznika, są podyktowane złożonością opisywanego polecenia.
Większość stron podręcznika zawiera przynajmniej następujące sekcje:
Nazwa: nazwa polecenia i zwięzły jednolinijkowy opis opisujący jego funkcję.
Streszczenie: Zwięzły opis wywołań, które ktoś może użyć do uruchomienia programu. Przedstawiają one typy akceptowanych parametrów wiersza polecenia.
Opis: opis polecenia lub funkcji.
Opcje: lista opcji wiersza polecenia i ich działanie.
Przykłady: kilka przykładów typowego użycia.
Wartości wyjściowe: możliwe kody powrotne i ich znaczenie.
Błędy: lista znanych błędów i dziwactw. Czasami jest to uzupełniane (lub zastępowane) linkiem do narzędzia do śledzenia problemów projektu.
Autor: osoba lub osoby, które napisały polecenie.
Prawa autorskie: Twoja wiadomość dotycząca praw autorskich. Obejmują one zwykle również typ licencji, na podstawie której program jest udostępniany.
Jeśli przejrzysz niektóre z bardziej skomplikowanych stron podręcznika, zobaczysz, że jest tam również wiele innych sekcji. Na przykład spróbuj man man. Nie musisz jednak uwzględniać ich wszystkich – tylko te, których naprawdę potrzebujesz. strony man nie są miejscem na gadatliwość.
Niektóre inne sekcje, które będziesz dość często widzieć, to:
Zobacz też: Inne polecenia związane z tematem, które niektórzy uznaliby za przydatne lub istotne.
Pliki: lista plików zawartych w pakiecie.
Ostrzeżenia: inne kwestie, o których należy pamiętać 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, które są następnie podzielone na ponumerowane sekcje:
Programy wykonywalne: lub polecenia powłoki.
Wywołania systemowe: funkcje dostarczane przez jądro.
Wywołania bibliotek: funkcje w bibliotekach programu.
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: zwykle zarezerwowane dla użytkownika root.
Procedury jądra: zwykle nie są instalowane domyślnie.
Każda strona podręcznika musi wskazywać, do której sekcji należy, i musi być również przechowywana w odpowiednim miejscu dla tej sekcji, jak zobaczymy później. Strony podręcznika man dla poleceń i narzędzi należą do sekcji pierwszej.
Format strony man
Format makra groffa nie jest łatwy do wizualnej analizy. W przeciwieństwie do tego przecena to pestka.
Poniżej znajduje się strona podręcznika systemowego groff.
Ta sama strona jest pokazana poniżej w przecenie.
Front Matter
Pierwsze trzy wiersze tworzą coś, co nazywa się materią frontową. Wszystkie muszą zaczynać się od znaku procentu (%), bez spacji wiodących, ale jedną następną, po której następuje:
Pierwsza linia: zawiera nazwę polecenia, po której następuje sekcja instrukcji w nawiasach, bez spacji. Nazwa staje się lewą i prawą sekcją nagłówka strony podręcznika. Zgodnie z konwencją, nazwa polecenia jest zapisana wielkimi literami, chociaż wiele takich nie jest. Wszystko, co następuje po nazwie polecenia i numerze sekcji instrukcji, staje się lewą sekcją stopki. Jest to wygodne w użyciu dla numeru wersji oprogramowania.
Drugi wiersz: nazwisko (a) autora (ów). Są one wyświetlane w automatycznie generowanej sekcji autorów strony podręcznika. Nie musisz dodawać sekcji „Autorzy” – podaj tutaj co najmniej jedno nazwisko.
Trzeci wiersz: data, która również staje się środkową częścią stopki.
Nazwa
Sekcje są oznaczone liniami zaczynającymi się od znaku liczby (#), czyli znacznika wskazującego nagłówek w przecenie. Znak liczby (#) musi być pierwszym znakiem w wierszu, po którym następuje spacja.
Sekcja nazwy zawiera zgrabną, jednoliniową linijkę, która zawiera nazwę polecenia, spację, myślnik (-), spację, a następnie bardzo krótki opis działania polecenia.
Streszczenie
Streszczenie zawiera różne formaty, które może przyjąć wiersz poleceń. To polecenie może akceptować wzorzec wyszukiwania lub opcję wiersza polecenia. Dwie gwiazdki (**) po obu stronach nazwy polecenia oznaczają, że nazwa zostanie pogrubiona na stronie podręcznika. Pojedyncza gwiazdka
po obu stronach jakiegoś tekstu powoduje, że strona podręcznika wyświetla go podkreślony.
Domyślnie po podziale wiersza następuje pusty wiersz. Aby wymusić twardą przerwę bez pustej linii, możesz użyć końcowego ukośnika odwrotnego ().
Sekcja opisowa strony podręcznika w promocji.
Opis wyjaśnia, co robi polecenie lub program. Powinien zwięźle opisywać ważne 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 fragmenty.
Sekcja opcji strony podręcznika w Markdown.
Sekcja opcji zawiera opis wszystkich opcji wiersza polecenia, których można użyć z poleceniem. Zgodnie z konwencją są one pogrubione, więc dołącz dwie gwiazdki (**) przed i po nich. Dołącz opis tekstowy opcji w następnym wierszu i rozpocznij go dwukropkiem (:), 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, jest wyświetlany jako akapit z wcięciem, który zaczyna się w wierszu poniżej opcji wiersza polecenia.
Sekcja przykładów strony podręcznika man w promocji.
Sekcja przykładów zawiera wybór różnych formatów wiersza poleceń. Zauważ, że linie opisu zaczynamy od dwukropka (:), tak jak zrobiliśmy to w sekcji opcji.
Wyjdź z sekcji wartości strony podręcznika w promocji.
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. W tej sekcji również rozpoczynamy linie opisu od dwukropka (:).
Sekcja błędów na stronie podręcznika w promocji.
Sekcja błędów zawiera listę znanych błędów, pułapek lub dziwactw, o których ludzie powinni wiedzieć. W przypadku projektów typu open source często umieszcza się tutaj łącze do narzędzia do śledzenia problemów projektu, aby sprawdzić stan wszelkich błędów lub zgłosić nowe.
Sekcja praw autorskich strony podręcznika w Markdown.
Sekcja dotycząca praw autorskich zawiera oświadczenie o prawach autorskich i zwykle opis typu licencji, na podstawie której oprogramowanie jest wydawane.
Wydajny przepływ pracy
Możesz edytować swoją stronę podręcznika w swoim ulubionym edytorze. Większość osób obsługujących podświetlanie składni będzie świadoma stosowania oznaczeń i kolorów w celu wyróżnienia nagłówków, a także pogrubienia i podkreślenia. To świetnie, jeśli chodzi o to, ale nie patrzysz na wyrenderowaną stronę podręcznika, która jest prawdziwym dowodem w puddingu.
pandoc ms.1.md -s -t man | /usr/bin/man -l -
pandoc ms.1.md -s -t man | / usr / bin / man -l – w oknie terminala.
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 kompletną stronę podręcznika od góry do dołu, zamiast tylko tekstu w formacie man.
Opcja -t (typ wyjścia) z operatorem „man” mówi pandocowi, aby wygenerował swoje wyjście w formacie man. Nie powiedzieliśmy pandocowi, aby wysyłał swoje dane wyjściowe do pliku, więc zostanie wysłane na standardowe wyjście.
Przekierowujemy również te dane wyjściowe do man za pomocą opcji -l (plik lokalny). Mówi manowi, aby nie przeszukiwał bazy danych man, szukając strony podręcznika. Zamiast tego powinien otworzyć wymieniony plik. Jeśli nazwa pliku to -, man pobierze dane wejściowe ze standardowego wejścia.
Sprowadza się to do tego, że możesz zapisać z edytora i nacisnąć Q, aby zamknąć man, jeśli działa w oknie terminala. Następnie możesz nacisnąć strzałkę w górę, a następnie Enter, aby zobaczyć wyrenderowaną wersję swojej strony podręcznika, bezpośrednio w man.
Tworzenie strony dla mężczyzn
pandoc ms.1.md -s -t man -o ms.1
pandoc ms.1.md -s -t man -o ms.1 w oknie terminala.
Jest to zgodne z konwencją nazywania strony podręcznika po poleceniu, które opisuje i dołączania numeru sekcji podręcznika tak, jakby było to rozszerzenie pliku.
manpath
manpath w oknie terminala.
Wyniki dają nam następujące informacje:
/ usr / share / man: Lokalizacja 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ę podręcznika.
Zwróć uwagę, ż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ć.
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 podręcznika zostaną skompresowane, więc użyjemy gzipskompresować
sudo gzip /usr/local/man/man1/ms.1
:
sudo mandb
sudo mkdir / usr / local / man / man1 w oknie terminala.
man ms
man ms w oknie terminala.
górna sekcja nowej strony podręcznika.
środkowa sekcja nowej strony podręcznika.
Dolna sekcja nowej strony podręcznika.
Automatycznie wygenerowaliśmy również sekcję „Autorzy”. Stopka zawiera również numer wersji oprogramowania, datę i nazwę polecenia, zgodnie z definicją na pierwszej stronie.
Jeśli chcesz . . .
Gdy pandoc utworzy twoją stronę podręcznika, możesz również bezpośrednio edytować plik w formacie makra groffa przed przeniesieniem go do katalogu strony podręcznika i zgzipować go.