Cum se creează o pagină de manual pe Linux

Vrei ca noul tău program Linux să arate profesional? Dă-i o pagină de manual. 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, „the singura comanda de care ai nevoie a cunoaște este om.” Paginile de manual 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 manual 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 manual pentru un program care a fost scris pentru Linux. Dacă suportați Linux în mod nativ, o pagină de manual este obligatorie dacă doriți ca programul dvs. să fie luat în serios.

Din punct de vedere istoric, paginile de manual au fost scrise folosind un set de macrocomenzi de formatare. Când îl chemați pe om să deschidă o pagină, îl cheamă pe Groff citește fișierul și generează rezultate formatate, conform macrocomenzilor din fișier. Ieșirea este canalizată în mai puțin și apoi afișat pentru tine.

Dacă nu creați frecvent pagini de manual, scrierea uneia și inserarea manuală a macrocomenzilor este o muncă grea. Faptul de a crea o pagină de manual 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.

pandoc la Salvare

The programul pandoc citește fișierele markdown și generează altele noi în aproximativ 40 de limbaje de marcare și formate de document diferite, inclusiv cel al paginii de manual. Transformă total procesul de scriere a paginii de manual, 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

Secțiuni ale unei pagini de manual

paginile de manual conțin secțiuni care urmează o convenție standard de denumire. Secțiunile de care 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 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.
Copyright: 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 manual mai complicate, vei vedea că există și multe alte secțiuni. De exemplu, încearcă om om. Totuși, nu trebuie să le includeți pe toate – doar pe acelea de care aveți cu adevărat nevoie. paginile de manual 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ă aveți grijă.
Istoric: un istoric al modificărilor pentru comandă.

Secțiuni ale manualului

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

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

Fiecare pagină de manual 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 manual 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 manual. 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 manual. 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 manual. Un singur asterisc

de fiecare parte a unui text face ca pagina de manual 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 rândurile 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

Puteți edita pagina de manual în editorul 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 manual redată, care este adevărata dovadă în budincă.

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

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:

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 manual 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 omului să nu caute prin baza de date de oameni căutând pagina de manual. În schimb, ar trebui să deschidă fișierul numit. Dacă numele fișierului este -, man își 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 manual, chiar în interiorul man.

Crearea paginii dvs. de manual

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

După ce ați completat pagina de manual, 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 manual numită „ms.1”:

Aceasta urmează convenția de a numi pagina de manual 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.

manpath

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

Rezultatele ne oferă următoarele informații:
/usr/share/man: Locația 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 manual.

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.

sudo mkdir /usr/local/man/man1

Pentru a face acest lucru, introducem următoarele:

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

Copiem apoi fișierul „ms.1” în directorul corect: man se așteaptă ca paginile de manual să fie comprimate, așa că vom folosi gzippentru a o comprima

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

:

sudo mandb

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

man ms

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

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

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

Rândurile de descriere care se potrivesc lângă opțiunea pe care o descriu apar pe aceeași linie. 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 . . .