Manuálové stránky pro knihovnu by patřily do sekce 3.
Pro dobré příklady manuálových stránek mějte na paměti, že některé jsou napsány pomocí specifických detailů groffu a/nebo používají specifická makra, která ve skutečnosti nejsou přenosná.
Vždy existují určitá úskalí v přenositelnosti manuálových stránek, protože některé systémy mohou (nebo nemusí) používat speciální funkce. Například v dokumentaci dialog , musel jsem mít na paměti (a obejít) rozdíly v různých systémech zobrazování příkladů (které nejsou oprávněné).
Začněte čtením příslušné sekce man man kde jsou zmíněna standardní makra a porovnat tyto popisy pro FreeBSD a Linux.
Zda se rozhodnete napsat jednu manuálovou stránku pro knihovnu, nebo samostatné manuálové stránky pro funkce (nebo skupiny funkcí), záleží na tom, jak komplikované by byly popisy funkcí:
- ncurses má několik stovek funkcí na několika desítkách manuálových stránek.
- dialogové okno obsahuje několik desítek funkcí na jedné manuálové stránce. Ostatní jistě ukážou mnohem více příkladů.
Další čtení:
- man -- zobrazí stránky s online manuálovou dokumentací (FreeBSD)
- man-page – konvence pro psaní manuálových stránek Linuxu
- groff_mdoc -- odkaz na implementaci groffova mdoc
- Jak na to:Vytvořte manuálovou stránku od začátku. (FreeBSD)
- Co je to "bikeshed"?
Používám ronn. Jednoduše napíšete markdown a změní se na manpage. K dispozici je také (poněkud méně schopný) js jeho klon s názvem Marked-man.
Dokumentoval jsem s ním své skripty pomocí END_MAN oddělil heredocs a můj kód C/C++ pomocí stejného END_MAN oddělené heredocskromě v rámci /* */ . Obojí lze snadno extrahovat pomocí sed a poté vykreslit do manuálové stránky. (S trochou unixového hackingu signálu spolu s inotifywait můžete extrahovat a prohlížet sekce manuálové stránky živě a nechat prohlížeč manuálových stránek znovu načíst jako aktualizace zdroje. )
Pokud jde o sekci, pak 3 by byla pro uživatelskou knihovnu C. O číslech sekcí (mimo jiné) si můžete přečíst v man(1).
Pokud chcete vidět nějaké čitelné, dobře strukturované vzorové manuálové stránky, podíval bych se do knihoven Plan9 https://swtch.com/plan9port/unix/, kde můžete vidět, jak sami tvůrci c a UNIX a jeho dokumentační systém je pravděpodobně určen k tomu, aby tyto věci fungovaly.
Pro doplnění ostatních odpovědí je dalším jazykem markdown, který lze použít ke zjednodušení psaní manuálových stránek, reStructuredText a příkaz rst2man, který je součástí python-docutils balík.
Tento markdown jazyk byl přijat pythonem pro svou dokumentaci a je mnohem snazší se ho naučit, psát a udržovat, než stará dobrá makra troff man, která pro vás rst2man vygeneruje z vašeho reStructuredText.