Muss ich Manpages für die C-Bibliothek schreiben?

Handbuchseiten für eine Bibliothek würden in Abschnitt 3.

aufgenommen

Bei guten Beispielen für Manpages sollten Sie bedenken, dass einige unter Verwendung spezifischer Details von groff geschrieben wurden und/oder spezifische Makros verwenden, die nicht wirklich portierbar sind.

Es gibt immer einige Fallstricke bei der Portabilität von Manpages, da einige Systeme spezielle Funktionen verwenden (oder auch nicht). Zum Beispiel bei der Dokumentation von dialog , musste ich Unterschiede in verschiedenen Systemen zur Anzeige von Beispielen berücksichtigen (und umgehen) (die nicht gerechtfertigt sind).

Beginnen Sie mit Lesen die relevanten Abschnitte von man man wo es die Standardmakros erwähnt, und vergleichen diese Beschreibungen für FreeBSD und Linux.

Ob Sie sich dafür entscheiden, eine Handbuchseite für die Bibliothek oder separate Handbuchseiten für die Funktionen (oder Gruppen von Funktionen) zu schreiben, hängt davon ab, wie kompliziert die Beschreibungen der Funktionen wären:

• ncurses hat ein paar hundert Funktionen auf mehreren Dutzend Handbuchseiten.
• dialog hat mehrere Dutzend Funktionen in einer Handbuchseite. Andere werden sicher noch viele weitere Beispiele zeigen.

Weiterführende Literatur:

• man -- zeigt Online-Handbuchdokumentationsseiten an (FreeBSD)
• man-pages - Konventionen zum Schreiben von Linux-man-pages
• groff_mdoc – Referenz für die mdoc-Implementierung von groff
• HowTo:Eine Manpage von Grund auf neu erstellen. (FreeBSD)
• Was ist ein "Fahrradschuppen"?

Ich benutze Ronn. Sie schreiben einfach Markdown und es verwandelt es in eine Manpage. Es gibt auch ein (etwas weniger leistungsfähiges) js Klon davon namens selected-man.

Ich habe meine Skripte damit dokumentiert, indem ich END_MAN verwendet habe begrenzte Heredocs und meinen C/C++-Code, indem Sie denselben END_MAN verwenden begrenzt hierdocsaußer innerhalb von /* */ . Beide lassen sich leicht mit sed extrahieren und dann in eine Manpage rendern. (Mit ein wenig UNIX-Signal-Hacking zusammen mit inotifywait können Sie Ihre Manpage-Abschnitte extrahieren und live anzeigen und den Manpage-Browser neu laden lassen, wenn die Quelle aktualisiert wird. )

Was den Abschnitt betrifft, so wäre 3 für eine C-Bibliothek auf Benutzerebene. Sie können die Abschnittsnummern (unter anderem) in man(1) nachlesen.

Wenn Sie einige lesbare, gut strukturierte Beispiel-Manpages sehen möchten, werfe ich einen Blick auf die Bibliotheken von Plan9 https://swtch.com/plan9port/unix/, wo Sie sehen können, wie die Schöpfer von c und UNIX und sein Dokumentationssystem wahrscheinlich dafür gedacht, dass diese Dinge funktionieren.

Um die anderen Antworten zu ergänzen, ist eine weitere Markdown-Sprache, die zum Vereinfachen des Schreibens von Manpages verwendet werden kann, reStructuredText und der Befehl rst2man, der Teil der python-docutils ist Paket.

Diese Markdown-Sprache wurde von Python für seine Dokumentation übernommen und ist viel einfacher zu erlernen, zu schreiben und zu pflegen als die guten alten troff-Man-Makros, die rst2man für Sie aus Ihrem reStructuredText generiert.