เหตุใด man page จึงไม่มีตัวอย่าง

52

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

man history

— Joy Deepak
แหล่งที่มา

1

ฉันเดาว่าพวกเขาต้องการประหยัดพื้นที่ดิสก์ที่มีค่าเช่นเดียวกับการกำจัด CR cf เลย Beckett, Watt , p.8: "พื้นที่ที่มีคุณค่ามากได้รับการบันทึก [... ] โดยการหลีกเลี่ยงคำสรรพนามสะท้อนมากมายหลังจากพูด "

— Peter - Reinstate Monica

3

วิธีแก้ปัญหาหนึ่งที่พยายามทำสำหรับปัญหานี้คือtldr-pages.github.ioถึงแม้ว่าฉันจะไม่เห็นว่าทำไมพวกเขาถึงทำให้ดาวน์โหลดทุกอย่างล่วงหน้าเพื่อการเข้าถึงแบบออฟไลน์ได้ง่าย

— นาธานลอง

man jqมีตัวอย่างมากกว่า 1,000 บรรทัด (บน Ubuntu 16.04)

— Motte001

49

ขึ้นอยู่กับหน้าคน ... ตามเนื้อผ้าพวกเขาได้รวมส่วนกับตัวอย่าง - แต่ด้วยเหตุผลบางอย่างที่มักจะหายไปจากหน้าคนที่อยู่ภายใต้ลินุกซ์ (และฉันถือว่าคนอื่นใช้คำสั่ง GNU - ซึ่งส่วนใหญ่วันนี้) ในอีกทางหนึ่ง Solaris เกือบทุกหน้าคนรวมส่วนตัวอย่างมักจะมีหลายตัวอย่าง

ถ้าฉันต้องเดาว่า FSF / GNU ใช้เวลานานในการใช้manเพจและไม่ต้องการให้ผู้ใช้ใช้ข้อมูลสำหรับเอกสารแทน infoหน้ามีแนวโน้มที่จะครอบคลุมมากกว่าหน้าคนและมักจะมีตัวอย่าง infoหน้ายังมี "topical" มากกว่า - คำสั่งที่เกี่ยวข้องเช่น (คำสั่ง. สำหรับการค้นหาไฟล์) มักจะพบกัน

อีกเหตุผลหนึ่งอาจเป็นเพราะ GNU และmanหน้าใช้ในระบบปฏิบัติการที่แตกต่างกันซึ่งอาจแตกต่างจากกัน (หลังจากมีความแตกต่างมากมายระหว่าง distros Linux ที่ต่างกัน) ความตั้งใจอาจเป็นไปได้ว่าผู้จัดพิมพ์ได้เพิ่มตัวอย่างที่เกี่ยวข้องกับระบบปฏิบัติการ / distro - ซึ่งเห็นได้ชัดว่าทำได้ยาก

ฉันจะเพิ่มmanหน้าเว็บที่ไม่เคยตั้งใจจะ "สอนผู้เริ่มต้น" UNIX ได้รับการพัฒนาโดยผู้เชี่ยวชาญด้านคอมพิวเตอร์ (แฮ็กเกอร์คำศัพท์เก่า) และตั้งใจที่จะใช้โดยผู้เชี่ยวชาญด้านคอมพิวเตอร์ หน้าคนไม่ได้ถูกสร้างขึ้นมาเพื่อสอนสามเณร แต่เพื่อช่วยเหลือผู้เชี่ยวชาญคอมพิวเตอร์อย่างรวดเร็วที่ต้องการการเตือนสำหรับตัวเลือกที่คลุมเครือหรือรูปแบบไฟล์แปลก ๆ

man- หน้าจึงมีวัตถุประสงค์เพื่อเป็น

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

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

ตัวอย่างส่วนตัวอย่างของหน้า man ของ Solaris - zfs (1M):

( ... )
ตัวอย่าง
     ตัวอย่างที่ 1 การสร้างลำดับชั้นของระบบไฟล์ ZFS

     คำสั่งต่อไปนี้สร้างระบบไฟล์ชื่อ pool / home
     และระบบไฟล์ชื่อ pool / home / bob จุดยึด
     / export / home ถูกตั้งค่าสำหรับระบบไฟล์พาเรนต์และเป็น
     สืบทอดโดยอัตโนมัติโดยระบบไฟล์ลูก

       # zfs สร้างพูล / โฮม
       # zfs set mountpoint = / export / home pool / home
       # zfs สร้างพูล / home / bob

     ตัวอย่างที่ 2 การสร้าง ZFS Snapshot

     คำสั่งต่อไปนี้สร้างสแน็ปช็อตที่ชื่อว่าเมื่อวานนี้
     สแน็ปช็อตนี้ติดตั้งตามต้องการใน. zfs / สแน็ปช็อต
     ไดเร็กทอรีที่รูทของระบบไฟล์ pool / home / bob

       # zfs snapshot pool / home / bob @ เมื่อวาน

     ตัวอย่างที่ 3 การสร้างและทำลายภาพรวมหลายภาพ

     คำสั่งต่อไปนี้สร้างสแน็ปช็อตที่ชื่อว่าเมื่อวานนี้
     pool / home และระบบไฟล์ที่สืบทอดทั้งหมด แต่ละ
     สแน็ปช็อตถูกเมานต์ตามความต้องการในไดเร็กทอรี. zfs / snapshot
     ที่รูทของระบบไฟล์ คำสั่งที่สองทำลาย
     ภาพรวมที่สร้างขึ้นใหม่

       # zfs snapshot -r pool / home @ เมื่อวาน
       # zfs ทำลาย -r pool / home @ เมื่อวานนี้

SunOS 5.11 การเปลี่ยนแปลงล่าสุด: 23 Jul 2012 51

การบริหารระบบคำสั่ง zfs (1M)

     ตัวอย่างที่ 4 การปิดใช้งานและเปิดใช้งานการบีบอัดระบบไฟล์

     คำสั่งต่อไปนี้ปิดใช้งานคุณสมบัติการบีบอัดสำหรับ
( ... )

หน้าตัวอย่างนี้มาพร้อมกับตัวอย่าง 16 (!) ... รุ่งโรจน์ถึง Solaris!
(และฉันจะยอมรับว่าตัวฉันเองได้ติดตามตัวอย่างเหล่านี้เป็นส่วนใหญ่แทนที่จะอ่านหน้าคนทั้งหมดสำหรับคำสั่งนี้ ... )

— Baard Kopperud
แหล่งที่มา

2

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

— Kusalananda

6

@ Kusalananda ในการป้องกันของฉันฉันได้อ่านเกี่ยวกับตัวเลือกต่าง ๆ และเกี่ยวกับคำสั่งย่อยที่ฉันต้องการจริง ๆ- ไม่ใช่ทุกอย่าง (ยัง) มันก็ไม่เกี่ยวข้องกับการใช้งานของฉัน ... แม้จะมีอันตรายจากการผิดตัวอย่างไม่ตอบสนองวัตถุประสงค์ - และถ้าสิ่งที่คุณต้องเป็นเพียงการใช้งานพื้นฐานที่สุดของคำสั่งการอ่านเกี่ยวกับระฆังและนกหวีดแทบจะไม่จำเป็น

— Baard Kopperud

@ Kusalananda มันอาจขึ้นอยู่กับคำสั่งด้วย ส่วนใหญ่ Unix และ GNU utils ฉันรู้ว่ามีเอกสารดี แต่คุณต้องการเอกสารประกอบเพื่อทำสิ่งที่เหมาะสม คำสั่ง Solaris รุ่นใหม่ (โดยเฉพาะzfs) ได้รับการออกแบบมาโดยธรรมชาติ ตัวอย่างเช่นzfs destroy pool/filesystemการใช้งานขั้นพื้นฐานและปรับได้ 90% ของกรณีการใช้งาน ตัวเลือกสั้น ๆ เช่น-rสำหรับrecursiveเป็นพิเศษมากขึ้นและต้องให้คำปรึกษาก่อนการใช้งานเพราะพวกเขาอาจจะไม่ได้ตั้งใจผลข้างเคียง

— 121391

26

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

— Faheem Mitha
แหล่งที่มา

7

มันขึ้นอยู่กับ:

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

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

— โทมัสผ้ากันเปื้อน
แหล่งที่มา

5

"ความพยายามประเภทนั้นสามารถเพิกเฉยได้" ฉันไม่แน่ใจว่าสิ่งนี้หมายถึงอะไร

— Faheem Mitha

เอกสารไม่ได้ช่วยอะไรที่มีประโยชน์เมื่อมันไม่ได้อิงจากประสบการณ์

— Thomas Dickey

ในความเป็นจริงเอกสารที่ไม่ได้อยู่บนพื้นฐานของประสบการณ์สามารถสร้างผลงานด้านลบได้ - นั่นเป็นเพียงข้อผิดพลาดธรรมดา

— alephzero

แน่นอน - ฉันพูดถึงมันเพราะตัวอย่างบางส่วนที่ OP ไม่ต้องสงสัยอยู่ในหมวดหมู่นี้ (ฉันจะละเว้นจากการจัดทำรายการในฟอรัมนี้)

— โทมัสผ้ากันเปื้อน

2

@ThomasDickey ฉันไม่เห็นด้วยกับการประเมินนี้อย่างสมบูรณ์ ความสามารถในการเขียนโปรแกรมอรรถประโยชน์นั้นไม่ได้มาพร้อมกับความสามารถในการอธิบาย API ให้กับผู้ใช้ปลายทาง T

— chiggsy

6

หากคุณกำลังมองหาทางเลือกอื่นใน man page คุณสามารถลองใช้bro pageซึ่งจะแสดงเฉพาะตัวอย่างต่าง ๆ ให้กับคำสั่งซึ่งคุณสามารถลงคะแนนได้จากรายการตัวอย่างที่ชุมชนส่งมา ตัวอย่างเช่นคำสั่งbro tarจะให้คุณ:

— BandW2011
แหล่งที่มา