หน้า man นั้นยอดเยี่ยม ปัญหาอยู่ที่ตัวอ่าน man

• มักมีคำวิจารณ์ว่าหน้า man "ไม่มีลิงก์ที่เชื่อมถึงกัน" หรือ "เมื่อย่อหน้าต่างเทอร์มินัลแล้วข้อความไม่จัดเรียงใหม่" แต่จริง ๆ แล้ว ฟอร์แมต man เองรองรับทั้งความสามารถด้านลิงก์และการจัดเรียงข้อความใหม่
• ปัญหาอยู่ที่ เครื่องมือที่ใช้สำหรับอ่านหน้า man (เช่น คำสั่ง man และ less) ยังไม่ได้นำความสามารถเหล่านี้ไปใช้อย่างเหมาะสม

โครงสร้างฟอร์แมตของหน้า man

• เอกสาร man โดยหลักแล้วเขียนด้วยฟอร์แมตอยู่ 2 แบบ:
  • mdoc(7): ฟอร์แมตมาร์กอัปสมัยใหม่ที่อิงความหมาย
  • man(7): ฟอร์แมตแบบเก่าที่ใช้ในช่วงปี 1979~1989
• ตัวอย่าง (บางส่วนของไวยากรณ์ mdoc):

  .Sh NAME  
  .Nm openrc  
  .Nd stops and starts services for the specified runlevel  
  .Sh SYNOPSIS  
  

• .Sh, .Nm, .Nd หมายถึงส่วนหัวของหัวข้อ, ชื่อคำสั่ง และคำอธิบาย ตามลำดับ
• หากต้องการแก้ไขโดยตรง จำเป็นต้องอ้างอิงรายการแมโครของ mdoc

ความสามารถด้านการอ้างอิง (ลิงก์) ก็มีในตัวเช่นกัน

• ฟอร์แมต mdoc มีแมโครสำหรับลิงก์ดังต่อไปนี้:
• .Xr: การอ้างอิงข้ามไปยังหน้า man อื่น
• .Sx: การอ้างอิงไปยังหัวข้ออื่นภายในหน้าเดียวกัน
• เมื่อนำไปแปลงเป็น HTML จะเรนเดอร์เป็นลิงก์จริง และสามารถคลิกได้ในเบราว์เซอร์
• ส่วนหัวข้อ .Sh จะถูกจัดการเป็นแองเคอร์ จึงสามารถเป็นปลายทางของลิงก์ .Sx ได้
• แต่เมื่อดูในเทอร์มินัลผ่านคำสั่ง man ความสามารถด้านลิงก์นี้จะไม่ทำงาน

สรุป: ปัญหาไม่ได้อยู่ที่ฟอร์แมต man แต่อยู่ที่ตัวแสดงผล

• ปัจจุบันคำสั่ง man จะแสดงหน้าโดย pipe ไปยัง less ซึ่งวิธีนี้ไม่สามารถจัดการลิงก์ได้
• แนวทางแก้คือ:
• ต้องมีตัวแสดงหน้ารูปแบบใหม่ที่เข้าใจฟอร์แมต man และรองรับลิงก์
• ถ้ารองรับความสามารถ จัดเรียงข้อความใหม่อัตโนมัติ (reflow) เมื่อความกว้างของเทอร์มินัลเปลี่ยนไปด้วยก็จะยิ่งดี

ข้อมูลพื้นหลัง

• mdoc(7) เป็นฟอร์แมตที่ถูกนำมาใช้ใน 4.4BSD ช่วงทศวรรษ 1990
• man(7) เป็นฟอร์แมตคลาสสิกที่ใช้ในช่วงปี 1979~1989 และปัจจุบันแทบไม่ได้ใช้งานแล้ว

[scari]

ฉันเห็นแค่บรรทัดแรกจากการแจ้งเตือนของ Slack bot ก็คลิกทันทีเพราะเห็นด้วยมากเหมือนกัน ผม/ฉันเองก็เห็นด้วย 100% กับคำชี้ว่าปัญหาอยู่ที่ตัวรีดเดอร์

...แต่ดูเหมือนมนุษย์ยุคใหม่จะไม่ใช้ทั้ง man และแม้แต่เทอร์มินัลกันแล้วด้วยซ้ำ rtfm เลยกลายเป็นซากโบราณแห่งยุคโรแมนติกไปแล้ว

[winterjung]

ผมตั้งค่าไว้บน mac แบบด้านล่าง แล้วใช้เป็น pman ls เพื่อเปิดดูเป็น PDF

pman() {  
  mandoc -Tpdf "$(man -w $@)" | open -f -a Preview  
}  

[pcj9024]

ทริกเด็ดมาก... ขอบคุณครับ

[pkj3186]

สุดยอดมาก ขอบคุณครับ

[bbulbum]

ว้าว อันนี้โดนใจมากครับ ถ้าอ่าน man เป็นมันดีมากจริง ๆ แต่การจะอ่านให้เข้าใจนี่มันยากมาก ๆ..

[GN⁺]

ความคิดเห็นจาก Hacker News

• มีความเห็นว่าแม้จะเขียนเอกสารในรูปแบบ mdoc และ mandb มานาน แต่การเชี่ยวชาญภาษานั้นก็ยังเป็นเรื่องยาก
  • mdoc และ mandb เปรียบได้กับชุดแมโครที่อยู่บน roff
  • มีแนวคิดว่าอยากเสนอให้แปลงหน้า man ทั้งหมดเป็น Markdown แล้วให้ระบบแสดงผล
  • Markdown มีเครื่องมือรองรับมากกว่า จึงทำให้ผู้ใช้ที่ไม่ใช่สายเทคนิคก็เขียนเอกสารได้ง่าย
  • แต่ Markdown มีโครงสร้างเชิงรูปแบบน้อยกว่า จึงมีภาษาถิ่นที่แตกต่างกันไปในแต่ละโปรแกรม
• การนำทางหน้า info ใน Emacs มีประโยชน์ และสามารถทำสิ่งคล้ายกันกับหน้า man ได้
  • ความสมบูรณ์ของหน้า man แบบเดิมเป็นข้อดีที่หลายคนไม่ตระหนัก
  • รู้สึกเสียดายกับคนที่พยายามจะย้ายไปใช้ Markdown
  • หากย้ายไปใช้ Markdown ก็อาจมีความยากในการทำลิงก์และความหมายเชิงโครงสร้างทั่วไปแบบที่โซลูชันเดิมมีอยู่
  • เมื่อดูกรณีที่ย้ายข้อมูลไปเป็น JSON ก็จะเห็นความพยายามในการเพิ่มความสามารถที่ซับซ้อน
• การใช้ ft-man-plugin ที่มากับ Vim เป็นตัวอ่านหน้า man หลักช่วยแก้ปัญหาได้
  • ลิงก์ใช้งานได้ และยังคงการเยื้องเมื่อมีการตัดบรรทัด
  • อาจปรับปรุงค่าตั้งต้นของ less ได้ แต่จำเป็นต้องมีการเลื่อนแนวนอน
• น่าเสียดายที่หน้า man เวอร์ชันเว็บหลายแห่งตั้งค่าเป็นฟอนต์แบบความกว้างคงที่ที่ดูจำเจ
  • หน้า man ออนไลน์ของ OpenBSD ยอดเยี่ยมมาก
  • การอ่านหน้า man ในเทอร์มินัลก็ดีเช่นกัน
  • ส่วนใหญ่ใช้งานฟังก์ชันค้นหาและการเลื่อนทีละครึ่งหน้า
• pinfo เดิมมีไว้สำหรับดูหน้า GNU Info แต่ก็สามารถแสดงหน้า man ได้เช่นกัน
  • มันสามารถรับรู้การอ้างอิงข้ามระหว่างหน้าและนำทางได้
• มีความเห็นว่าน่าจะดีหากมีฟังก์ชันกระโดดไปยังคำอธิบายของแฟล็กที่ต้องการได้
  • ตอนนี้ใช้ regular expression เพื่อหาคำอธิบายของแฟล็ก
• มีข้อเสนอให้พิจารณาโครงการ mandoc
  • มันสามารถประมวลผลหน้าในเชิงความหมายได้ ทำให้ได้ผลลัพธ์ที่ดีกว่า
• มีความเห็นว่า Markdown เป็นทางออกที่ดีกว่า
  • คุ้นเคยกับการอ่านเอกสารบนเว็บหรือในตัวแก้ไขโค้ด จึงรู้สึกว่าอินเทอร์เฟซอื่นใช้งานไม่สะดวก
  • นักพัฒนาคุ้นเคยกับ Markdown และเอกสารส่วนใหญ่ก็เขียนด้วย Markdown
  • หน้า man ด้อยกว่าสำหรับทั้งผู้เขียนเอกสารและผู้อ่าน