ฉันเขียนไลบรารี C ขนาดเล็กสำหรับ Linux และ FreeBSD และฉันจะเขียนเอกสารสำหรับมัน ฉันพยายามเรียนรู้เพิ่มเติมเกี่ยวกับการสร้างหน้าคนและไม่พบคำแนะนำหรือคำอธิบายของวิธีปฏิบัติที่ดีที่สุดในการสร้างหน้าคนสำหรับห้องสมุด โดยเฉพาะอย่างยิ่งฉันสนใจในส่วนที่จะนำหน้าคนของฟังก์ชั่น? 3 หรือไม่? อาจมีตัวอย่างหรือคู่มือดีๆ สร้างหน้าคนสำหรับแต่ละฟังก์ชั่นจากห้องสมุดเป็นความคิดที่ไม่ดี?
คำตอบ:
หน้าคู่มือสำหรับห้องสมุดจะไปในส่วนที่ 3
สำหรับตัวอย่างที่ดีของหน้าเว็บด้วยตนเองโปรดจำไว้ว่าบางหน้าเขียนโดยใช้รายละเอียดเฉพาะของ Groff และ / หรือใช้มาโครเฉพาะที่ไม่สามารถพกพาได้
มีข้อผิดพลาดบางประการในการพกพาของ man-pages เนื่องจากบางระบบอาจใช้ (หรืออาจไม่) ใช้คุณสมบัติพิเศษ ตัวอย่างเช่นในการทำเอกสารdialogฉันต้องจำไว้ (และหลีกเลี่ยง) ความแตกต่างในระบบต่าง ๆ สำหรับการแสดงตัวอย่าง (ซึ่งไม่เป็นธรรม)
เริ่มต้นด้วยการอ่านหัวข้อที่เกี่ยวข้องman manซึ่งกล่าวถึงมาโครมาตรฐานและเปรียบเทียบคำอธิบายเหล่านั้นสำหรับ FreeBSD และ Linux
ไม่ว่าคุณจะเลือกที่จะเขียนหน้าคู่มือหนึ่งหน้าสำหรับห้องสมุดหรือหน้าคู่มือแยกต่างหากสำหรับฟังก์ชั่น (หรือกลุ่มของฟังก์ชั่น) ขึ้นอยู่กับความซับซ้อนของคำอธิบายฟังก์ชั่น:
อ่านเพิ่มเติม:
ผมใช้Ronn คุณเพียงแค่เขียน markdown แล้วมันจะเปลี่ยนเป็น manpage นอกจากนี้ยังมี (ค่อนข้างน้อยที่มีความสามารถ) jsโคลนของมันเรียกว่าการทำเครื่องหมายคน
ฉันได้รับการจัดเก็บเอกสารสคริปต์ของฉันกับมันโดยใช้END_MANheredocs คั่นและรหัสของฉัน C / C ++ โดยใช้แบบเดียวกันEND_MANheredocs /* */คั่นยกเว้นภายใน สามารถดึงข้อมูลได้อย่างง่ายดายด้วย sed แล้วแสดงผลเป็น manpage (ด้วยการแฮ็คสัญญาณ UNIX เล็กน้อยพร้อมกับ inotifywait คุณสามารถแยกและดูส่วน manpage ของคุณสดๆและให้เบราว์เซอร์ manpage โหลดใหม่เป็นแหล่งอัปเดต)
สำหรับส่วนนี้จะเป็น 3 สำหรับไลบรารี C ระดับผู้ใช้ คุณสามารถอ่านเกี่ยวกับตัวเลขส่วน (เหนือสิ่งอื่น) ในคน (1)
หากคุณต้องการที่จะเห็นอ่านดีโครงสร้างหน้าคนบางตัวอย่างเช่นผมจะดูที่แผน 9 https://swtch.com/plan9port/unix/ห้องสมุดที่คุณสามารถดูวิธีการที่ผู้สร้างมากcและUNIXและเอกสารประกอบ ระบบอาจมีไว้สำหรับสิ่งเหล่านี้ในการทำงาน
เพื่อเสริมคำตอบอื่น ๆ ภาษา markdown อื่นที่สามารถใช้เพื่อทำให้การเขียน man page ง่ายขึ้นคือreStructuredTextและคำสั่งrst2manซึ่งเป็นส่วนหนึ่งของแพ็คเกจpython-docutils
ภาษามาร์คดาวน์ถูกนำไปใช้โดย python สำหรับเอกสารของมันและง่ายต่อการเรียนรู้เขียนและดูแลรักษามากกว่าแมโครแมน troff เก่าที่ดีซึ่ง rst2man จะสร้างให้คุณจาก reStructuredText ของคุณ
คุณสามารถจัดทำเอกสาร API โดยใช้doxygenเพื่อให้การอ้างอิงเป็น HTML และยังสร้าง man page และรูปแบบอื่น ๆ สำหรับการอ่านออฟไลน์
ข้อดีของ doxygen คือมันเป็นเอกสาร "inline" เช่น JavaDoc หรือ PythonDoc เพิ่มความคิดเห็นเป็นอินเทอร์เฟซ (หรือ vv. เป็นสองเท่าแสดงความคิดเห็นเป็นข้อความ doc); คุณเพิ่มข้อความ doc ลงในไฟล์ต้นฉบับ / ไฟล์ส่วนหัวของคุณและมันถูกแยกออกมาจากที่นั่นซึ่งช่วยเพิ่มโอกาสในการถูกอัพเดตเป็นปัจจุบัน
manเขียนโปรแกรมยกเว้นไลบรารี่มาตรฐานและ syscalls