Le pagine di manuale per una libreria andrebbero nella sezione 3.
Per buoni esempi di pagine di manuale, tieni presente che alcune sono scritte 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 funzionalità speciali. Ad esempio, nel documentare dialog , ho dovuto tenere a mente (e aggirare) le differenze nei vari sistemi di visualizzazione degli esempi (che non sono giustificate).
Inizia leggendo le sezioni pertinenti di man man dove menziona le macro standard e confronta quelle descrizioni per FreeBSD e Linux.
La scelta 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:
- ncurses ha alcune centinaia di funzioni su diverse dozzine di pagine di manuale.
- dialog ha diverse dozzine di funzioni in una pagina di manuale. Altri mostreranno sicuramente molti altri esempi.
Ulteriori letture:
- man -- visualizza le pagine di documentazione del manuale online (FreeBSD)
- man-pages - convenzioni per la scrittura di pagine man di Linux
- groff_mdoc -- riferimento per l'implementazione mdoc di groff
- HowTo:creare una manpage da zero. (FreeBSD)
- Che cos'è una "rimessa per biciclette"?
io uso ron. Scrivi semplicemente markdown e lo trasformerà in una manpage. C'è anche un (un po' meno capace) js clone di esso chiamato Marked-Man.
Ho documentato i miei script utilizzando END_MAN delimitato heredocs e il mio codice C/C++ utilizzando lo stesso END_MAN delimitato heredocstranne all'interno di /* */ . Entrambi sono facilmente estraibili con sed e quindi renderizzabili in una manpage. (Con un po' di hackeraggio del segnale UNIX insieme a inotifywait, puoi estrarre e visualizzare le sezioni della tua manpage dal vivo e ricaricare il browser della manpage man mano che la fonte si aggiorna. )
Per quanto riguarda la sezione, allora 3 sarebbe per una libreria C a livello utente. Puoi leggere i numeri di sezione (tra le altre cose) in man(1).
Se vuoi vedere alcune pagine man di esempio leggibili e ben strutturate, darei un'occhiata alle librerie Plan9 https://swtch.com/plan9port/unix/ dove puoi vedere come gli stessi creatori di c e UNIX e il suo sistema di documentazione probabilmente intendeva far funzionare queste cose.
Per integrare le altre risposte, un altro linguaggio markdown che può essere utilizzato per semplificare la scrittura di pagine man è reStructuredText e il comando rst2man che fa parte di python-docutils pacchetto.
Questo linguaggio markdown è stato adottato da Python per la sua documentazione ed è molto più facile da imparare, scrivere e mantenere rispetto alle buone vecchie macro troff man che rst2man genererà per te dal tuo reStructuredText.