Halaman manual untuk perpustakaan akan masuk ke bagian 3.
Untuk contoh halaman manual yang bagus, perlu diingat bahwa beberapa halaman ditulis menggunakan detail khusus groff dan/atau menggunakan makro tertentu yang tidak benar-benar portabel.
Selalu ada beberapa jebakan dalam portabilitas halaman manual, karena beberapa sistem mungkin (atau mungkin tidak) menggunakan fitur khusus. Misalnya dalam mendokumentasikan dialog , saya harus mengingat (dan mengatasi) perbedaan dalam berbagai sistem untuk menampilkan contoh (yang tidak dibenarkan).
Mulailah dengan membaca bagian yang relevan dari man man yang menyebutkan makro standar, dan bandingkan deskripsi tersebut untuk FreeBSD dan Linux.
Apakah Anda memilih untuk menulis satu halaman buku panduan untuk pustaka, atau memisahkan halaman buku panduan untuk fungsi (atau grup fungsi) bergantung pada seberapa rumit deskripsi fungsi nantinya:
- ncurses memiliki beberapa ratus fungsi di beberapa lusin halaman manual.
- dialog memiliki beberapa lusin fungsi dalam satu halaman manual. Orang lain pasti akan menunjukkan lebih banyak contoh.
Bacaan lebih lanjut:
- man -- tampilkan halaman dokumentasi manual online (FreeBSD)
- man-pages - konvensi untuk menulis halaman manual Linux
- groff_mdoc -- referensi untuk implementasi mdoc groff
- Cara:Membuat halaman manual dari awal. (FreeBSD)
- Apa itu "Bikeshed"?
Saya menggunakan ronn. Anda cukup menulis penurunan harga, dan itu akan mengubahnya menjadi halaman manual. Ada juga (agak kurang mampu) js tiruannya disebut orang bertanda.
Saya telah mendokumentasikan skrip saya dengan menggunakan END_MAN heredocs dipisahkan dan kode C/C++ saya dengan menggunakan END_MAN yang sama dipisahkan di sinidocskecuali dalam /* */ . Entah mudah diekstraksi dengan sed dan kemudian dirender menjadi halaman manual. (Dengan sedikit peretasan sinyal UNIX bersama dengan inotifywait, Anda dapat mengekstrak dan melihat bagian halaman manual Anda secara langsung dan memuat ulang browser halaman manual sebagai pembaruan sumber.)
Sedangkan untuk bagian, maka 3 adalah untuk pustaka C tingkat pengguna. Anda dapat membaca tentang nomor bagian (antara lain) di man(1).
Jika Anda ingin melihat beberapa contoh halaman manual yang dapat dibaca dan terstruktur dengan baik, saya akan melihat perpustakaan Plan9 https://swtch.com/plan9port/unix/ di mana Anda dapat melihat bagaimana pembuat c dan UNIX dan sistem dokumentasinya mungkin dimaksudkan agar hal-hal ini berfungsi.
Untuk melengkapi jawaban lain, bahasa markdown lain yang dapat digunakan untuk menyederhanakan penulisan halaman manual adalah reStructuredText dan perintah rst2man yang merupakan bagian dari python-docutils kemasan.
Bahasa penurunan harga ini telah diadopsi oleh python untuk dokumentasinya, dan jauh lebih mudah untuk dipelajari, ditulis, dan dipelihara, daripada makro troff man tua yang baik yang akan dibuat oleh rst2man untuk Anda dari reStructuredText Anda.