Ho scritto una piccola libreria C per Linux e FreeBSD e scriverò la documentazione per esso. Ho cercato di saperne di più sulla creazione di pagine man e non ho trovato le istruzioni o le descrizioni delle migliori pratiche per creare pagine man per le biblioteche. In particolare sono interessato a quale sezione mettere le pagine man delle funzioni? 3? Forse ci sono buoni esempi o manuali? Creare pagine man per ogni funzione dalla libreria una cattiva idea?
Risposte:
Le pagine di manuale per una biblioteca andrebbero nella sezione 3.
Per buoni esempi di pagine di manuali, tenere presente che alcuni sono scritti utilizzando dettagli specifici di groff e / o utilizzano macro specifiche che non sono realmente portabili.
Ci sono sempre alcune insidie nella portabilità delle pagine man, dal momento che alcuni sistemi possono (o meno) utilizzare funzioni speciali. Ad esempio, nel documentare dialog, ho dovuto tenere presente (e aggirare) le differenze nei vari sistemi per visualizzare esempi (che non sono giustificati).
Inizia leggendo le sezioni pertinenti in man mancui menziona le macro standard e confronta le descrizioni per FreeBSD e Linux.
Che tu scelga di scrivere una pagina di manuale per la libreria o pagine di manuale separate per le funzioni (o gruppi di funzioni) dipende da quanto complicate sarebbero le descrizioni delle funzioni:
Ulteriori letture:
Uso ronn . Devi semplicemente scrivere markdown e lo trasformerà in una manpage. C'è anche un clone js (un po 'meno capace) chiamato mark-man .
Ho documentato i miei script con esso utilizzando END_MANheredocs delimitati e il mio codice C / C ++ utilizzando gli stessi END_MANheredocs delimitati tranne all'interno /* */. Entrambi sono facilmente estraibili con sed e quindi renderizzabili in una manpage. (Con un po 'di pirateria informatica del segnale UNIX insieme a inotifywait, puoi estrarre e visualizzare le sezioni della tua manpage dal vivo e far ricaricare il browser della manpage come aggiornamenti della fonte.)
Per quanto riguarda la sezione, quindi 3 sarebbe per una libreria C di livello utente. Puoi leggere i numeri di sezione (tra le altre cose) in man (1) .
Se volete vedere qualche esempio, pagine man leggibili ben strutturati, mi piacerebbe prendere uno sguardo al Plan9 https://swtch.com/plan9port/unix/ librerie dove è possibile vedere come gli stessi creatori di ce UNIXe la sua documentazione sistema probabilmente destinato a far funzionare queste cose.
Per integrare le altre risposte, un altro linguaggio di marcatura che può essere usato per semplificare la scrittura di pagine man è reStructuredText e il comando rst2man che fa parte del pacchetto python-docutils .
Questo linguaggio di marcatura è stato adottato da Python per la sua documentazione ed è molto più facile da imparare, scrivere e mantenere, rispetto alle buone vecchie macro di troff man che rst2man genererà per te dal tuo reStructuredText.
È possibile documentare l'API utilizzando doxygen per fornire il riferimento come HTML e anche generare pagine man e altri formati per la lettura offline.
Il vantaggio di doxygen è che è una sorta di documentazione "inline" come JavaDoc o PythonDoc, che raddoppia come commenti dell'interfaccia (o vv., Che raddoppia come testo doc); aggiungi i testi del documento ai tuoi file sorgente / intestazione, ed è estratto da lì, il che migliora le possibilità di essere tenuto aggiornato.
manper la programmazione tranne la libreria standard e i syscalls.