ต้องการให้โปรแกรม Linux ใหม่ของคุณดูเป็นมืออาชีพหรือไม่? ให้มัน man
หน้าหนังสือ. เราจะแสดงวิธีการที่ง่ายที่สุดและเร็วที่สุดให้คุณเห็น
เพจผู้ชาย
มีแก่นของความจริงในเรื่องตลก Unix เก่า “คำสั่งเดียวที่คุณต้องรู้คือ man
” NS man
เพจมีความรู้มากมาย และควรเป็นที่แรกที่คุณเปิดเมื่อคุณต้องการเรียนรู้เกี่ยวกับคำสั่ง
ให้ man
หน้าสำหรับยูทิลิตี้หรือคำสั่งที่คุณเขียนจะยกระดับจากโค้ดที่มีประโยชน์ไปเป็นแพ็คเกจ Linux ที่มีรูปแบบสมบูรณ์ ผู้คนคาดหวัง a man
หน้าสำหรับโปรแกรมที่เขียนขึ้นสำหรับ Linux หากคุณสนับสนุน Linux โดยกำเนิด a man
หน้าเป็นสิ่งจำเป็นหากคุณต้องการให้โปรแกรมของคุณได้รับการพิจารณาอย่างจริงจัง
ในอดีต man
หน้าต่างๆ ถูกเขียนโดยใช้ชุดมาโครการจัดรูปแบบ เมื่อคุณโทรหา man
จะเปิดเพจเรียก groff
เพื่ออ่านไฟล์และสร้างเอาต์พุตที่จัดรูปแบบตามมาโครในไฟล์ เอาต์พุตถูกวางลงใน less
แล้วแสดงให้คุณเห็น
เว้นแต่คุณจะสร้าง man
หน้าบ่อยครั้ง การเขียนหนึ่งหน้าและแทรกมาโครด้วยตนเองนั้นเป็นงานหนัก กรรมแห่งการสร้าง man
หน้าที่แยกวิเคราะห์อย่างถูกต้องและถูกต้องสามารถแซงหน้าเป้าหมายของคุณเพื่อให้คำอธิบายคำสั่งของคุณกระชับแต่ละเอียดถี่ถ้วน
คุณควรจดจ่อกับเนื้อหาของคุณ อย่าต่อสู้กับชุดมาโครที่คลุมเครือ
ที่เกี่ยวข้อง: วิธีใช้คำสั่ง man ของ Linux: ความลับและพื้นฐานที่ซ่อนอยู่
pandoc สู่หน่วยกู้ภัย
NS pandoc
โปรแกรมอ่านไฟล์ markdown และสร้างไฟล์ใหม่ในภาษามาร์กอัปและรูปแบบเอกสารต่างๆ ประมาณ 40 ภาษา รวมถึงไฟล์ของ man
หน้าหนังสือ. มันเปลี่ยน .โดยสิ้นเชิง man
ขั้นตอนการเขียนหน้าเพื่อที่คุณจะได้ไม่ต้องต่อสู้กับอักษรอียิปต์โบราณ
ในการเริ่มต้น คุณสามารถติดตั้ง pandoc
บน Ubuntu ด้วยคำสั่งนี้:
sudo apt-get install pandoc
บน Fedora คำสั่งที่คุณต้องการมีดังต่อไปนี้:
sudo dnf install pandoc
บน Manjaro พิมพ์:
sudo pacman -Syu pandoc
ที่เกี่ยวข้อง: วิธีใช้ pandoc เพื่อแปลงไฟล์บน Linux Command Line
ส่วนของผู้ชายหน้า
man
หน้ามีส่วนที่เป็นไปตามหลักการตั้งชื่อมาตรฐาน ส่วนของคุณ man
ความต้องการของหน้าถูกกำหนดโดยความซับซ้อนของคำสั่งที่คุณอธิบาย
อย่างน้อย man page ส่วนใหญ่มีส่วนเหล่านี้:
- ชื่อ: ชื่อของคำสั่งและบรรทัดเดียวที่อธิบายหน้าที่ของมัน
- เรื่องย่อ: คำอธิบายสั้น ๆ ของการเรียกที่ผู้อื่นสามารถใช้เพื่อเปิดโปรแกรมได้ สิ่งเหล่านี้แสดงประเภทของพารามิเตอร์บรรทัดคำสั่งที่ยอมรับ
- คำอธิบาย: คำอธิบายของคำสั่งหรือฟังก์ชัน
- ตัวเลือก: รายการตัวเลือกบรรทัดคำสั่ง และสิ่งที่พวกเขาทำ
- ตัวอย่าง: ตัวอย่างการใช้งานทั่วไปบางส่วน
- ค่าทางออก: รหัสส่งคืนที่เป็นไปได้และความหมาย
- บัก: รายการข้อบกพร่องและนิสัยใจคอที่รู้จัก บางครั้ง ลิงก์นี้จะเสริมด้วย (หรือแทนที่ด้วย) ลิงก์ไปยังตัวติดตามปัญหาสำหรับโครงการ
- ผู้เขียน: บุคคลหรือผู้ที่เขียนคำสั่ง
- ลิขสิทธิ์: ข้อความลิขสิทธิ์ของคุณ สิ่งเหล่านี้มักจะรวมถึงประเภทของใบอนุญาตภายใต้โปรแกรมที่เผยแพร่
หากคุณมองผ่านบางสิ่งที่ซับซ้อนกว่านั้น man
คุณจะเห็นว่ายังมีส่วนอื่นๆ อีกมากมายเช่นกัน ตัวอย่างเช่น ลอง man man
. คุณไม่จำเป็นต้องรวมทั้งหมด—แค่สิ่งที่คุณต้องการจริงๆ man
หน้าไม่มีที่สำหรับใช้คำ
ส่วนอื่นๆ ที่คุณจะเห็นบ่อยๆ ได้แก่:
- ดูสิ่งนี้ด้วย: คำสั่งอื่นๆ ที่เกี่ยวข้องกับเรื่องบางคำอาจพบว่ามีประโยชน์หรือมีความเกี่ยวข้อง
- ไฟล์: รายการไฟล์ที่รวมอยู่ในแพ็คเกจ
- คำเตือน: จุดอื่น ๆ ที่ควรทราบหรือระวัง
- ประวัติศาสตร์: ประวัติการเปลี่ยนแปลงสำหรับคำสั่ง
ส่วนต่างๆ ของคู่มือ
คู่มือ Linux ประกอบด้วย man
หน้า ซึ่งจะถูกแบ่งออกเป็นส่วนต่างๆ ที่มีหมายเลขเหล่านี้:
- โปรแกรมปฏิบัติการ: หรือคำสั่งเชลล์
- การโทรของระบบ: ฟังก์ชั่นที่มีให้โดยเคอร์เนล
- ห้องสมุดโทร: ฟังก์ชั่นภายในไลบรารีโปรแกรม
- ไฟล์พิเศษ.
- รูปแบบไฟล์และข้อตกลง: ตัวอย่างเช่น “/etc/passwd”
- เกม.
-
เบ็ดเตล็ด: แพ็คเกจมาโครและข้อตกลงเช่น
groff
. - คำสั่งการดูแลระบบ: มักจะสงวนไว้สำหรับรูท
- กิจวัตรเคอร์เนล: ปกติไม่ได้ติดตั้งไว้โดยปริยาย
ทั้งหมด man
หน้าต้องระบุว่าเป็นของส่วนใด และต้องเก็บไว้ในตำแหน่งที่เหมาะสมสำหรับส่วนนั้นด้วย ดังที่เราจะได้เห็นในภายหลัง NS man
หน้าสำหรับคำสั่งและยูทิลิตี้อยู่ในส่วนที่หนึ่ง
รูปแบบของผู้ชายหน้า
NS groff
รูปแบบมาโครไม่ใช่เรื่องง่ายที่จะแยกวิเคราะห์ด้วยสายตา ในทางตรงกันข้าม markdown เป็นเรื่องง่าย
ด้านล่างเป็นหน้าคนใน groff
.
หน้าเดียวกันแสดงอยู่ด้านล่างในมาร์กดาวน์
Front Matter
สามบรรทัดแรกสร้างสิ่งที่เรียกว่า เรื่องหน้า. ทั้งหมดนี้ต้องเริ่มต้นด้วยเครื่องหมายเปอร์เซ็นต์ (%
) โดยไม่มีช่องว่างนำหน้า แต่หลังจากนั้นหนึ่งช่อง ตามด้วย:
-
บรรทัดแรก: ประกอบด้วยชื่อของคำสั่ง ตามด้วยส่วนคู่มือในวงเล็บ โดยไม่มีช่องว่าง ชื่อจะกลายเป็นส่วนซ้ายและขวาของ
man
ส่วนหัวของหน้า ตามธรรมเนียมแล้ว ชื่อคำสั่งจะเป็นตัวพิมพ์ใหญ่ แม้ว่าคุณจะพบมากมายที่ไม่ใช่ สิ่งใดก็ตามที่ตามหลังชื่อคำสั่งและหมายเลขส่วนด้วยตนเองจะกลายเป็นส่วนด้านซ้ายของส่วนท้าย สะดวกในการใช้สำหรับหมายเลขเวอร์ชันซอฟต์แวร์ -
บรรทัดที่สอง: ชื่อของผู้แต่ง สิ่งเหล่านี้จะแสดงในส่วนผู้เขียนที่สร้างขึ้นโดยอัตโนมัติของ
man
หน้าหนังสือ. คุณไม่จำเป็นต้องเพิ่มส่วน “ผู้เขียน” เพียงแค่ใส่ชื่ออย่างน้อยหนึ่งชื่อที่นี่ - บรรทัดที่สาม: วันที่ซึ่งกลายเป็นส่วนตรงกลางของส่วนท้ายด้วย
ชื่อ
ส่วนต่างๆ จะแสดงด้วยบรรทัดที่ขึ้นต้นด้วยเครื่องหมายตัวเลข (#
) ซึ่งเป็นมาร์กอัปที่ระบุส่วนหัวในมาร์กอัป เครื่องหมายตัวเลข (#)
ต้องเป็นอักขระตัวแรกในบรรทัด ตามด้วยช่องว่าง
ส่วนชื่อมีซับในหนึ่งอันที่เร็วซึ่งมีชื่อของคำสั่ง ช่องว่าง ยัติภังค์ (-
) เว้นวรรค และคำอธิบายสั้นๆ เกี่ยวกับสิ่งที่คำสั่งทำ
เรื่องย่อ
เรื่องย่อมีรูปแบบต่างๆ ที่บรรทัดคำสั่งสามารถใช้ได้ คำสั่งนี้สามารถยอมรับรูปแบบการค้นหาหรือตัวเลือกบรรทัดคำสั่งได้ เครื่องหมายดอกจันทั้งสอง (**
) ที่ด้านใดด้านหนึ่งของชื่อคำสั่งหมายความว่าชื่อจะแสดงเป็นตัวหนาบน man
หน้าหนังสือ. เครื่องหมายดอกจันเดียว (*
) ที่ด้านใดด้านหนึ่งของข้อความบางส่วนทำให้เกิด man
หน้าเพื่อแสดงขีดเส้นใต้
ตามค่าเริ่มต้น ตัวแบ่งบรรทัดจะตามด้วยบรรทัดว่าง หากต้องการบังคับให้ฮาร์ดเบรกโดยไม่มีบรรทัดว่าง คุณสามารถใช้แบ็กสแลชต่อท้าย ().
คำอธิบาย
คำอธิบายอธิบายสิ่งที่คำสั่งหรือโปรแกรมทำ ควรครอบคลุมรายละเอียดที่สำคัญอย่างกระชับ จำไว้ว่าคุณไม่ได้เขียนคู่มือผู้ใช้
ใช้เครื่องหมายตัวเลขสองตัว (##
) ที่จุดเริ่มต้นของบรรทัดจะสร้างส่วนหัวระดับที่สอง คุณสามารถใช้สิ่งเหล่านี้เพื่อแบ่งคำอธิบายของคุณเป็นส่วนย่อยๆ
ตัวเลือก
ส่วนตัวเลือกประกอบด้วยคำอธิบายของตัวเลือกบรรทัดคำสั่งที่สามารถใช้กับคำสั่งได้ ตามธรรมเนียมแล้ว สิ่งเหล่านี้จะแสดงเป็นตัวหนา ดังนั้นให้ใส่เครื่องหมายดอกจันสองอัน (**
) ก่อนและหลังพวกเขา รวมคำอธิบายข้อความของตัวเลือกในบรรทัดถัดไปและเริ่มต้นด้วยเครื่องหมายทวิภาค (:
) ตามด้วยช่องว่าง
หากคำอธิบายสั้นพอ man
จะแสดงในบรรทัดเดียวกับตัวเลือกบรรทัดคำสั่ง หากยาวเกินไป จะแสดงเป็นย่อหน้าที่เยื้องขึ้นในบรรทัดด้านล่างตัวเลือกบรรทัดคำสั่ง
ตัวอย่าง
ส่วนตัวอย่างประกอบด้วยการเลือกรูปแบบบรรทัดคำสั่งต่างๆ โปรดทราบว่าเราเริ่มบรรทัดรายละเอียดด้วยเครื่องหมายทวิภาค (:
) เช่นเดียวกับที่เราทำในส่วนตัวเลือก
ค่าทางออก
ส่วนนี้แสดงรายการค่าส่งคืนที่คำสั่งของคุณส่งกลับไปยังกระบวนการโทร นี่อาจเป็นเชลล์ถ้าคุณเรียกมันจากบรรทัดคำสั่ง หรือสคริปต์ถ้าคุณเปิดมันจากเชลล์สคริปต์ เราเริ่มบรรทัดรายละเอียดด้วยเครื่องหมายทวิภาค (:
) ในส่วนนี้ด้วย
บัก
ส่วนบั๊กแสดงรายการบั๊กที่รู้จัก โกตชา หรือนิสัยใจคอที่ผู้คนจำเป็นต้องรู้ สำหรับโครงการโอเพนซอร์ซ เป็นเรื่องปกติที่จะรวมลิงก์ไปยังตัวติดตามปัญหาของโครงการเพื่อตรวจสอบสถานะของจุดบกพร่องหรือรายงานจุดบกพร่องใหม่
ลิขสิทธิ์
ส่วนลิขสิทธิ์ประกอบด้วยคำชี้แจงลิขสิทธิ์ของคุณ และโดยทั่วไปแล้ว คำอธิบายเกี่ยวกับประเภทของใบอนุญาตภายใต้การนำซอฟต์แวร์ออกใช้
เวิร์กโฟลว์ที่มีประสิทธิภาพ
คุณสามารถแก้ไข man
ในหน้าแก้ไขที่คุณชื่นชอบ ส่วนใหญ่ที่รองรับการเน้นไวยากรณ์จะรับรู้ถึงการมาร์กดาวน์และระบายสีข้อความเพื่อเน้นส่วนหัว รวมถึงตัวหนาและขีดเส้นใต้ เยี่ยมไปเลย แต่คุณไม่ได้ดูการเรนเดอร์ man
หน้าซึ่งเป็นข้อพิสูจน์ที่แท้จริงในการพุดดิ้ง
เปิดหน้าต่างเทอร์มินัลในไดเร็กทอรีที่มีไฟล์ markdown ของคุณ เมื่อเปิดอยู่ในโปรแกรมแก้ไข ให้บันทึกไฟล์ลงในฮาร์ดไดรฟ์เป็นระยะ ทุกครั้งที่คุณดำเนินการ คุณสามารถรันคำสั่งต่อไปนี้ในหน้าต่างเทอร์มินัล:
pandoc ms.1.md -s -t man | /usr/bin/man -l -
เมื่อคุณใช้คำสั่งนี้แล้ว คุณสามารถกดลูกศรขึ้นเพื่อทำซ้ำ จากนั้นกด Enter
คำสั่งนี้ยังเรียกใช้ pandoc
ในไฟล์ markdown (ในที่นี้เรียกว่า “ms.1.md”):
- NS
-s
(สแตนด์อโลน) ตัวเลือกสร้างจากบนลงล่างให้สมบูรณ์man
หน้า แทนที่จะเป็นเพียงข้อความบางส่วนในman
รูปแบบ. - NS
-t
(ประเภทเอาต์พุต) พร้อมตัวดำเนินการ “man” บอกpandoc
เพื่อสร้างผลผลิตในman
รูปแบบ. เราไม่ได้บอกpandoc
เพื่อส่งผลลัพธ์ไปยังไฟล์ ดังนั้นมันจะถูกส่งไปยังstdout
.
เรากำลังวางเอาต์พุตนั้นลงใน man
กับ -l
(ไฟล์ในเครื่อง) ตัวเลือก มันบอก man
ไม่ต้องค้นหาผ่าน man
ฐานข้อมูลกำลังมองหา man
หน้าหนังสือ. แต่ควรเปิดไฟล์ที่มีชื่อแทน หากชื่อไฟล์คือ -
, man
จะเอาข้อมูลจาก stdin
.
สิ่งนี้ทำให้คุณสามารถบันทึกจากโปรแกรมแก้ไขและกด Q เพื่อปิด man
ถ้ามันทำงานในหน้าต่างเทอร์มินัล จากนั้น คุณสามารถกดลูกศรขึ้น ตามด้วย Enter เพื่อดูเวอร์ชันของคุณ man
หน้าด้านใน man
.
ที่เกี่ยวข้อง: stdin, stdout และ stderr บน Linux คืออะไร
การสร้างหน้าคนของคุณ
หลังจากที่คุณเสร็จสิ้น man
คุณต้องสร้างเวอร์ชันสุดท้าย แล้วติดตั้งลงในระบบของคุณ คำสั่งต่อไปนี้บอก pandoc
เพื่อสร้าง man
หน้าชื่อ “ms.1”:
pandoc ms.1.md -s -t man -o ms.1
นี้เป็นไปตามแบบแผนของการตั้งชื่อ man
หน้าหลังคำสั่งที่อธิบายและต่อท้ายหมายเลขส่วนด้วยตนเองราวกับว่าเป็นนามสกุลไฟล์
สิ่งนี้จะสร้างไฟล์ “ms.1” ซึ่งเป็นไฟล์ใหม่ของเรา man
หน้าหนังสือ. เราจะวางมันไว้ที่ไหน? คำสั่งนี้จะบอกเราว่าที่ไหน man
ค้นหา man
หน้า:
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
หน้าที่จะบีบอัดดังนั้นเราจะใช้ gzip
เพื่อบีบอัด:
sudo gzip /usr/local/man/man1/ms.1
เพื่อทำ man
เพิ่มไฟล์ใหม่ลงในฐานข้อมูล พิมพ์ดังต่อไปนี้:
sudo mandb
แค่นั้นแหละ! ตอนนี้เราสามารถเรียกใหม่ของเรา man
หน้าเหมือนกับหน้าอื่น ๆ โดยพิมพ์:
man ms
ใหม่ของเรา man
พบและแสดงหน้า
มันดูเหมือนกับที่อื่นๆ man
หน้า ด้วยตัวหนา ขีดเส้นใต้ และเยื้องข้อความในตำแหน่งที่เหมาะสม
บรรทัดคำอธิบายที่พอดีกับตัวเลือกที่อธิบายจะปรากฏในบรรทัดเดียวกัน บรรทัดที่ยาวเกินกว่าจะพอดีจะปรากฏด้านล่างตัวเลือกที่อธิบาย
นอกจากนี้เรายังได้สร้างส่วน “ผู้เขียน” โดยอัตโนมัติอีกด้วย ส่วนท้ายยังรวมถึงหมายเลขเวอร์ชันซอฟต์แวร์ วันที่ และชื่อคำสั่ง ตามที่กำหนดไว้ในส่วนหน้า
ถ้าคุณต้องการ . . .
ครั้งหนึ่ง pandoc
ได้สร้าง .ของคุณ man
คุณยังสามารถแก้ไขไฟล์ได้โดยตรงใน groff
รูปแบบมาโครก่อนที่จะย้ายไปที่ man
ไดเรกทอรีหน้าและ gzip
มัน.