Napisałem małą bibliotekę C dla Linuksa i FreeBSD i zamierzam napisać dla niej dokumentację. Próbowałem dowiedzieć się więcej o tworzeniu stron podręcznika i nie znalazłem instrukcji ani opisów najlepszych praktyk tworzenia stron podręcznika dla bibliotek. W szczególności jestem zainteresowany, w której sekcji umieścić strony podręcznika funkcji? 3? Może są tam dobre przykłady lub instrukcje? Tworzenie stron podręcznika dla każdej funkcji z biblioteki to zły pomysł?
Odpowiedzi:
Strony podręcznika do biblioteki przejdą w sekcji 3.
Dla dobrych przykładów stron podręcznika, pamiętaj, że niektóre są napisane przy użyciu konkretnych szczegółów groff i / lub używają określonych makr, które tak naprawdę nie są przenośne.
Przenośność stron podręcznika zawsze wiąże się z pewnymi pułapkami, ponieważ niektóre systemy mogą (ale nie muszą) korzystać ze specjalnych funkcji. Na przykład, dokumentując dialog, musiałem mieć na uwadze (i obejść) różnice w różnych systemach do wyświetlania przykładów (które nie są uzasadnione).
Zacznij od przeczytania odpowiednich sekcji, w man manktórych wspomniano o standardowych makrach, i porównaj te opisy dla FreeBSD i Linux.
To, czy zdecydujesz się napisać jedną stronę podręcznika dla biblioteki, czy osobne strony podręcznika dla funkcji (lub grup funkcji) zależy od tego, jak skomplikowane byłyby opisy funkcji:
Dalsza lektura:
Używam ronn . Po prostu piszesz przecenę, a to zmieni stronę w manpage. Jest też (nieco mniej zdolny) klon js o nazwie mark-man .
Dokumentuję za pomocą tego skryptu, używając END_MANograniczników heredoc i mojego kodu C / C ++, używając tych samych END_MANograniczników heredoc, z wyjątkiem wewnątrz /* */. Każdy z nich można łatwo wyekstrahować za pomocą sed, a następnie przekształcić w stronę podręcznika. (Przy odrobinie hakowania sygnału w systemie UNIX i inotifywait możesz wyodrębnić i wyświetlić sekcje strony man na żywo, a przeglądarka strony przeładuje się w miarę aktualizacji źródła).
Jeśli chodzi o sekcję, to 3 byłoby w przypadku biblioteki C na poziomie użytkownika. Możesz przeczytać o numerach sekcji (między innymi) w man (1) .
Jeśli chcesz zobaczyć jakieś czytelne, dobrze zorganizowany przykładowe strony podręcznika, chciałbym spojrzeć na Plan9 https://swtch.com/plan9port/unix/ bibliotek, gdzie można zobaczyć, jak samych twórców ci UNIXoraz jego dokumentacji system prawdopodobnie przeznaczony do działania tych rzeczy.
Aby uzupełnić inne odpowiedzi, innym językiem oznaczania, którego można użyć do uproszczenia pisania stron podręcznika man, jest reStructuredText i komenda rst2man, która jest częścią pakietu python-docutils .
Ten język wyceny został przyjęty przez Pythona do dokumentacji i jest znacznie łatwiejszy do nauczenia się, pisania i utrzymywania niż stare dobre makra troff man, które rst2man wygeneruje dla ciebie z twojego reStructuredText.
Możesz udokumentować interfejs API za pomocą doxygen, aby podać odwołanie jako HTML, a także wygenerować strony podręcznika i inne formaty do czytania offline.
Zaletą doxygen jest to, że jest to swego rodzaju „wbudowana” dokumentacja, taka jak JavaDoc lub PythonDoc, dublująca się jako komentarze interfejsu (lub vv., Komentarze dublujące się jako tekst doc); dodajesz teksty dokumentów do plików źródłowych / nagłówkowych i są one z nich wyodrębniane, co zwiększa szanse na aktualizację.
mando programowania oprócz standardowych bibliotek i wywołań systemowych.