Dorești ca programul tău nou pentru Linux să aibă un aspect profesional? Oferă-i o pagină de manual. Îți vom arăta cum să faci asta rapid și ușor.
Paginile Man
Există un sâmbure de adevăr în vechea glumă Unix: „Singura comandă de care ai nevoie este ‘man’”. Paginile de manual conțin informații valoroase și ar trebui să fie prima resursă la care apelezi când vrei să înțelegi o comandă.
Adăugarea unei pagini de manual pentru un instrument sau o comandă pe care ai scris-o transformă un cod util într-un pachet Linux complet. Utilizatorii se așteaptă ca un program Linux să aibă o pagină de manual. Dacă oferi suport nativ pentru Linux, o pagină de manual este esențială pentru ca programul tău să fie luat în serios.
Tradițional, paginile de manual erau scrise cu un set de macrocomenzi de formatare. Când apelezi comanda `man` pentru a deschide o pagină, `Groff` citește fișierul și generează rezultate formatate, conform macrocomenzilor. Rezultatul este transmis către `less` și apoi afișat.
Dacă nu creezi frecvent pagini de manual, scrierea uneia și introducerea manuală a macrocomenzilor este dificilă. Realizarea unei pagini de manual care să fie corect analizată și care să arate bine poate fi dificil și te poate distrage de la obiectivul principal: descrierea concisă a comenzii tale.
Ar trebui să te concentrezi pe conținut, nu să te lupți cu un set de macrocomenzi complexe.
Pandoc, Soluția
Programul pandoc citește fișiere markdown și generează altele în aproximativ 40 de formate, inclusiv formatul paginii de manual. Acesta simplifică procesul de scriere a paginii de manual, eliminând nevoia de a te lupta cu macrocomenzile.
Pentru a începe, poți instala pandoc pe Ubuntu cu această comandă:
sudo apt-get install pandoc
Pe Fedora, comanda este:
sudo dnf install pandoc
Pe Manjaro, tastează:
sudo pacman -Syu pandoc
Secțiunile unei Pagini de Manual
Paginile de manual sunt organizate în secțiuni cu denumiri standard. Secțiunile necesare paginii tale de manual depind de complexitatea comenzii pe care o descrii.
Majoritatea paginilor de manual includ cel puțin următoarele secțiuni:
Nume: Numele comenzii și o descriere succintă a funcției sale.
Sinopsis: O descriere scurtă a modului în care poate fi invocat programul. Acesta prezintă tipurile de parametri acceptați pe linia de comandă.
Descriere: O explicație a comenzii sau funcției.
Opțiuni: O listă a opțiunilor de linie de comandă și ce fac ele.
Exemple: Câteva exemple de utilizare obișnuită.
Valori de ieșire: Posibilele coduri de returnare și semnificațiile lor.
Erori: O listă de erori cunoscute. Uneori, aceasta este înlocuită cu un link către instrumentul de urmărire a problemelor proiectului.
Autor: Persoana sau persoanele care au scris comanda.
Copyright: Declarația ta de copyright. Aceasta include și tipul de licență sub care este lansat programul.
Dacă examinezi pagini de manual mai complexe, vei observa multe alte secțiuni. De exemplu, încearcă `man man`. Nu trebuie să le incluzi pe toate – doar pe cele necesare. Paginile de manual nu sunt locuri pentru cuvinte inutile.
Alte secțiuni întâlnite frecvent includ:
Vezi și: Alte comenzi similare sau relevante.
Fișiere: O listă a fișierelor incluse în pachet.
Avertismente: Alte informații importante sau aspecte de care trebuie să fii atent.
Istoric: Un istoric al modificărilor comenzii.
Secțiunile Manualului
Manualul Linux este format din toate paginile de manual, grupate în secțiuni numerotate:
Programe executabile: Comenzi shell.
Apeluri de sistem: Funcții oferite 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, pentru root.
Rutine kernel: De obicei, nu sunt instalate implicit.
Fiecare pagină de manual trebuie să indice secțiunea căreia îi aparține și trebuie stocată în locația corespunzătoare. 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 citit. Spre deosebire de acesta, markdown este foarte simplu.
Mai jos este o pagină de manual în Groff.
Aceeași pagină este afișată mai jos în markdown.
Antetul
Primele trei linii formează antetul. Acesta trebuie să înceapă cu un semn procent (%) fără spații la început, dar cu un spațiu după, urmat de:
Prima linie: Numele comenzii, urmat de secțiunea manuală între paranteze, fără spații. Numele devine secțiunea din stânga și din dreapta a antetului. Prin convenție, numele comenzii este cu majuscule, deși nu întotdeauna. Orice urmează după numele comenzii și numărul secțiunii manuale devine secțiunea din stânga a subsolului. Folosește asta pentru numărul versiunii software.
A doua linie: Numele autorului (autorilor). Acestea sunt afișate într-o secțiune de autori generată automat a paginii de manual. Nu trebuie să adaugi o secțiune „Autori” – include doar 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 (#), marcajul pentru antet în markdown. Semnul numeric (#) trebuie să fie primul caracter al liniei, urmat de un spațiu.
Secțiunea de nume conține o linie rapidă cu numele comenzii, un spațiu, o liniuță (-), un spațiu și o descriere foarte scurtă a ceea ce face comanda.
Sinopsis
Sinopsisul prezintă formatele posibile ale liniei de comandă. Comanda poate accepta un model de căutare sau o opțiune de linie de comandă. Asteriscurile duble (**) de pe ambele părți ale numelui comenzii înseamnă că numele va fi afișat cu caractere aldine. Un singur asterisc (*) de fiecare parte a textului îl va afișa subliniat.
Implicit, o linie nouă este urmată de o linie goală. Pentru a forța o întrerupere de linie fără o linie goală, utilizează o bară oblică inversă (\).
Descriere
Descrierea explică funcția comenzii sau a programului. Include detaliile importante într-un mod concis. Nu scrii un ghid al utilizatorului.
Folosirea a două semne numerice (##) la începutul unei linii creează un titlu de nivelul doi. Poți folosi asta pentru a diviza descrierea în bucăți mai mici.
Opțiuni
Secțiunea de opțiuni conține o descriere a opțiunilor de linie de comandă. Prin convenție, acestea sunt afișate cu caractere aldine, deci adaugă două asteriscuri (**) înainte și după ele. Descrie opțiunile pe rândul următor, începând cu două puncte (:) și un spațiu.
Dacă descrierea este scurtă, man o va afișa pe aceeași linie cu opțiunea din linia de comandă. Dacă este prea lungă, va fi afișată ca un paragraf indentat, începând pe linia de sub opțiune.
Exemple
Secțiunea de exemple conține diverse formate de linie de comandă. Observă că începem liniile de descriere cu două puncte (:), ca în secțiunea de opțiuni.
Valori de ieșire
Această secțiune listează valorile returnate de comandă procesului care a apelat-o. Acesta poate fi shell-ul, dacă a fost apelată din linia de comandă, sau un script, dacă a fost lansată dintr-un script shell. Începem rândurile de descriere cu două puncte (:) și în această secțiune.
Erori
Secțiunea de erori listează erorile cunoscute, problemele sau particularitățile de care trebuie să știe utilizatorii. Pentru proiectele open source, se include adesea un link către instrumentul de urmărire a problemelor, pentru a verifica starea erorilor sau a raporta altele noi.
Drepturi de autor
Secțiunea de copyright conține declarația ta de drepturi de autor și descrierea tipului de licență sub care este lansat software-ul.
Un Mod Eficient de Lucru
Poți edita pagina de manual în editorul tău preferat. Majoritatea editoarelor cu evidențiere a sintaxelor vor recunoaște markdown și vor colora textul pentru a evidenția titlurile, caracterele aldine și subliniate. Este un ajutor vizual, dar adevărata probă este pagina de manual redată.
pandoc ms.1.md -s -t man | /usr/bin/man -l -
Deschide o fereastră de terminal în directorul cu fișierul markdown. Cu acesta deschis în editor, salvează periodic fișierul. De fiecare dată, poți executa următoarea comandă în terminal:
După ce folosești această comandă, poți apăsa săgeata în sus pentru a o repeta, apoi tasta Enter.
Această comandă apelează pandoc pe fișierul markdown (aici, denumit „ms.1.md”):
Opțiunea -s (standalone) generează o pagină de manual completă, nu doar un text formatat pentru man.
Opțiunea -t (tipul de ieșire) cu „man” spune pandoc să genereze ieșirea în format man. Nu i-am spus lui pandoc să trimită rezultatul într-un fișier, deci va fi trimis la stdout.
Transmitem ieșirea către man cu opțiunea -l (fișier local). Aceasta spune lui man să nu caute în baza de date de pagini de manual, ci să deschidă fișierul specificat. Dacă numele fișierului este -, man va primi intrarea de la stdin.
Pe scurt, poți salva din editor și apăsa Q pentru a închide man dacă rulează în terminal. Apoi, poți apăsa săgeata în sus, urmată de Enter, pentru a vedea o versiune redată a paginii de manual, direct în man.
Crearea paginii tale de manual
pandoc ms.1.md -s -t man -o ms.1
După ce ai terminat pagina de manual, creează o versiune finală și instalează-o pe sistem. Următoarea comandă îi spune lui pandoc să genereze o pagină de manual numită „ms.1”:
Aceasta urmează convenția de a denumi pagina de manual după comanda pe care o descrie și adaugă numărul secțiunii manuale ca o extensie de fișier.
manpath
Aceasta creează fișierul „ms.1”, noua pagină de manual. Unde o punem? Această comandă îți spune unde caută man pagini de manual:
Rezultatul ne oferă următoarele:
/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ă adăugăm noua noastră pagină de manual.
Reține că secțiunile manualului sunt organizate în directoare separate: man1, man2, man3, etc. Dacă directorul pentru o secțiune nu există, trebuie să-l creăm.
sudo mkdir /usr/local/man/man1
Pentru a face asta, introducem:
sudo cp ms.1 /usr/local/man/man1
Copiem fișierul „ms.1” în directorul corect. Man se așteaptă ca paginile de manual să fie comprimate, deci vom folosi gzip pentru a-l comprima.
sudo gzip /usr/local/man/man1/ms.1
:
sudo mandb
Pentru ca man să adauge noul fișier în baza de date, tastează:
man ms
Gata! Acum putem apela noua pagină de manual ca orice alta, tastând:
Noua pagină de manual este găsită și afișată.
Arată ca orice altă pagină de manual, cu text aldine, subliniat și indentat în locurile corecte.
Liniile de descriere scurte apar pe aceeași linie cu opțiunea pe care o descriu. Liniile prea lungi apar sub opțiunea pe care o descriu.
Am generat automat și secțiunea „Autori”. Subsolul include numărul versiunii software, data și numele comenzii, definite în antet.
Dacă dorești . . .
Odată ce pandoc a creat pagina de manual, poți edita direct fișierul în formatul macro groff înainte de a-l muta în directorul paginii de manual și a-l comprima cu gzip.