To bardzo powszechny fakt, że nikt nie lubi pisać dokumentacji. Cholera, nikt też nie lubi go czytać. Ale są chwile, kiedy musimy go przeczytać, aby, powiedzmy, zakończyć projekt na czas, a zwłaszcza podczas pracy w tworzeniu oprogramowania, a nawet napisać go. Jeśli musisz tylko to przeczytać, zawsze zachęcamy cię do tego, ale jeśli będziesz musiał napisać strony ręczne i potrzebujesz rozpoczęcia, oto artykuł dla Ciebie. Jeśli pracowałeś wcześniej z HTML, twoje życie będzie łatwiejsze, ale jeśli nie, wszystko jest w porządku. Pisanie stron ręcznych dla Linuksa nie jest tak trudne, pomimo wyglądu stron, które są czytane w zwykłym teście. Zasadniczo potrzebujesz wiedzy Linux i możliwości korzystania z edytora tekstu. Nauczysz się (oczywiście z przykładami) głównymi pojęciami w formatowaniu tekstu w stosunku do stron Man i jak napisać prostą stronę ręczną. Ponieważ wykorzystaliśmy wczoraj jako przykład naszego samouczka rozwoju C, użyjemy fragmentów z jego strony ręcznej, aby zilustrować nasz punkt podczas tego artykułu.

Trochę historii

Pierwsze napisane pakiety manualne są napisane przez Dennis Ritchie i Ken Thompson w 1971 roku. Zastosowane oprogramowanie do formatowania było Troff i format ten jest nadal używany do dziś, chociaż narzędzia mogą być inne. Narzędzie do formatowania tekstu w systemach Linux jest teraz Groff, a wiodący „G” pochodzi z GNU. Istnienie Groffa jest należne faktowi, że kiedy Troff został napisany, terminale oznaczały coś innego pod względem możliwości niż to, co mają na myśli dzisiaj. Kolejną silną zachętą do projektu GNU do stworzenia Groffa była własna licencja Troff. Troff nadal żyje w innych systemach UNIX, takich jak OpenSolaris lub Plan9, chociaż na licencjach open source.

Zanim zaczniemy, musimy ci coś powiedzieć o *Roff: to oprogramowanie do składania, na przykład Tex, i jest to język samodzielny. Nie przekształcimy tego artykułu w podręcznik Groff, ani nie będziemy dokonywać listy różnic między Groff i Troff. To tylko starter do prostego ręcznego pisania stron, a jeśli potrzebujesz więcej, znajdziesz w Internecie wiele dokumentacji.

Alternatywy

Jeśli po przeczytaniu poczujesz, że składnia jest zniechęcająca, mamy rozwiązanie dla twojego problemu: Pod2man. POD oznacza to zwykłą starą dokumentację i oferuje prostszą składnię, a istnieje Pod2Man, który jest modułem Perl (część Perlpod), który tłumaczy dokumentację napisaną w formacie POD na format ManPage. Perlpod oferuje również narzędzia do konwersji POD na tekst lub HTML, więc po prostu zapoznaj się z dokumentacją dystrybucji, jak ją zainstalować.

Strony ręczne

Kategorie

Strony ręczne są podzielone na kategorie, w zależności od tego, jaki temat leczą. Nie różnią się w rozkładach Linuksa, ale inne systemy UNIX mają różne sposoby dzielenia stron ręcznych. Za pomocą

 $ Man Man

da ci te kategorie i wiele więcej w odniesieniu do tego, jak korzystać z polecenia człowieka. Kategorie w Linux są następujące:

 1 programy wykonywalne lub polecenia powłoki
2 wywołania systemowe (funkcje dostarczone przez jądro)
3 wywołania bibliotek (funkcje w bibliotekach programowych)
4 pliki specjalne (zwykle występujące w /dev)
5 formatów i konwencji plików np. /Etc /passwd
6 gier
7 Różne (w tym pakiety makro i konwencje), E.G. Man (7), Groff (7)
8 poleceń administracji systemu (zwykle tylko dla korzenia)
9 Procedury jądra [non standard]

Zaleca się, aby przeczytać stronę Man Manual, ponieważ nie jest to samouczek o tym, jak to zrobić używać oni, ale jak pisać ich.

Układ strony ręcznej

Od kilku lat temu istnieje standard pisania stron ręcznych, co powinny zawierać i problemy z stylami. Powinny być zwięzłe, szanować układ i kompresować jak najwięcej informacji w jak największej przestrzeni. Kiedy ktoś zobaczy 100-stronicową instrukcję, pierwszym odruchem będzie ucieczka.

Daleko daleko stąd. Z drugiej strony krótka, ale pouczająca strona ręczna, która da czytelnikowi to, co on/ona chce wiedzieć. Jeśli program, dla którego piszesz strony ręczne, nie jest napisane przez ciebie (całkowicie), pracuj z programistami, dopóki nie rozstrzygasz, jak powinna wyglądać instrukcja. Teraz chcemy uniknąć nudnego lub przerażającego, zacznijmy od układu.

Przede wszystkim nazwa pliku powinna być $ CommandName.$ kategoria, na przykład vim.1. Ten plik, po zainstalowaniu, powinien zostać gzowany i skopiowany do odpowiedniego katalogu, który dla VIM powinien być/usr/share/man/man1. Plik niezak dla bezkompresji to zwykły plik tekstowy, nic więcej. Czytanie dowolnej strony ręcznej da ci pomysł, jak powinna wyglądać: Nazwa, streszczenie, opis, opcje, przykłady, pomoc, zobacz także, autor i błędy. Nie wszystkie są obowiązkowe, ale zaleca się, aby zapewnić im wszystko wystarczy, aby uzyskać lepsze wrażenia użytkownika.

Język znaczników

Jak wspomniano wcześniej, jeśli jesteś przyzwyczajony do pisania XML lub HTML, znajdziesz prostą składnię. W rzeczywistości i tak jest to proste, gdy się do tego przyzwyczaisz. Zaczynamy od nagłówek, a pierwszym nagłówkiem jest tytuł nagłówka. Inne zwykle spotykane makr (odpowiednik znaczników w językach znaczników) nagłówki przedmiotowe I akapity, Ale więcej o nich później.

Nagłówek tytułu musi zawierać następujące czynności: Nazwa, rozdział (kategoria) i datę ostatniej modyfikacji strony. Więc aby zmoczyć stopy, oto jak to powinno wyglądać:

.Th w przeszłości 1 „19 kwietnia 2010”

Oznacza nagłówek tytułu, a ponieważ jest to makro. Wczoraj jest nazwa aplikacji, kategoria 1, ostatnia edytowana 19 kwietnia 2010 r. Zanim przejdziemy dalej, możesz wstawić kilka komentarzy do swojego pliku przed nachyleniem tytułu. One zaczynają się od .\ ”(Cytat odwrotny kropki) i może wyglądać tak:

.\ ”Copyright 2004, 2006, 2010 Kimball Hawkins .

.\" Wszelkie prawa zastrzeżone.

Teraz wstaw te linie (nagłówek i komentarz nad nim) i sprawdź wynik

 $ Groff -man -tascii.1

-TASCII instruuje Groffa, aby wyprowadzono w formacie ASCII (tekst), ale Groff obsługuje inne typy wyjściowe. Zapraszamy do sprawdzenia strony ręcznej Groff.

Następnie, teraz, kiedy wiemy, jak radzić sobie z tytułowymi nagłówkami, przejdźmy do Sekcja nagłówki. Jak można się domyślać, makro jest .SH i to, co robi, wprowadza nazwę, streszczenie, opis itp. sekcje napisane powyżej. Zatem składnia:

.CII Nazwa wczoraj - narzędzie manipulacji datą.

.CII STRESZCZENIE .B w przeszłości \ fr -help

.P .B w przeszłości \ fr -license

.P .B MIROST \ FR -IVERSION

.P .B MIST \ fr [\ fb-idf = \ fistr \ fr] [\ fb-tz = \ fitzone \ fr] [[\ fb- \ fr | \ fb+\ fr] \ fiadjust \ fr [\ fbd \ fr | \ fbh fbh \ fr | \ fbm \ fr]] [\ Fiate \ fr] [\ fiformat-string \ fr] .

CII Opis To nazywa się „wczoraj”, ponieważ domyślnie jest wczorajsza data wyjścia. To narzędzie wie o roku kroku, oszczędnościach dziennych i takich odmianach. To narzędzie dodaje lub odejmuje dni, godziny i/lub minuty od danej daty i wynika wyniki w określonym formacie. Domyślnie, jeśli nie jest określona nie ma korekty, to „-1d”

Jest to oczywiście tylko część instrukcji, ale zobaczmy, co oznaczają nowe makra… B oznacza odważne i zalecamy wklej ten kod w pliku i przetestuj go, z poleceniem Groff powyżej… P Stands Standss w akapicie, ponieważ, jak widać, po każdym .P Na stronie sformatowanej jest podwójna nowa linia. \ F* są sekwencjami ucieczki czcionki, a to oznacza, że ​​po słowie „streszczenie” .B mówi Groffowi, żeby wydrukował odważny. Jednak po słowie „wczoraj”, które rzeczywiście jest wydrukowane odważne, potrzebujemy „-help”, aby wydrukować zwykłymi czcionkami, więc to właśnie oznacza \ fr. I odwrotnie, \ fb oznacza „wydruku .B . Za pomocą logiki możesz zrozumieć, na przykład oznacza \ fl.

Prosty tekst, czyli tekst, który nie jest nagłówkiem ani sekcją, jest zawarty w akapitach. Prosty akapit jest wyznaczony przez .Makro PP, które tworzy małą pionową przestrzeń między faktycznym akapitem a następną. Jeśli chcesz oznaczyć akapit, możesz go mieć .TP . Następnie porozmawiamy o wcięcie.

Względne wcięcie oznacza, że ​​tekst jest wcięty w stosunku do poprzedniego i następującego tekstu. Aby rozpocząć stosunkowo indentowany kawałek tekstu, użyj .RS (względny start) i kończyć go użycie .RE (względny koniec). Oto przykład:

.Rs.7i Jeśli w ciągu są przestrzenie lub znaki specjalne, należy je cytować. Program rozpozna większość konwencji ewakuacyjnych podobnych do fbecho \ fR, takie jak „\\ n” (newline) i „\\ t” (tab) w \ fiform-string \ fr i escapes (\\ 0nn) są obsługiwane.

.P Jeśli określono tylko jedno dzień, domyślnie \ fiformat-string \ fR to „%x”. Jeśli \ fiadjustment \ fr zawiera element czasu, domyślny \ fiformat-string \ fr staje się „%x-%r”.

.ODNOŚNIE

Jak widać, możesz mieć .P makro wewnątrz stosunkowo wciętego kawałka tekstu… P to tylko alias dla .PP, aby można ich używać zamiennie. Być może zauważyłeś „.7i ”po .RS: To mówi Groffowi do wcięcia z siedmioma przestrzeniami tekstu w środku.

Używanie tabel jest równie proste, jak stosowanie względnego wcięcia: .TS i .Te. Możesz, jak powiedziano wcześniej, zmodyfikować jedno słowo lub cały akapit (z typograficznego punktu widzenia) z makrami. Trzy sposoby zmiany postaci to, jak wszyscy wiedzą, odważne, kursywne i rzymskie. Na przykład, .BI zmienia tekst po nim, ponieważ pojawi się oba pogrubiony I italski.

Wniosek

Pamiętaj, że może to wystarczyć, aby zacząć, ale nie jest to kompletne. To nie są wszystkie makra, a jeśli przełączysz się na system BSD, może się okazać, że używają Mandoc zamiast Groffa, więc będziesz musiał nauczyć się samodzielnie, jeśli chcesz stać się biegły. Następnie przeczytaj kilka ręcznych stron, aby zobaczyć główne konwencje, które należy szanować, takie jak umieszczenie opcjonalnych argumentów do aplikacji (jeśli tak jest) w nawiasach kwadratowych lub użycie , aby pokazać, że przynajmniej jeden z argumentów wewnątrz Ustalanie należy użyć. Podsumowując, dokumentowanie oprogramowania, nawet jeśli nie jesteś zmuszony przez swojego pracodawcę, jest dobre dla Ciebie i użytkowników oprogramowania. Będziesz uważany za starannego programistę, a użytkownicy mogą łatwiej wykorzystać twoje stworzenie, wiedząc, co mogą i czego nie mogą zrobić.

Powiązane samouczki Linux:

• Rzeczy do zainstalowania na Ubuntu 20.04
• Rzeczy do zrobienia po zainstalowaniu Ubuntu 20.04 Focal Fossa Linux
• Jak wykonywać instalacje bez opieki Linux z Kickstart
• Jak sprawdzić żywotność baterii na Ubuntu
• Rzeczy do zrobienia po zainstalowaniu Ubuntu 22.04 JAMMY Jellyfish…
• Wprowadzenie do automatyzacji, narzędzi i technik Linuksa
• Hung Linux System? Jak uciec do wiersza poleceń i…
• Rzeczy do zainstalowania na Ubuntu 22.04
• Mint 20: Lepsze niż Ubuntu i Microsoft Windows?
• Zainstaluj Arch Linux na stacji roboczej VMware