Come creare una pagina man su Linux

Vuoi che il tuo nuovo programma Linux abbia un aspetto professionale? Dagli una pagina man . Ti mostreremo il modo più semplice e veloce per farlo.

Le pagine dell'uomo

C'è un fondo di verità nella vecchia battuta di Unix, "l'unico comando che devi sapere è man ". Le pagine man contengono una grande quantità di conoscenze e dovrebbero essere il primo posto in cui ti rivolgi quando vuoi conoscere un comando.

Fornire una pagina man per un'utilità o un comando che hai scritto lo eleva da un utile pezzo di codice a un pacchetto Linux completamente formato. La gente si aspetta che venga fornita una pagina man per un programma che è stato scritto per Linux. Se stai supportando Linux in modo nativo, una pagina man è obbligatoria se vuoi che il tuo programma sia preso sul serio.

Storicamente le pagine man sono state scritte utilizzando una serie di macro di formattazione. Quando invochi man per aprire una pagina, chiama groff per leggere il file e generare output formattato, in base alle macro nel file. L'output viene convogliato in less e quindi visualizzato per te.

A meno che non crei pagine man frequentemente, scriverne una e inserire manualmente le macro è un duro lavoro. L'atto di creare una pagina man che analizzi correttamente e appaia a destra può superare il tuo obiettivo di fornire una descrizione concisa, ma completa, del tuo comando.

Dovresti concentrarti sul tuo contenuto, non combattere un oscuro insieme di macro.

CORRELATO: Come utilizzare il comando man di Linux: Segreti nascosti e nozioni di base

pandoc in soccorso

Il programma pandoc legge i file markdown e ne genera di nuovi in ​​circa 40 diversi linguaggi di markup e formati di documenti, incluso quello della pagina man . Trasforma totalmente il processo di scrittura della pagina man in modo da non dover lottare con i geroglifici.

Per iniziare, puoi installare pandoc su Ubuntu con questo comando:

 sudo apt-get install pandoc 

Su Fedora, il comando di cui hai bisogno è il seguente:

 sudo dnf install pandoc 

Su Manjaro, digita:

 sudo pacman -Syu pandoc 

CORRELATI: Come utilizzare pandoc per convertire file sulla riga di comando di Linux

Sezioni di una pagina man

le pagine man contengono sezioni che seguono una convenzione di denominazione standard. Le sezioni di cui la tua pagina man bisogno sono dettate dalla sofisticatezza del comando che stai descrivendo.

Come minimo, la maggior parte delle pagine man contiene queste sezioni:

• Nome : il nome del comando e una riga concisa che ne descrive la funzione.
• Sinossi : Una descrizione concisa delle invocazioni che qualcuno può usare per avviare il programma. Questi mostrano i tipi di parametri della riga di comando accettati.
• Descrizione : una descrizione del comando o della funzione.
• Opzioni : un elenco di opzioni della riga di comando e cosa fanno.
• Esempi : Alcuni esempi di uso comune.
• Valori di uscita : I possibili codici di ritorno e il loro significato.
• Bug : un elenco di bug e stranezze noti. A volte, questo viene integrato con (o sostituito da) un collegamento al tracker dei problemi per il progetto.
• Autore : la persona o le persone che hanno scritto il comando.
• Copyright : Il tuo messaggio di copyright. Questi di solito includono anche il tipo di licenza con cui viene rilasciato il programma.

Se esamini alcune delle pagine man più complicate, vedrai che ci sono anche molte altre sezioni. Ad esempio, prova man man . Non devi includerli tutti, però, solo quelli di cui hai veramente bisogno. le pagine man non sono spazio per verbosità.

Alcune altre sezioni che vedrai ragionevolmente frequentemente sono:

• Vedi anche : Altri comandi relativi all'argomento che alcuni potrebbero trovare utili o pertinenti.
• File : un elenco di file inclusi nel pacchetto.
• Avvertenze : altri punti da conoscere o a cui prestare attenzione.
• Cronologia : una cronologia delle modifiche per il comando.

Sezioni del Manuale

Il manuale di Linux è composto da tutte le pagine man , che vengono poi suddivise in queste sezioni numerate:

1. Programmi eseguibili: oppure comandi della shell.
2. Chiamate di sistema: funzioni fornite dal kernel.
3. Chiamate alle librerie: funzioni all'interno delle librerie di programmi.
4. File speciali.
5. Formati e convenzioni di file: Ad esempio, "/etc/passwd".
6. Giochi.
7. Varie: pacchetti di macro e convenzioni, come groff .
8. Comandi di amministrazione del sistema: generalmente riservati a root.
9. Routine del kernel: di solito non installate per impostazione predefinita.

Ogni pagina di man deve indicare a quale sezione appartiene, e deve anche essere memorizzata nella posizione appropriata per quella sezione, come vedremo più avanti. Le pagine man per i comandi e le utilità appartengono alla sezione uno.

Il formato di una pagina man

Il formato della macro groff non è facile da analizzare visivamente. Al contrario, il ribasso è un gioco da ragazzi.

Di seguito una pagina man in groff .

La stessa pagina è mostrata sotto in markdown.

Materia anteriore

Le prime tre righe formano qualcosa chiamato materia anteriore . Questi devono iniziare tutti con un segno di percentuale ( % ), senza spazi iniziali ma uno dopo, seguito da:

• La prima riga: contiene il nome del comando, seguito dalla sezione manuale tra parentesi, senza spazi. Il nome diventa le sezioni sinistra e destra dell'intestazione della pagina man . Per convenzione, il nome del comando è in maiuscolo, anche se ne troverai molti che non lo sono. Tutto ciò che segue il nome del comando e il numero della sezione del manuale diventa la sezione sinistra del piè di pagina. È conveniente usarlo per il numero di versione del software.
• La seconda riga: Il nome/i dell'autore/i. Questi sono visualizzati in una sezione autori generata automaticamente della pagina man . Non è necessario aggiungere una sezione "Autori", basta includere almeno un nome qui.
• La terza riga: la data, che diventa anche la parte centrale del piè di pagina.

Nome

Le sezioni sono indicate da righe che iniziano con un segno numerico ( # ), che è il markup che indica un'intestazione in markdown. Il segno numerico ( #) deve essere il primo carattere della riga, seguito da uno spazio.

La sezione del nome contiene un'interessante riga che include il nome del comando, uno spazio, un trattino ( - ), uno spazio e quindi una breve descrizione di ciò che fa il comando.

Sinossi

La sinossi contiene i diversi formati che la riga di comando può assumere. Questo comando può accettare un modello di ricerca o un'opzione della riga di comando. I due asterischi ( ** ) su entrambi i lati del nome del comando indicano che il nome verrà visualizzato in grassetto nella pagina man . Un singolo asterisco ( * ) su entrambi i lati di un testo fa sì che la pagina man lo visualizzi sottolineato.

Per impostazione predefinita, un'interruzione di riga è seguita da una riga vuota. Per forzare un'interruzione definitiva senza una riga vuota, puoi utilizzare una barra rovesciata finale ( \ ).

Descrizione

La descrizione spiega cosa fa il comando o il programma. Dovrebbe coprire i dettagli importanti in modo succinto. Ricorda, non stai scrivendo una guida per l'utente.

L'utilizzo di due segni numerici ( ## ) all'inizio di una riga crea un'intestazione di livello due. Puoi usarli per suddividere la tua descrizione in blocchi più piccoli.

Opzioni

La sezione delle opzioni contiene una descrizione di tutte le opzioni della riga di comando che possono essere utilizzate con il comando. Per convenzione, questi sono visualizzati in grassetto, quindi includi due asterischi ( ** ) prima e dopo di essi. Includere la descrizione testuale delle opzioni nella riga successiva e iniziarla con due punti ( : ), seguiti da uno spazio.

Se la descrizione è abbastanza breve, man la visualizzerà sulla stessa riga dell'opzione della riga di comando. Se è troppo lungo, viene visualizzato come un paragrafo rientrato che inizia sulla riga sotto l'opzione della riga di comando.

Esempi

La sezione degli esempi contiene una selezione di diversi formati della riga di comando. Nota che iniziamo le righe descrittive con i due punti ( : ), proprio come abbiamo fatto per la sezione delle opzioni.

Valori di uscita

Questa sezione elenca i valori di ritorno che il comando invia al processo di chiamata. Questa potrebbe essere la shell se l'hai chiamata dalla riga di comando o uno script se l'hai avviato da uno script di shell. Iniziamo le righe descrittive con i due punti ( : ) anche in questa sezione.

Bug

La sezione dei bug elenca i bug noti, i trucchi o le stranezze che le persone devono conoscere. Per i progetti open source, è comune includere qui un collegamento al tracker dei problemi del progetto per controllare lo stato di eventuali bug o segnalarne di nuovi.

Diritto d'autore

La sezione sul copyright contiene la tua dichiarazione di copyright e, di solito, una descrizione del tipo di licenza in base alla quale il software viene rilasciato.

Un flusso di lavoro efficiente

Puoi modificare la tua pagina man nel tuo editor preferito. La maggior parte di coloro che supportano l'evidenziazione della sintassi saranno consapevoli del markdown e coloreranno il testo per evidenziare i titoli, nonché in grassetto e sottolinearlo. È fantastico per quanto riguarda, ma non stai guardando una pagina man renderizzata, che è la vera prova nel budino.

Apri una finestra di terminale nella directory che contiene il tuo file markdown. Con esso aperto nel tuo editor, salva periodicamente il tuo file sul tuo disco rigido. Ogni volta che lo fai, puoi eseguire il seguente comando nella finestra del terminale:

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

Dopo aver utilizzato questo comando, puoi premere la freccia su per ripeterlo, quindi premere Invio.

Questo comando invoca anche pandoc sul file markdown (qui, si chiama "ms.1.md"):

• L'opzione -s (autonoma) genera una pagina man completa dall'alto verso il basso, piuttosto che solo del testo in formato man .
• L'opzione -t (tipo di output) con l'operatore "man" dice a pandoc di generare il suo output in formato man . Non abbiamo detto a pandoc di inviare il suo output a un file, quindi verrà inviato a stdout .

Stiamo anche reindirizzando l'output in man con l'opzione -l (file locale). Dice a man di non cercare nel database man alla ricerca della pagina man . Invece, dovrebbe aprire il file denominato. Se il nome del file è - , man prenderà l'input da stdin .

Ciò a cui si riduce è che puoi salvare dal tuo editor e premere Q per chiudere man se è in esecuzione nella finestra del terminale. Quindi, puoi premere la freccia su, seguita da Invio per vedere una versione renderizzata della tua pagina man , proprio all'interno man .

CORRELATI: Cosa sono stdin, stdout e stderr su Linux?

Creazione della tua pagina man

Dopo aver completato la tua pagina man , devi crearne una versione finale e quindi installarla sul tuo sistema. Il comando seguente dice a pandoc di generare una pagina man chiamata "ms.1":

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

Questo segue la convenzione di nominare la pagina man dopo il comando che descrive e aggiungere il numero della sezione del manuale come se fosse un'estensione di file.

Questo crea un file "ms.1", che è la nostra nuova pagina man . Dove lo mettiamo? Questo comando ci dirà dove man cerca le pagine man :

 sentiero dell'uomo 

I risultati ci danno le seguenti informazioni:

• /usr/share/man: la posizione della libreria standard delle pagine man . Non aggiungiamo pagine a questa libreria.
• /usr/local/share/man: questo collegamento simbolico punta a "/usr/local/man".
• /usr/local/man: qui è dove dobbiamo posizionare la nostra nuova pagina man .

Si noti che le diverse sezioni del manuale sono contenute all'interno delle proprie directory: man1, man2, man3 e così via. Se la directory per la sezione non esiste, dobbiamo crearla.

Per fare ciò, digitiamo quanto segue:

 sudo mkdir /usr/local/man/man1

Quindi copiamo il file "ms.1" nella directory corretta:

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

man si aspetta che le pagine man siano compresse, quindi useremo gzip per comprimerlo:

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

Per fare in modo man aggiunga il nuovo file al suo database, digita quanto segue:

 sudo mandb 

Questo è tutto! Ora possiamo chiamare la nostra nuova pagina man come qualsiasi altra digitando:

 uomo ms 

La nostra nuova pagina man viene trovata e visualizzata.

Ha l'aspetto di qualsiasi altra pagina man , con testo in grassetto, sottolineato e rientrato nei punti appropriati.

Le righe di descrizione che si adattano accanto all'opzione che descrivono vengono visualizzate sulla stessa riga. Le righe troppo lunghe per adattarsi appaiono sotto l'opzione che descrivono.

Abbiamo anche generato automaticamente una sezione "Autori". Il piè di pagina include anche il numero di versione del software, la data e il nome del comando, come definito nella parte iniziale.

Se lo desidera . . .

Una volta pandoc ha creato la tua pagina man , puoi anche modificare direttamente il file nel formato macro groff prima di spostarlo nella directory della pagina man e gzip .