Cum se creează o pagină de manual pe Linux

Vrei ca noul tău program Linux să arate profesional? Dă-i o pagină de man . Vă vom arăta cel mai simplu și mai rapid mod de a o face.

Omul Pagini

Există un sâmbure de adevăr în vechea glumă Unix, „singura comandă pe care trebuie să o știi este man ”. Paginile de man conțin o mulțime de cunoștințe și ar trebui să fie primul loc în care vă întoarceți atunci când doriți să aflați despre o comandă.

Furnizarea unei pagini de man pentru un utilitar sau o comandă pe care ați scris-o o ridică de la o bucată utilă de cod la un pachet Linux complet format. Oamenii se așteaptă să fie furnizată o pagină de man pentru un program care a fost scris pentru Linux. Dacă suportați Linux în mod nativ, o pagină de man este obligatorie dacă doriți ca programul dvs. să fie luat în serios.

Din punct de vedere istoric, paginile de man au fost scrise folosind un set de macrocomenzi de formatare. Când apelați la man să deschidă o pagină, acesta îl cheamă pe groff pentru a citi fișierul și a genera rezultate formatate, conform macrocomenzilor din fișier. Ieșirea este transmisă în less și apoi afișată pentru dvs.

Dacă nu creați frecvent pagini de man , scrierea uneia și inserarea manuală a macrocomenzilor este o muncă grea. Faptul de a crea o pagină de man care se analizează corect și care arată corect vă poate depăși scopul de a oferi o descriere concisă, dar detaliată a comenzii dvs.

Ar trebui să vă concentrați asupra conținutului dvs., nu să vă luptați cu un set obscur de macrocomenzi.

LEGATE: Cum să utilizați comanda man Linux: Secrete și elemente de bază ascunse

pandoc la Salvare

Programul pandoc citește fișierele markdown și generează altele noi în aproximativ 40 de limbaje de marcare și formate de documente diferite, inclusiv cel al paginii de man . Transformă total procesul de scriere a paginii de man , astfel încât să nu trebuie să te lupți cu hieroglifele.

Pentru a începe, puteți instala pandoc pe Ubuntu cu această comandă:

 sudo apt-get install pandoc 

Pe Fedora, comanda de care aveți nevoie este următoarea:

 sudo dnf install pandoc 

Pe Manjaro, tastați:

 sudo pacman -Syu pandoc 

LEGATE: Cum să utilizați pandoc pentru a converti fișiere pe linia de comandă Linux

Secțiuni ale unei pagini de manual

paginile de man conțin secțiuni care urmează o convenție standard de denumire. Secțiunile de man are nevoie pagina ta de manual sunt dictate de sofisticarea comenzii pe care o descrii.

Cel puțin, majoritatea paginilor de manual conțin următoarele secțiuni:

• Nume : Numele comenzii și o linie concisă care descrie funcția acesteia.
• Sinopsis : O descriere concisă a invocărilor pe care cineva le poate folosi pentru a lansa programul. Acestea arată tipurile de parametri acceptați pentru linia de comandă.
• Descriere : O descriere a comenzii sau funcției.
• Opțiuni : o listă de opțiuni de linie de comandă și ceea ce fac acestea.
• Exemple : câteva exemple de utilizare obișnuită.
• Valori de ieșire : posibilele coduri de returnare și semnificațiile acestora.
• Erori : o listă de erori și ciudatenii cunoscute. Uneori, acesta este completat cu (sau înlocuit cu) un link către instrumentul de urmărire a problemelor pentru proiect.
• Autor : Persoana sau persoanele care au scris comanda.
• Drepturi de autor : mesajul dvs. privind drepturile de autor. Acestea includ de obicei și tipul de licență sub care este lansat programul.

Dacă te uiți prin unele dintre paginile de man mai complicate, vei vedea că există și multe alte secțiuni. De exemplu, încercați man man . Totuși, nu trebuie să le includeți pe toate - doar pe acelea de care aveți cu adevărat nevoie. paginile de man nu sunt loc pentru cuvinte.

Alte secțiuni pe care le veți vedea destul de frecvent sunt:

• Vezi și : Alte comenzi legate de subiectul pe care unii le-ar găsi utile sau relevante.
• Fișiere : o listă de fișiere incluse în pachet.
• Avertismente : Alte puncte de știut sau la care trebuie să fiți atenți.
• Istoric : un istoric al modificărilor pentru comandă.

Secțiuni ale manualului

Manualul Linux este alcătuit din toate paginile de man , care sunt apoi împărțite în aceste secțiuni numerotate:

1. Programe executabile: Sau, comenzi shell.
2. Apeluri de sistem: Funcții furnizate de kernel.
3. Apeluri de bibliotecă: Funcții din bibliotecile de programe.
4. Fișiere speciale.
5. Formate de fișiere și convenții: De exemplu, „/etc/passwd”.
6. Jocuri.
7. Diverse: pachete macro și convenții, cum ar fi groff .
8. Comenzi de administrare a sistemului: De obicei rezervate pentru root.
9. Rutine kernel: de obicei nu sunt instalate implicit.

Fiecare pagină de man trebuie să indice căreia secțiune îi aparține și, de asemenea, trebuie să fie stocată în locația potrivită pentru acea secțiune, așa cum vom vedea mai târziu. Paginile de man pentru comenzi și utilitare aparțin secțiunii unu.

Formatul unei pagini de manual

Formatul macro groff nu este ușor de analizat vizual. Spre deosebire de aceasta, reducere este o briză.

Mai jos este o pagină de manual în groff .

Aceeași pagină este afișată mai jos în markdown.

Materia frontală

Primele trei linii formează ceva numit materie frontală . Acestea trebuie să înceapă cu un semn procentual ( % ), fără spații de început, dar unul după, urmat de:

• Prima linie: Conține numele comenzii, urmat de secțiunea manuală între paranteze, fără spații. Numele devine secțiunile din stânga și din dreapta ale antetului paginii de man . Prin convenție, numele comenzii este în majuscule, deși veți găsi multe care nu sunt. Orice lucru care urmează numele comenzii și numărul secțiunii manuale devine secțiunea din stânga a subsolului. Este convenabil să utilizați acest lucru pentru numărul versiunii software.
• A doua linie: Numele (numele) autorului (autorilor). Acestea sunt afișate într-o secțiune de autori generată automat a paginii de man . Nu trebuie să adăugați o secțiune „Autori” – doar includeți cel puțin un nume aici.
• A treia linie: data, care devine și partea centrală a subsolului.

Nume

Secțiunile sunt indicate prin linii care încep cu un semn numeric ( # ), care este marcajul care indică un antet în markdown. Semnul numeric ( #) trebuie să fie primul caracter de pe linie, urmat de un spațiu.

Secțiunea de nume conține o linie rapidă care include numele comenzii, un spațiu, o cratimă ( - ), un spațiu și apoi o descriere foarte scurtă a ceea ce face comanda.

Rezumat

Sinopsisul conține diferitele formate pe care le poate lua linia de comandă. Această comandă poate accepta un model de căutare sau o opțiune de linie de comandă. Cele două asteriscuri ( ** ) de pe ambele părți ale numelui comenzii înseamnă că numele va fi afișat cu caractere aldine pe pagina de man . Un singur asterisc ( * ) de ambele părți ale unui text face ca pagina de man să o afișeze subliniată.

În mod implicit, o întrerupere de linie este urmată de o linie goală. Pentru a forța o pauză grea fără o linie goală, puteți utiliza o bară oblică inversă ( \ ).

Descriere

Descrierea explică ce face comanda sau programul. Ar trebui să acopere detaliile importante în mod succint. Amintiți-vă, nu scrieți un ghid al utilizatorului.

Utilizarea a două semne numerice ( ## ) la începutul unei linii creează un titlu de nivelul doi. Puteți folosi acestea pentru a vă împărți descrierea în bucăți mai mici.

Opțiuni

Secțiunea de opțiuni conține o descriere a oricăror opțiuni de linie de comandă care pot fi utilizate cu comanda. Prin convenție, acestea sunt afișate cu caractere aldine, așa că includeți două asteriscuri ( ** ) înainte și după ele. Includeți descrierea textului opțiunilor pe rândul următor și începeți-o cu două puncte ( : ), urmate de un spațiu.

Dacă descrierea este suficient de scurtă, man o va afișa pe aceeași linie cu opțiunea din linia de comandă. Dacă este prea lung, este afișat ca un paragraf indentat care începe pe linia de sub opțiunea din linia de comandă.

Exemple

Secțiunea de exemple conține o selecție de formate diferite de linie de comandă. Rețineți că începem liniile de descriere cu două puncte ( : ), la fel cum am făcut secțiunea de opțiuni.

Valori de ieșire

Această secțiune listează valorile returnate pe care comanda ta le trimite înapoi procesului de apelare. Acesta ar putea fi shell-ul dacă l-ați apelat din linia de comandă sau un script dacă l-ați lansat dintr-un script shell. Începem liniile de descriere cu două puncte ( : ) și în această secțiune.

Gandaci

Secțiunea erori listează erori cunoscute, probleme sau ciudatenii despre care oamenii trebuie să știe. Pentru proiectele cu sursă deschisă, este obișnuit să includeți aici un link către instrumentul de urmărire a problemelor proiectului pentru a verifica starea oricăror erori sau pentru a raporta unele noi.

Drepturi de autor

Secțiunea privind drepturile de autor conține declarația dvs. privind drepturile de autor și, de obicei, o descriere a tipului de licență sub care este lansat software-ul.

Un flux de lucru eficient

Îți poți edita pagina de man în editorul tău preferat. Majoritatea celor care acceptă evidențierea sintaxelor vor fi conștienți de markdown și vor colora textul pentru a evidenția titlurile, precum și aldin și subliniat. Este grozav în ceea ce privește, dar nu te uiți la o pagină de man redată, care este adevărata dovadă în budincă.

Deschideți o fereastră de terminal în directorul care conține fișierul dvs. de reducere. Cu acesta deschis în editorul dvs., salvați periodic fișierul pe hard disk. De fiecare dată când o faceți, puteți executa următoarea comandă în fereastra terminalului:

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

După ce ați folosit această comandă, puteți apăsa săgeata sus pentru a o repeta, apoi apăsați Enter.

Această comandă invocă și pandoc în fișierul markdown (aici, se numește „ms.1.md”):

• Opțiunea -s (autonomă) generează o pagină de man completă de sus în jos, mai degrabă decât un text în format man .
• Opțiunea -t (tipul de ieșire) cu operatorul „man” îi spune pandoc să-și genereze ieșirea în format man . Nu i-am spus pandoc să-și trimită rezultatul într-un fișier, așa că va fi trimis la stdout .

De asemenea, trimitem acea ieșire în man cu opțiunea -l (fișier local). Îi spune man să nu caute prin baza de date de man căutând pagina de man . În schimb, ar trebui să deschidă fișierul numit. Dacă numele fișierului este - , man va prelua intrarea de la stdin .

La ce se rezumă, puteți salva din editor și apăsați Q pentru a închide man dacă rulează în fereastra terminalului. Apoi, puteți apăsa săgeata în sus, urmată de Enter pentru a vedea o versiune redată a paginii dvs. de man , chiar în interiorul man .

RELATE: Ce sunt stdin, stdout și stderr pe Linux?

Crearea paginii dvs. de manual

După ce ați completat pagina de man , trebuie să creați o versiune finală a acesteia, apoi să o instalați pe sistemul dvs. Următoarea comandă îi spune pandoc să genereze o pagină de man numită „ms.1”:

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

Aceasta urmează convenția de a numi pagina de man după comanda pe care o descrie și de a adăuga numărul secțiunii manuale ca și cum ar fi o extensie de fișier.

Aceasta creează un fișier „ms.1”, care este noua noastră pagină de man . Unde o punem? Această comandă ne va spune unde caută man paginile de man :

 calea omului 

Rezultatele ne oferă următoarele informații:

• /usr/share/man: man bibliotecii standard de pagini de manual. Nu adăugăm pagini în această bibliotecă.
• /usr/local/share/man: această legătură simbolică indică „/usr/local/man”.
• /usr/local/man: Aici trebuie să plasăm noua noastră pagină de man .

Rețineți că diferitele secțiuni ale manualelor sunt conținute în propriile directoare: man1, man2, man3 și așa mai departe. Dacă directorul pentru secțiune nu există, trebuie să-l creăm.

Pentru a face acest lucru, introducem următoarele:

 sudo mkdir /usr/local/man/man1

Copiem apoi fișierul „ms.1” în directorul corect:

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

man se așteaptă ca paginile de man să fie comprimate, așa că vom folosi gzip pentru a le comprima:

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

Pentru a face man să adauge noul fișier în baza de date, tastați următoarele:

 sudo mandb 

Asta e! Acum putem numi noua noastră pagină de man la fel ca oricare alta, tastând:

 omul ms 

Noua noastră pagină de man este găsită și afișată.

Arată la fel ca orice altă pagină de man , cu text aldine, subliniat și indentat în locurile corespunzătoare.

Pe aceeași linie apar rânduri de descriere care se potrivesc lângă opțiunea pe care o descriu. Liniile care sunt prea lungi pentru a se potrivi apar sub opțiunea pe care o descriu.

De asemenea, am generat automat o secțiune „Autori”. Subsolul include, de asemenea, numărul versiunii software, data și numele comenzii, așa cum sunt definite în prima pagină.

Dacă dorești . . .

Odată ce pandoc și-a creat pagina de man , puteți, de asemenea, să editați direct fișierul în formatul macro groff înainte de a-l muta în directorul paginii de man și să îl gzip .