Come creare una pagina man in Linux

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

Le pagine dell'uomo

Potrebbe esserci del vero nel vecchio scherzo di Unix, “il solo comando di cui hai bisogno lo so è man. ” il man Le pagine contengono un patrimonio di conoscenze e dovrebbero essere il primo posto dove andare quando vuoi informazioni su un comando.

Fornire un man la pagina di un'utilità o di un comando che hai scritto ti eleva da codice utile a pacchetto Linux completamente formato. La gente si aspetta un man pagina da fornire per un programma che è stato scritto per Linux. Se è nativamente compatibile con Linux, man La pagina è necessaria se vuoi che il tuo programma venga preso sul serio.

Storicamente il man le pagine sono state scritte utilizzando una serie di macro di formattazione. Quando chiami man per aprire una pagina, lama groff per leggi il file e genera un output formattato, secondo le macro nel file. L'uscita è convogliata a less, e successivamente mostrato per te.

A meno che tu non creda man pagine spesso, scriverne una e inserire manualmente le macro è un lavoro duro. L'atto di creare a man una pagina che viene analizzata correttamente e ha un bell'aspetto potrebbe superare il tuo obiettivo di fornire una descrizione concisa, ma completo, del tuo comando.

Devi concentrarti sui tuoi contenuti, non combattere una serie oscura di macro.

IMPARENTATO: Come usare il comando man di Linux: segreti nascosti e nozioni di base

pandoc in soccorso

il pandoc Programma legge i file di markup e ne genera di nuovi in ​​circa 40 diversi linguaggi di markup e formati di documenti, compreso quello di man pagina. Trasforma completamente il man procedura di scrittura della pagina in modo da non dover lottare con i geroglifici.

Iniziare, può installare pandoc in Ubuntu con questo comando:

sudo apt-get install pandoc

In Fedora, il comando che ti serve è il seguente:

sudo dnf install pandoc

A Manjaro, scriba:

sudo pacman -Syu pandoc

IMPARENTATO: Come usare pandoc per convertire i file sulla riga di comando di Linux

Sezioni di una pagina man

man Le pagine contengono sezioni che seguono una convenzione di denominazione standard. Le sezioni che man le esigenze della pagina sono dettate dalla raffinatezza del comando che stai descrivendo.

Minimamente, la maggior parte delle pagine man contiene queste sezioni:

• Nome: Il nome del comando e un breve riassunto 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.
• scelte: Un elenco di alternative da riga di comando e cosa fanno.
• Esempi di: Alcuni esempi di uso comune.
• Valori di uscita: Eventuali codici di ritorno e loro significato.
• insetti: Un elenco di bug e stranezze noti. Qualche volta, questo è completato con (o è sostituito da) un collegamento al tracker dei problemi del progetto.
• Autore: La persona o le persone che hanno scritto il comando.
• Diritto d'autore: Il tuo messaggio di copyright. Questi di solito includono anche il tipo di licenza con cui viene lanciato il programma.

Se guardi alcuni dei più complicati man pagine, vedrai che ci sono anche tante altre sezioni. Come esempio, Tentativo man man. Nonostante questo, non devi includerli tutti, solo quelli di cui hai veramente bisogno. man le pagine non sono posto per verbosità.

Alcune altre sezioni che vedrai abbastanza frequentemente sono:

• Guarda anche: Altri comandi relativi all'argomento che alcuni potrebbero trovare utili o pertinenti.
• record: Un elenco di file inclusi nel pacchetto.
• Avvertenze: Altri punti da conoscere o prestare attenzione.
• Storia: Una cronologia delle modifiche per il comando.

Sezioni del manuale

Il manuale di Linux consiste di tutte le man pagine, che è poi suddiviso in queste sezioni numerate:

1. Programmi eseguibili: I comandi della shell.
2. Chiamate di sistema: Funzioni fornite dal kernel.
3. Chiamate in biblioteca: Funzioni all'interno delle librerie di programmi.
4. File speciali.
5. Convenzioni e formati di file: Come esempio, “/ eccetera / passwd”.
6. Giochi.
7. Diverso: Pacchetti Macro e Convenzioni, Che cosa groff.
8. Comandi di amministrazione del sistema: Riservato regolarmente per root.
9. Routine del kernel: Di solito non installato per impostazione predefinita.

Ogni man La pagina deve indicare a quale sezione appartiene, e deve anche essere conservato nella posizione appropriata per quella sezione, come discusso di seguito. il man le pagine dei comandi e delle utilità appartengono alla sezione uno.

Il formato di una pagina man

il groff Il formato macro non è facile da analizzare visivamente. al contrario, lo sconto è semplicissimo.

Di seguito è riportata una pagina man su groff.

La stessa pagina è mostrata di seguito in vendita.

Argomento anteriore

Le prime tre righe formano qualcosa chiamato problema principale. Tutti questi dovrebbero iniziare con un segno di percentuale (%), nessuno spazio iniziale, tranne uno dopo, seguito da:

• La prima riga: Contiene il nome del comando, seguito dalla sezione manuale tra parentesi, no spazi. Il nome diventa le sezioni sinistra e destra del man Intestazione di pagina. 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 manuale diventa la sezione sinistra del piè di pagina. È conveniente usarlo per il numero di versione del software.
• La seconda riga: Il (il) Nome (S) del (il) Autore (è). Questi vengono visualizzati in una sezione degli autori generata automaticamente del man pagina. Non è necessario aggiungere una sezione “Autori”, basta includere almeno un nome qui.
• La terza riga: L'appuntamento, che diventa anche la parte centrale del footer.

Nome

Le sezioni sono indicate da linee che iniziano con un cancelletto (#), che è il markup che indica un'intestazione nel markup. Il segno del numero (#) deve essere il primo carattere della riga, seguito da uno spazio.

La sezione del nome ha una singola riga che include il nome del comando, Uno spazio, un trattino (-), uno spazio e poi una brevissima descrizione di cosa 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 significa che il nome verrà visualizzato in grassetto nel man pagina. Un solo asterisco (*) su entrambi i lati di un testo rende il man pagina da visualizzare sottolineata.

Per impostazione predefinita, un'interruzione di riga è seguita da una riga vuota. Per forzare un'interruzione senza una riga vuota, puoi usare una barra rovesciata alla fine ().

Descrizione

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

Uso dei simboli numerici (##) all'inizio di una riga creare un'intestazione di livello due. Puoi usarli per suddividere la tua descrizione in parti più piccole.

scelte

La sezione delle alternative contiene una descrizione delle alternative della riga di comando che possono essere utilizzate con il comando. Per convenzione, questi sono mostrati in grassetto, quindi includi due asterischi (**) prima e dopo di loro. Includi la descrizione testuale delle alternative nella riga successiva e inizia con i due punti (:), seguito da uno spazio.

Se la descrizione è abbastanza breve, man lo mostrerà sulla stessa riga dell'opzione della riga di comando. Se è troppo lungo, viene visualizzato come un paragrafo rientrato a partire dalla riga sotto l'opzione della riga di comando.

Esempi di

La sezione degli esempi contiene una selezione di diversi formati della riga di comando. Nota che iniziamo le righe descrittive con i due punti (:), nello stesso modo in cui abbiamo fatto con la sezione delle alternative.

Valori di uscita

Questa sezione elenca i valori di ritorno che il tuo comando invia alla procedura chiamante. Questa potrebbe essere la shell se la chiami dalla riga di comando, o uno script se lo hai lanciato da uno script di shell. Iniziamo le righe descrittive con i due punti (:) anche in questa sezione.

insetti

La sezione bug elenca i bug conosciuti, le trappole o le stranezze che le persone dovrebbero conoscere. Per 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 sul copyright e, generalmente, una descrizione del tipo di licenza con cui viene rilasciato il software.

Un flusso di lavoro efficiente

Puoi modificare il tuo man pagina nel tuo editor preferito. La maggior parte di coloro che supportano l'evidenziazione della sintassi saranno a conoscenza dei ribassi e coloreranno il testo per evidenziare i titoli, oltre che in grassetto e sottolinearlo. È fantastico, per quanto possibile., ma non stai vedendo un rendering man pagina, che è la vera prova nel budino.

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

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

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

Questo comando invoca anche pandoc nel file di vendita (qui, è chiamato “ms.1.md”):

• il -s (Indipendente) genera un completo dall'alto verso il basso man pagina, invece del solo testo dentro man formato.
• il -t L'opzione (tipo di uscita) con l'operatore “uomo” indica pandoc per generare il suo output in man formato. Non abbiamo detto pandoc per inviare il tuo output a un file, quindi sarà inviato a stdout.

Stiamo anche canalizzando quell'output verso man con il -l (file locale) opzione. Dado man non cercare attraverso man database alla ricerca del man pagina. Anziché, dovrebbe aprire il file indicato. Se il nome del file è -, man prenderà il tuo contributo da stdin.

Questo dipende dal fatto che puoi salvare dal tuo editor e premere Q per chiudere man se è in esecuzione nella finestra del terminale. Dopo, puoi premere la freccia su, seguito da Invio per vedere una versione renderizzata del tuo man pagina, appena dentro man.

IMPARENTATO: Cosa sono gli standard, stdout e stderr in Linux?

Creare la tua pagina man

Una volta completato il tuo man pagina, devi creare una versione finale e poi installarla sul tuo sistema. Il seguente comando dice pandoc per generare a man pagina chiamata “ms.1”:

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

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

Questo crea un file “ms.1”, qual è la nostra novità? man pagina. Dove lo mettiamo? Questo comando ci dirà dove man cerca man pagine:

manpath

I risultati ci danno le prossime informazioni:

• / usr / Condividere / uomo: La posizione della biblioteca standard di man pagine. Non aggiungiamo pagine a questa libreria.
• / usr / Locale / Condividere / uomo: Questo collegamento simbolico punta a “/ usr / Locale / uomo”.
• / usr / Locale / uomo: Qui è dove dovremmo posizionare il nostro nuovo man pagina.

Si noti che le diverse sezioni del manuale sono contenute nelle proprie directory: uomo1, uomo2, uomo3, eccetera. Se la directory della sezione non esiste, dobbiamo crearlo.

Per farlo, scriviamo 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 aspetta il man pagine da comprimere, quindi useremo gzip per comprimerlo:

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

Produrre man aggiungi il nuovo file al tuo database, scrivi quanto segue:

sudo mandb

Questo è tutto! Ora possiamo chiamare il nostro nuovo man pagina come qualsiasi altra scritta:

uomo signorina

Il nostro nuovo man la pagina viene trovata e visualizzata.

Sembra un altro man pagina, con testo in grassetto, sottolineatura e rientro nei punti appropriati.

Le righe descrittive che vanno a capo accanto all'opzione che descrivono appaiono sulla stessa riga. Le righe troppo lunghe per adattarsi appaiono sotto l'opzione che descrivono.

Inoltre, abbiamo generato automaticamente una sezione di “Autori”. Il piè di pagina include anche il numero di versione del software, la data e il nome del comando, come indicato nella pagina principale.

Se desideri . . .

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