Tôi đã viết một thư viện C nhỏ cho Linux và FreeBSD, và tôi sẽ viết tài liệu cho nó. Tôi đã cố gắng tìm hiểu thêm về việc tạo các trang man và không tìm thấy các hướng dẫn hoặc mô tả về các thực tiễn tốt nhất để tạo các trang man cho các thư viện. Cụ thể tôi quan tâm đến phần nào để đặt các trang man của các chức năng? 3? Có thể có ví dụ hay hướng dẫn sử dụng? Tạo trang man cho mỗi chức năng từ thư viện một ý tưởng tồi?
Câu trả lời:
Các trang hướng dẫn cho một thư viện sẽ đi vào phần 3.
Đối với các ví dụ hay về các trang hướng dẫn, hãy nhớ rằng một số được viết bằng cách sử dụng các chi tiết cụ thể của lưới và / hoặc sử dụng các macro cụ thể không thực sự di động.
Luôn có một số cạm bẫy về tính di động của các trang con người, vì một số hệ thống có thể (hoặc không) sử dụng các tính năng đặc biệt. Ví dụ, trong tài liệu dialog, tôi đã phải ghi nhớ (và giải quyết các khác biệt) trong các hệ thống khác nhau để hiển thị các ví dụ (không hợp lý).
Bắt đầu bằng cách đọc các phần có liên quan trong man manđó đề cập đến các macro tiêu chuẩn và so sánh các mô tả đó cho FreeBSD và Linux.
Việc bạn chọn viết một trang thủ công cho thư viện hay tách các trang thủ công cho các chức năng (hoặc nhóm chức năng) tùy thuộc vào mức độ phức tạp của các mô tả chức năng:
Đọc thêm:
Tôi sử dụng ronn . Bạn chỉ cần viết markdown và nó sẽ biến nó thành một trang. Ngoài ra còn có một bản sao js (có khả năng ít hơn) của nó được gọi là mark-man .
Tôi đã ghi lại các tập lệnh của mình bằng cách sử dụng END_MANheredocs được phân tách và mã C / C ++ của tôi bằng cách sử dụng cùng một END_MANheredocs được phân tách ngoại trừ bên trong/* */ . Hoặc là dễ dàng trích xuất với sed và sau đó có thể kết xuất thành một trang. (Với một chút tin tặc tín hiệu UNIX cùng với inotifywait, bạn có thể trích xuất và xem các phần manpage của mình trực tiếp và có trình duyệt manpage tải lại dưới dạng cập nhật nguồn.)
Đối với phần này, thì 3 sẽ là thư viện C cấp độ người dùng. Bạn có thể đọc về số phần (trong số những thứ khác) ở người đàn ông (1) .
Nếu bạn muốn xem một số có thể đọc được, có cấu trúc tốt ví dụ trang người đàn ông, tôi muốn có một cái nhìn tại Plan9 https://swtch.com/plan9port/unix/ thư viện nơi bạn có thể xem làm thế nào những người sáng tạo rất của cvà UNIXvà tài liệu của nó hệ thống có lẽ dành cho những thứ này để làm việc.
Để bổ sung câu trả lời khác, một ngôn ngữ khác markdown có thể được sử dụng để đơn giản hóa cách viết trang người đàn ông được reStructuredText và rst2man lệnh mà là một phần của python-docutils gói.
Ngôn ngữ đánh dấu này đã được python áp dụng cho tài liệu của nó , và dễ học, viết và bảo trì hơn nhiều so với các macro man troff tốt mà rst2man sẽ tạo cho bạn từ reSturationuredText của bạn.
Bạn có thể ghi lại API bằng cách sử dụng doxygen để cung cấp tham chiếu dưới dạng HTML và cũng tạo các trang man và các định dạng khác để đọc ngoại tuyến.
Ưu điểm của doxygen là đó là loại tài liệu "nội tuyến" như JavaDoc hoặc PythonDoc, nhân đôi khi nhận xét giao diện (hoặc vv., Nhận xét nhân đôi dưới dạng văn bản doc); bạn thêm các văn bản tài liệu vào các tệp nguồn / tiêu đề của mình và nó được trích xuất từ đó, điều này sẽ cải thiện cơ hội được cập nhật.
manđể lập trình ngoại trừ thư viện và tòa nhà chọc trời tiêu chuẩn.