วิธีสร้าง man Page บน Linux

ต้องการให้โปรแกรม Linux ใหม่ของคุณดูเป็นมืออาชีพหรือไม่? ให้หน้า man เราจะแสดงวิธีการที่ง่ายที่สุดและเร็วที่สุดให้คุณเห็น

เพจผู้ชาย

มีแก่นของความจริงในเรื่องตลก Unix แบบเก่า “คำสั่งเดียวที่คุณต้องรู้คือ man ” หน้า man มีความรู้มากมาย และควรเป็นที่แรกที่คุณเปิดเมื่อต้องการเรียนรู้เกี่ยวกับคำสั่ง

การให้ man page สำหรับยูทิลิตี้หรือคำสั่งที่คุณเขียนช่วยยกระดับจากโค้ดที่มีประโยชน์ไปเป็นแพ็คเกจ Linux ที่มีรูปแบบสมบูรณ์ ผู้คนคาดหวังว่าจะมี man page สำหรับโปรแกรมที่เขียนขึ้นสำหรับ Linux หากคุณสนับสนุน Linux โดยกำเนิด จำเป็นต้องมี man page หากคุณต้องการให้โปรแกรมของคุณได้รับการพิจารณาอย่างจริงจัง

ในอดีต man page ถูกเขียนโดยใช้ชุดของการจัดรูปแบบมาโคร เมื่อคุณเรียก man ให้เปิดเพจ มันจะเรียก groff เพื่ออ่านไฟล์และสร้างเอาต์พุตที่จัดรูปแบบ ตามมาโครในไฟล์ เอาต์พุตจะถูกวางลงใน less แล้วแสดงให้คุณเห็น

เว้นแต่คุณจะสร้าง man page บ่อยๆ การเขียนหนึ่งหน้าและการแทรกมาโครด้วยตนเองถือเป็นงานหนัก การสร้าง man page ที่แยกวิเคราะห์อย่างถูกต้องและถูกต้องสามารถแซงหน้าเป้าหมายของคุณในการให้คำอธิบายคำสั่งของคุณที่กระชับ แต่ละเอียดถี่ถ้วน

คุณควรจดจ่อกับเนื้อหาของคุณ ไม่ใช่ต่อสู้กับมาโครที่คลุมเครือ

ที่เกี่ยวข้อง: วิธีใช้คำสั่ง man ของ Linux: ความลับและพื้นฐานที่ซ่อนอยู่

pandoc สู่หน่วยกู้ภัย

โปรแกรม pandoc อ่านไฟล์ markdown และสร้างไฟล์ใหม่ในภาษามาร์กอัปและรูปแบบเอกสารต่างๆ ประมาณ 40 ภาษา รวมถึง man page มันเปลี่ยนกระบวนการเขียนหน้า man โดยสิ้นเชิง ดังนั้นคุณจึงไม่ต้องต่อสู้กับอักษรอียิปต์โบราณ

ในการเริ่มต้น คุณสามารถติดตั้ง pandoc บน Ubuntu ด้วยคำสั่งนี้:

 sudo apt-get ติดตั้ง pandoc 

บน Fedora คำสั่งที่คุณต้องการมีดังต่อไปนี้:

 sudo dnf ติดตั้ง pandoc 

บน Manjaro พิมพ์:

 sudo pacman -Syu pandoc 

ที่เกี่ยวข้อง: วิธีใช้ pandoc เพื่อแปลงไฟล์บน Linux Command Line

ส่วนของผู้ชายหน้า

หน้า man มีส่วนที่เป็นไปตามหลักการตั้งชื่อมาตรฐาน ส่วนที่ต้องการของ man page ถูกกำหนดโดยความซับซ้อนของคำสั่งที่คุณกำลังอธิบาย

อย่างน้อย man page ส่วนใหญ่มีส่วนเหล่านี้:

• ชื่อ : ชื่อของคำสั่งและบรรทัดเดียวที่อธิบายหน้าที่ของมัน
• เรื่องย่อ : คำอธิบายสั้น ๆ เกี่ยวกับการเรียกที่ผู้อื่นสามารถใช้เพื่อเปิดโปรแกรมได้ สิ่งเหล่านี้แสดงประเภทของพารามิเตอร์บรรทัดคำสั่งที่ยอมรับ
• Description : คำอธิบายคำสั่งหรือฟังก์ชัน
• ตัวเลือก : รายการตัวเลือกบรรทัดคำสั่ง และสิ่งที่พวกเขาทำ
• ตัวอย่าง : ตัวอย่างการใช้งานทั่วไปบางส่วน
• ค่าทางออก : รหัสส่งคืนที่เป็นไปได้และความหมาย
• บัก : รายการบั๊กและนิสัยใจคอที่รู้จัก บางครั้ง ลิงก์นี้จะเสริมด้วย (หรือแทนที่ด้วย) ลิงก์ไปยังตัวติดตามปัญหาสำหรับโครงการ
• ผู้แต่ง : บุคคลหรือผู้ที่เขียนคำสั่ง
• ลิขสิทธิ์ : ข้อความลิขสิทธิ์ของคุณ สิ่งเหล่านี้มักจะรวมถึงประเภทของใบอนุญาตที่โปรแกรมออกให้

หากคุณดู man page ที่ซับซ้อนกว่านี้ คุณจะเห็นว่ายังมีส่วนอื่นๆ อีกมากมายเช่นกัน ตัวอย่างเช่น ลอง man man . คุณไม่จำเป็นต้องรวมพวกเขาทั้งหมด—แค่สิ่งที่คุณต้องการจริงๆ หน้า man ไม่มีที่สำหรับใช้คำ

ส่วนอื่นๆ ที่คุณจะเห็นบ่อยๆ ได้แก่:

• ดูเพิ่มเติม ที่ : คำสั่งอื่นๆ ที่เกี่ยวข้องกับหัวข้อที่บางคำสั่งอาจพบว่ามีประโยชน์หรือมีความเกี่ยวข้อง
• ไฟล์ : รายการไฟล์ที่รวมอยู่ในแพ็คเกจ
• คำเตือน : จุดอื่น ๆ ที่ควรทราบหรือระวัง
• ประวัติ : ประวัติการเปลี่ยนแปลงสำหรับคำสั่ง

ส่วนต่างๆ ของคู่มือ

คู่มือ Linux ประกอบด้วย man page ทั้งหมด ซึ่งแบ่งออกเป็นส่วนต่างๆ ที่มีหมายเลขดังนี้:

1. โปรแกรมปฏิบัติการ: หรือคำสั่งเชลล์
2. การเรียกของระบบ: ฟังก์ชันที่เคอร์เนลให้มา
3. การเรียกไลบรารี: ฟังก์ชันภายในไลบรารีโปรแกรม
4. ไฟล์พิเศษ.
5. รูปแบบไฟล์และข้อตกลง: ตัวอย่างเช่น “/etc/passwd”
6. เกม.
7. เบ็ดเตล็ด: แพ็คเกจและข้อตกลงมาโคร เช่น groff
8. คำสั่งการดูแลระบบ: โดยปกติสงวนไว้สำหรับรูท
9. รูทีนของ เคอร์เนล: โดยปกติจะไม่ติดตั้งตามค่าเริ่มต้น

man page ทุกหน้าต้องระบุว่าเป็นของส่วนใด และต้องเก็บไว้ในตำแหน่งที่เหมาะสมสำหรับส่วนนั้น ตามที่เราจะเห็นในภายหลัง หน้าคู่มือสำหรับคำสั่งและยูทิลิตี้อยู่ในส่วนที่ man

รูปแบบของผู้ชายหน้า

รูปแบบมาโคร groff ไม่ใช่เรื่องง่ายที่จะแยกวิเคราะห์ด้วยสายตา ในทางตรงกันข้าม markdown เป็นเรื่องง่าย

ด้านล่างเป็นหน้าคนใน groff

หน้าเดียวกันแสดงอยู่ด้านล่างในมาร์กดาวน์

Front Matter

สามบรรทัดแรกสร้างสิ่งที่เรียกว่า เรื่องหน้า ทั้งหมดนี้ต้องขึ้นต้นด้วยเครื่องหมายเปอร์เซ็นต์ ( % ) โดยไม่มีช่องว่างนำหน้า ตามด้วย:

• บรรทัดแรก: ประกอบด้วยชื่อของคำสั่ง ตามด้วยส่วนคู่มือในวงเล็บ โดยไม่มีช่องว่าง ชื่อจะกลายเป็นส่วนซ้ายและขวาของส่วนหัวของหน้า man ตามธรรมเนียมแล้ว ชื่อคำสั่งจะเป็นตัวพิมพ์ใหญ่ แม้ว่าคุณจะพบมากมายที่ไม่ใช่ สิ่งใดก็ตามที่ตามหลังชื่อคำสั่งและหมายเลขส่วนด้วยตนเองจะกลายเป็นส่วนด้านซ้ายของส่วนท้าย สะดวกในการใช้สำหรับหมายเลขเวอร์ชันซอฟต์แวร์
• บรรทัดที่สอง: ชื่อของผู้แต่ง สิ่งเหล่านี้จะแสดงในส่วน man เขียนที่สร้างขึ้นโดยอัตโนมัติของหน้าคู่มือ คุณไม่จำเป็นต้องเพิ่มส่วน "ผู้เขียน" เพียงแค่ใส่ชื่ออย่างน้อยหนึ่งชื่อที่นี่
• บรรทัดที่สาม: วันที่ ซึ่งกลายเป็นส่วนตรงกลางของส่วนท้ายด้วย

ชื่อ

ส่วนต่างๆ จะถูกระบุด้วยบรรทัดที่ขึ้นต้นด้วยเครื่องหมายตัวเลข ( # ) ซึ่งเป็นมาร์กอัปที่ระบุส่วนหัวในมาร์กอัป เครื่องหมายตัวเลข ( #) ต้องเป็นอักขระตัวแรกในบรรทัด ตามด้วยช่องว่าง

ส่วนชื่อมีซับในหนึ่งบรรทัดสั้นๆ ที่ประกอบด้วยชื่อของคำสั่ง ช่องว่าง ยัติภังค์ ( - ) ช่องว่าง และคำอธิบายสั้นๆ เกี่ยวกับสิ่งที่คำสั่งทำ

เรื่องย่อ

เรื่องย่อมีรูปแบบต่างๆ ที่บรรทัดคำสั่งสามารถใช้ได้ คำสั่งนี้สามารถยอมรับรูปแบบการค้นหาหรือตัวเลือกบรรทัดคำสั่ง เครื่องหมายดอกจันสองตัว ( ** ) ที่ด้านใดด้านหนึ่งของชื่อคำสั่งหมายความว่าชื่อจะแสดงเป็นตัวหนาบนหน้า man เครื่องหมายดอกจันเดียว ( * ) ที่ด้านใดด้านหนึ่งของข้อความทำให้ man page แสดงขีดเส้นใต้

ตามค่าเริ่มต้น ตัวแบ่งบรรทัดจะตามด้วยบรรทัดว่าง หากต้องการบังคับให้ฮาร์ดเบรกโดยไม่มีบรรทัดว่าง คุณสามารถใช้แบ็กสแลชต่อท้าย ( \ )

คำอธิบาย

คำอธิบายอธิบายสิ่งที่คำสั่งหรือโปรแกรมทำ ควรครอบคลุมรายละเอียดที่สำคัญอย่างกระชับ จำไว้ว่าคุณไม่ได้เขียนคู่มือผู้ใช้

การใช้เครื่องหมายตัวเลขสองตัว ( ## ) ที่จุดเริ่มต้นของบรรทัดจะสร้างส่วนหัวระดับสอง คุณสามารถใช้สิ่งเหล่านี้เพื่อแบ่งคำอธิบายของคุณเป็นส่วนย่อยๆ

ตัวเลือก

ส่วนตัวเลือกประกอบด้วยคำอธิบายของตัวเลือกบรรทัดคำสั่งที่สามารถใช้กับคำสั่งได้ ตามธรรมเนียมแล้ว สิ่งเหล่านี้จะแสดงเป็นตัวหนา ดังนั้นให้ใส่เครื่องหมายดอกจันสองอัน ( ** ) ก่อนและหลังด้วย รวมคำอธิบายข้อความของตัวเลือกในบรรทัดถัดไปและเริ่มต้นด้วยเครื่องหมายทวิภาค ( : ) ตามด้วยช่องว่าง

หากคำอธิบายสั้นเพียงพอ man จะแสดงในบรรทัดเดียวกับตัวเลือกบรรทัดคำสั่ง หากยาวเกินไป จะแสดงเป็นย่อหน้าที่เยื้องขึ้นในบรรทัดด้านล่างตัวเลือกบรรทัดคำสั่ง

ตัวอย่าง

ส่วนตัวอย่างประกอบด้วยการเลือกรูปแบบบรรทัดคำสั่งต่างๆ โปรดทราบว่าเราเริ่มบรรทัดรายละเอียดด้วยเครื่องหมายทวิภาค ( : ) เช่นเดียวกับที่เราทำในส่วนตัวเลือก

ค่าทางออก

ส่วนนี้แสดงรายการค่าส่งคืนที่คำสั่งของคุณส่งกลับไปยังกระบวนการโทร นี่อาจเป็นเชลล์ถ้าคุณเรียกมันจากบรรทัดคำสั่ง หรือสคริปต์ถ้าคุณเปิดมันจากเชลล์สคริปต์ เราเริ่มบรรทัดรายละเอียดด้วยเครื่องหมายทวิภาค ( : ) ในส่วนนี้ด้วย

บัก

ส่วนบั๊กแสดงรายการบั๊กที่รู้จัก โกตชา หรือนิสัยใจคอที่ผู้คนจำเป็นต้องรู้ สำหรับโครงการโอเพนซอร์ซ เป็นเรื่องปกติที่จะรวมลิงก์ไปยังตัวติดตามปัญหาของโครงการเพื่อตรวจสอบสถานะของจุดบกพร่องหรือรายงานจุดบกพร่องใหม่

ลิขสิทธิ์

ส่วนลิขสิทธิ์ประกอบด้วยคำชี้แจงลิขสิทธิ์ของคุณ และโดยทั่วไปแล้ว คำอธิบายเกี่ยวกับประเภทของใบอนุญาตภายใต้การนำซอฟต์แวร์ออกใช้

เวิร์กโฟลว์ที่มีประสิทธิภาพ

คุณสามารถแก้ไขหน้า man ในโปรแกรมแก้ไขที่คุณชื่นชอบ ส่วนใหญ่ที่รองรับการเน้นไวยากรณ์จะรับรู้ถึงการมาร์กดาวน์และระบายสีข้อความเพื่อเน้นส่วนหัว รวมถึงตัวหนาและขีดเส้นใต้ มันยอดเยี่ยมมาก แต่คุณไม่ได้ดู man page ที่แสดงผลซึ่งเป็นข้อพิสูจน์ที่แท้จริงในพุดดิ้ง

เปิดหน้าต่างเทอร์มินัลในไดเร็กทอรีที่มีไฟล์ markdown ของคุณ เมื่อเปิดอยู่ในโปรแกรมแก้ไข ให้บันทึกไฟล์ลงในฮาร์ดไดรฟ์เป็นระยะ ทุกครั้งที่คุณดำเนินการ คุณสามารถรันคำสั่งต่อไปนี้ในหน้าต่างเทอร์มินัล:

 pandoc ms.1.md -s -t ชาย | /usr/bin/man -l - 

เมื่อคุณใช้คำสั่งนี้แล้ว คุณสามารถกดลูกศรขึ้นเพื่อทำซ้ำ จากนั้นกด Enter

คำสั่งนี้ยังเรียกใช้ pandoc ในไฟล์ markdown (ในที่นี้เรียกว่า “ms.1.md”):

• ตัวเลือก -s (สแตนด์อโลน) สร้าง man page ที่สมบูรณ์จากบนลงล่าง แทนที่จะเป็นเพียงข้อความบางส่วนในรูปแบบ man
• ตัวเลือก -t (ประเภทเอาต์พุต) พร้อมตัวดำเนินการ "man" บอกให้ pandoc สร้างเอาต์พุตในรูปแบบ man เราไม่ได้บอกให้ pandoc ส่งเอาต์พุตไปยังไฟล์ ดังนั้นมันจะถูกส่งไปยัง stdout

เรากำลังส่งเอาต์พุตนั้นไปยัง man ด้วยตัวเลือก -l (ไฟล์ในเครื่อง) มันบอก man ไม่ให้ค้นหาผ่านฐานข้อมูล man เพื่อค้นหา man page แต่ควรเปิดไฟล์ที่มีชื่อแทน ถ้าชื่อไฟล์คือ - man จะรับข้อมูลจาก stdin

สิ่งที่ทำให้เดือดคือคุณสามารถบันทึกจากโปรแกรมแก้ไขและกด Q เพื่อปิด man ถ้ามันทำงานในหน้าต่างเทอร์มินัล จากนั้น คุณสามารถกดลูกศรขึ้น ตามด้วย Enter เพื่อดู man page เวอร์ชันที่แสดงผลได้โดยตรงใน man

ที่เกี่ยวข้อง: stdin, stdout และ stderr บน Linux คืออะไร

การสร้างหน้าคนของคุณ

หลังจากที่คุณทำ man page เสร็จเรียบร้อยแล้ว คุณต้องสร้างเวอร์ชันสุดท้าย แล้วติดตั้งลงในระบบของคุณ คำสั่งต่อไปนี้บอกให้ pandoc สร้าง man page ชื่อ “ms.1”:

 pandoc ms.1.md -s -t man -o ms.1 

เป็นไปตามหลักการตั้งชื่อ man page หลังจากคำสั่งที่อธิบายและต่อท้ายหมายเลขส่วนแบบ manual ราวกับว่าเป็นนามสกุลไฟล์

สิ่งนี้จะสร้างไฟล์ “ms.1” ซึ่งเป็นหน้า man ใหม่ของเรา เราจะวางมันไว้ที่ไหน? คำสั่งนี้จะบอกเราว่า man ค้นหา man page ที่ไหน:

 manpath 

ผลลัพธ์ให้ข้อมูลต่อไปนี้แก่เรา:

• /usr/share/man: ตำแหน่งของไลบรารีมาตรฐานของหน้า man เราไม่เพิ่มหน้าในห้องสมุดนี้
• /usr/local/share/man: ลิงก์สัญลักษณ์นี้ชี้ไปที่ “/usr/local/man”
• /usr/local/man: นี่คือตำแหน่งที่เราจำเป็นต้องวางหน้า man ใหม่ของเรา

โปรดทราบว่าส่วนคู่มือต่างๆ จะอยู่ภายในไดเร็กทอรีของตนเอง: man1, man2, man3 และอื่นๆ หากไม่มีไดเร็กทอรีสำหรับส่วนนี้ เราต้องสร้างไดเร็กทอรีดังกล่าว

ในการทำเช่นนั้น เราพิมพ์ดังต่อไปนี้:

 sudo mkdir /usr/local/man/man1

จากนั้นเราจะคัดลอกไฟล์ "ms.1" ไปยังไดเร็กทอรีที่ถูกต้อง:

 sudo cp ms.1 /usr/local/man/man1

man คาดหวังให้ man page ถูกบีบอัด ดังนั้นเราจะใช้ gzip เพื่อบีบอัด:

 sudo gzip /usr/local/man/man1/ms.1

เมื่อต้องการให้ man เพิ่มไฟล์ใหม่ลงในฐานข้อมูล ให้พิมพ์ดังต่อไปนี้:

 sudo mandb 

แค่นั้นแหละ! ขณะนี้เราสามารถเรียกหน้า man ใหม่ของเราได้เหมือนกับหน้าอื่น ๆ โดยพิมพ์:

 ผู้ชาย ms 

พบและแสดงหน้า man ใหม่ของเรา

ดูเหมือนหน้า man อื่นๆ ที่มีข้อความตัวหนา ขีดเส้นใต้ และเยื้องในตำแหน่งที่เหมาะสม

บรรทัดคำอธิบายที่พอดีกับตัวเลือกที่อธิบายจะปรากฏในบรรทัดเดียวกัน บรรทัดที่ยาวเกินกว่าจะพอดีจะปรากฏด้านล่างตัวเลือกที่อธิบาย

นอกจากนี้เรายังได้สร้างส่วน "ผู้เขียน" โดยอัตโนมัติอีกด้วย ส่วนท้ายยังรวมถึงหมายเลขเวอร์ชันซอฟต์แวร์ วันที่ และชื่อคำสั่ง ตามที่กำหนดไว้ในส่วนหน้า

ถ้าคุณต้องการ . . .

เมื่อ pandoc ได้สร้าง man page ของคุณแล้ว คุณยังสามารถแก้ไขไฟล์โดยตรงในรูปแบบมาโคร groff ก่อนที่จะย้ายไปยังไดเร็กทอรี man page และ gzip