มีรูปแบบ "มาตรฐาน" สำหรับบรรทัดคำสั่ง / ข้อความช่วยเหลือของเชลล์หรือไม่?


239

ถ้าไม่เป็นจริงมีมาตรฐานหรือไม่ โดยทั่วไปฉันกำลังเขียนข้อความช่วยเหลือบรรทัดคำสั่งเช่น:

usage: app_name [options] required_input required_input2
  options:
    -a, --argument     Does something
    -b required     Does something with "required"
    -c, --command required     Something else
    -d [optlistitem1 optlistitem 2 ... ]     Something with list

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


8
ฉันคิดว่า GNU มีคำแนะนำบางอย่าง ฉันจะดูว่ายูทิลิตี้ GNU ส่วนใหญ่กำลังทำอะไรอยู่
Basile Starynkevitch

1
@DanielPryden ฉันคิดว่าคำตอบในคำถามนั้นทำให้เข้าใจผิดเล็กน้อย มันจะช่วยให้การเชื่อมโยงที่อธิบายสิ่งที่สวิทช์ควรจะได้รับการยอมรับและไม่ได้เป็นวิธีการส่งออกของ--helpควรดู แต่คำถามทั้งสองเป็นตัวเลือกที่ดีสำหรับการรวม
pmr

@ pmr: ฉันเห็นด้วย - บางที mod อาจรวมคำถามสำหรับเรา
Daniel Pryden

2
ฉันจะดูว่ายูทิลิตี้ GNU ส่วนใหญ่ทำอะไรอยู่และทำอย่างอื่น
Yakov Galka

คำตอบ:


160

โดยทั่วไปแล้วความช่วยเหลือของคุณควรรวมถึง:

  • คำอธิบายเกี่ยวกับสิ่งที่แอพทำ
  • ไวยากรณ์การใช้งานซึ่ง:
    • ใช้[options]เพื่อระบุตำแหน่งของตัวเลือกต่างๆ
    • arg_name สำหรับ ARG ที่ต้องการเอกพจน์
    • [arg_name] สำหรับตัวเลือกหาเรื่องเอกพจน์
    • arg_name... สำหรับ arg ที่ต้องการซึ่งสามารถมีได้มากมาย (นี่เป็นของหายาก)
    • [arg_name...] สำหรับหาเรื่องสำหรับจำนวนใด ๆ ที่สามารถจัดจำหน่าย
    • โปรดทราบว่าarg_nameควรเป็นชื่อที่สื่อความหมายสั้น ๆ ในกรณีงูที่ต่ำกว่า
  • รายการตัวเลือกที่จัดรูปแบบไว้อย่างดีแต่ละรายการ:
    • มีคำอธิบายสั้น ๆ
    • แสดงค่าเริ่มต้นถ้ามี
    • แสดงค่าที่เป็นไปได้ถ้ามี
    • โปรดทราบว่าหากตัวเลือกสามารถยอมรับรูปแบบสั้น ๆ (เช่น-l) หรือรูปแบบยาว (เช่น--list) รวมไว้ในบรรทัดเดียวกันเนื่องจากคำอธิบายจะเหมือนกัน
  • ตัวบ่งชี้ย่อของที่ตั้งของไฟล์กำหนดค่าหรือตัวแปรสภาพแวดล้อมที่อาจเป็นแหล่งที่มาของอาร์กิวเมนต์บรรทัดคำสั่งเช่น GREP_OPTS
  • หากมี man page ให้ระบุเช่นนั้นมิฉะนั้นตัวบ่งชี้สั้น ๆ ว่าสามารถพบความช่วยเหลือแบบละเอียดเพิ่มเติมได้ที่ใด

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


3
จะเป็นอย่างไรถ้าฉันมี ARG ที่ต้องการสองรูปแบบ เช่นวิธีการมาตรฐานมากขึ้นในการพูดว่า: usage: move (+|-)pixelsคือเมื่อหนึ่ง+ หรือ -เป็นผู้ได้รับมอบอำนาจ ? (ฉันรู้ว่าฉันสามารถมี 2 เส้นการใช้งาน แต่ฉันชอบความคิดในการเพิ่มเป็นสองเท่าด้วยการโต้แย้งใหม่แต่ละครั้ง) คุณสามารถคิดตัวอย่างจากเครื่องมือมาตรฐานได้หรือไม่?
Alois Mahdal

4
@AloisMahdal ผมมักจะเห็น{a|b|c|...}ในส่วนความช่วยเหลือสำหรับ SysV Init สคริปต์ / บริการพุ่งพรวดซึ่งจำเป็นต้องมีการโต้แย้งเอกพจน์ที่เป็นหนึ่งa, b, cฯลฯ ตัวอย่างเช่นโดยไม่โต้แย้งในระบบของฉันพิมพ์ออกservice sddm Usage: /etc/init.d/sddm {start|stop|status|restart|try-restart|force-reload}ดังนั้นคนส่วนใหญ่อาจจะเข้าใจusage: move {+|-}pixels}โดยเฉพาะอย่างยิ่งหากมีตัวอย่าง:example: move +5
Braden ที่ดีที่สุด

@JorgeBucaran พวกเขาไม่ควรออกจากสถานะ 0 พวกเขาควรทำอย่างไร? ฉันเชื่อว่าการออกจากสถานะ 2 เป็นมาตรฐานสำหรับคำสั่งเชลล์ที่ไม่ถูกต้อง
inavda

91

ลองดูที่docopt เป็นมาตรฐานที่เป็นทางการสำหรับการบันทึก (และแยกวิเคราะห์อัตโนมัติ) อาร์กิวเมนต์บรรทัดคำสั่ง

ตัวอย่างเช่น...

Usage:
  my_program command --option <argument>
  my_program [<optional-argument>]
  my_program --another-option=<with-argument>
  my_program (--either-that-option | <or-this-argument>)
  my_program <repeating-argument> <repeating-argument>...

46

ฉันคิดว่าไม่มีไวยากรณ์มาตรฐานสำหรับการใช้บรรทัดคำสั่ง แต่ส่วนใหญ่ใช้การประชุมนี้:

Microsoft Command-Line Syntax , IBM มีไวยากรณ์ Command-Line ที่คล้ายกัน


  • Text without brackets or braces

    รายการที่คุณต้องพิมพ์ตามที่แสดง

  • <Text inside angle brackets>

    ตัวยึดตำแหน่งที่คุณต้องระบุค่า

  • [Text inside square brackets]

    รายการเสริม

  • {Text inside braces}

    ชุดของรายการที่ต้องการ; เลือกมาหนึ่งอย่าง

  • แถบแนวตั้ง {a|b}

    ตัวคั่นสำหรับรายการพิเศษร่วมกัน เลือกมาหนึ่งอย่าง

  • การตัดคำทิ้งจากประโยด <file> …

    รายการที่สามารถทำซ้ำได้


16

เรากำลังใช้งาน Linux ซึ่งเป็นระบบปฏิบัติการที่สอดคล้องกับ POSIX เป็นส่วนใหญ่ มาตรฐาน POSIX มันควรจะเป็น: ยูทิลิตี้อาร์กิวเมนต์ไวยากรณ์

  • ตัวเลือก-oคือยัติภังค์ตามด้วยตัวอักษรและตัวเลขเดียวเช่นนี้
  • ตัวเลือกอาจต้องมีการโต้แย้ง (ซึ่งจะต้องปรากฏขึ้นทันทีหลังจากตัวเลือก); ตัวอย่างเช่นหรือ-o argument -oargument
  • ตัวเลือกที่ไม่ต้องมีการขัดแย้งสามารถแบ่งหลังจากยัติภังค์ดังนั้นสำหรับตัวอย่างเช่นเทียบเท่ากับ-lst-t -l -s
  • ตัวเลือกสามารถปรากฏในลำดับใด ๆ จึงจะเทียบเท่ากับ-lst-tls
  • ตัวเลือกสามารถปรากฏได้หลายครั้ง
  • ตัวเลือกนำหน้าข้อโต้แย้ง nonoption อื่น ๆ : -lstnonoption
  • --อาร์กิวเมนต์ยุติตัวเลือก
  • โดย-ทั่วไปจะใช้ตัวเลือกเพื่อแทนหนึ่งในสตรีมอินพุตมาตรฐาน

2
เป็นเรื่องปกติที่การใช้งานใน GNU / Linux จะไม่เป็นไปตามมาตรฐานนี้ เรียกใช้เช่นman aptitudeที่ผลนี้ aptitude [<options>...] {add-user-tag | remove-user-tag} <tag> <packages>...(เหนือสิ่งอื่น): มันมี {และ} เพื่อผูกคำสั่งบังคับทางเลือก ผมคิดว่า (และ) สามารถนำมาใช้สำหรับเดียวกันเหมือนพวกเขาจะใช้ในdocopt
jarno

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

11

Microsoft มีข้อกำหนดมาตรฐานบรรทัดคำสั่งของตนเอง:

เอกสารนี้มุ่งเน้นที่ผู้พัฒนาโปรแกรมอรรถประโยชน์บรรทัดคำสั่ง เป้าหมายของเราคือการนำเสนอประสบการณ์ผู้ใช้บรรทัดคำสั่งที่สอดคล้องได้ ความสำเร็จที่ทำให้ผู้ใช้สามารถเรียนรู้ชุดแนวคิดหลัก (ไวยากรณ์การตั้งชื่อพฤติกรรม ฯลฯ ) แล้วสามารถแปลความรู้นั้นไปทำงานกับชุดคำสั่งขนาดใหญ่ คำสั่งเหล่านั้นควรสามารถส่งออกกระแสข้อมูลมาตรฐานในรูปแบบมาตรฐานเพื่อให้สามารถจัดองค์ประกอบได้ง่ายโดยไม่ต้องรับภาระในการแยกวิเคราะห์กระแสข้อความ เอกสารนี้เขียนขึ้นเพื่อเป็นอิสระจากการใช้งานเฉพาะของเชลล์ชุดของยูทิลิตี้หรือเทคโนโลยีการสร้างคำสั่ง อย่างไรก็ตามภาคผนวก J - การใช้ Windows Powershell เพื่อใช้มาตรฐานบรรทัดคำสั่งของ Microsoft แสดงให้เห็นว่าการใช้ Windows PowerShell จะช่วยให้การดำเนินการตามหลักเกณฑ์เหล่านี้มากมายได้ฟรี


9
Microsoft มีความช่วยเหลือบรรทัดคำสั่งที่แย่มากสำหรับยูทิลิตี้เกือบทุกอย่างน่ากลัวจนทำให้ Powershell ซ่อนบรรทัดคำสั่ง "ปกติ" ไว้ใต้พรม
Camilo Martin

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

2
ตกลงนั่นไม่ใช่เหตุผลที่คำตอบนี้ควรถูกลดระดับลง หาก downvoted น่าจะเป็นเพราะก) ส่วนของเอกสารที่อ้างถึงนั้นไม่ตอบคำถามในมือและข) เอกสารที่เชื่อมโยงกับดูเหมือนจะไม่เกี่ยวข้องกัน คำถามถามว่ามี "มาตรฐานข้อความช่วยเหลือ" ที่เน้นหนักไปที่ไวยากรณ์ที่ใช้ในการสื่อสารการใช้งานคำสั่ง synopses หรือไม่ เอกสารไม่ได้บอกเช่นไวยากรณ์ แต่วิธีการสร้างแอพพลิเคบรรทัดคำสั่งที่ดีโดยทั่วไปในระบบนิเวศ PowerShell (เช่นต้องสนับสนุน-?, -Help, -Versionฯลฯ ) คำตอบของ IMO Steely Wing ใกล้เคียงกับเครื่องหมาย
มาร์กกรัม

9

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


0

ใช่คุณอยู่ในเส้นทางที่ถูกต้อง

ใช่วงเล็บเหลี่ยมเป็นตัวบ่งชี้ปกติสำหรับรายการเพิ่มเติม

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

เทรนด์ที่ใหม่กว่า (อาจมีข้อกำหนด POSIX ที่กล่าวถึงเรื่องนี้) คือการกำจัดระบบ man page สำหรับเอกสารประกอบและรวมถึงข้อมูลทั้งหมดที่จะอยู่ใน manpage โดยเป็นส่วนหนึ่งของprogram --helpผลลัพธ์ ส่วนเสริมนี้จะรวมคำอธิบายที่ยาวขึ้นแนวคิดที่อธิบายตัวอย่างการใช้งานข้อ จำกัด และข้อบกพร่องที่รู้จักวิธีการรายงานข้อบกพร่องและอาจเป็นส่วน 'ดูด้วย' สำหรับคำสั่งที่เกี่ยวข้อง

ฉันหวังว่านี่จะช่วยได้.


4
ไม่ไม่ไม่. คำสั่งควรมี manpage ซึ่งรวมถึงการอ้างอิงโดยละเอียดอย่างเต็มรูปแบบของการใช้งานและ-h|--helpควรเป็นเพียงการอ้างอิงโดยสรุป คุณอาจรวมถึงเอกสารที่ครอบคลุมมากขึ้น (บทช่วยสอน ฯลฯ ... ) ใน HTML หรือหน้าข้อมูล แต่ manpage ควรจะอยู่ที่นั่น!
ninjalj

ฉันเห็นด้วยกับคุณ @ninjalj แต่ในขณะที่ฉันพูดว่า "เทรนด์ใหม่" และโดยที่ฉันหมายถึงระบบทั้งสองที่ฉันใช้ UWin และ MinGW ทั้งสองได้ไปพร้อมกับเอกสารที่ฝังตัว ฉันคิดว่าเอกสารฝังตัวอยู่ในที่ของมันโดยเฉพาะสคริปต์ระดับผู้ใช้ขนาดเล็กเช่นเดียวกับที่ผู้ใช้รายนี้เสนอ เขาควรจะต้องเรียนรู้ nroff และ. info? แต่ดีที่จะทำให้เราซื่อสัตย์ขอบคุณสำหรับความคิดเห็นของคุณและขอให้ทุกคนโชคดี
shellter

ส่วนตัวเมื่อฉันพิมพ์someCommand --helpที่เปลือกของฉันทั้งหมดที่ฉันจำเป็นต้องเป็นคำเตือนเล็ก ๆ ของคำสั่งที่ถูกต้องข้อโต้แย้งไปในไม่ได้เป็นแนวยักษ์ของข้อความที่เติมหน้าจอที่ต้องฉันท่อมันลงไปlessเพียงเพื่อดูทั้งหมดของมัน manpage ควรเป็นตำแหน่งที่คุณใส่คำอธิบายแบบละเอียดไม่ใช่ข้อความช่วยเหลือ
AJMansfield

ตามที่ผู้ทำ docopt ในการประชุมของเขาเขากล่าวว่า POSIX มีบรรทัดฐานสำหรับเรื่องนี้
v.oddou

0

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


เกี่ยวกับtar... ถ้ามีใครจะทำไม่ทุกอย่างพระเจ้าสาธารณูปโภคเช่น tar โปรดให้สั้นสวิทช์ที่น่าจดจำและมีส่วน "การใช้งานตัวอย่างเช่น" --helpใน 90% ของเวลาที่ผมดูคำแนะนำ tar tar.gzของมันสำหรับการสกัดที่เรียบง่าย
Camilo Martin

' ไม่มีความต้องการที่แท้จริงสำหรับ "ความช่วยเหลือมาตรฐาน" 'มีความต้องการที่แท้จริง "สำหรับสิ่งที่เราใช้ส่วนใหญ่หรือไม่? หรือพวกเขาอยู่ที่นั่นเพื่อทำให้ชีวิตของเราง่ายขึ้นมาก? การมีวิธีที่ตกลงกันเพื่อแสดงตัวเลือกนั้นมีประโยชน์ไม่เพียง แต่สำหรับผู้อ่านเท่านั้น แต่ยังมีประโยชน์สำหรับการสร้างผู้ใช้เช่น GUIs ที่สามารถควบคุมยูทิลิตีบรรทัดคำสั่งโดยพลการและต้องการให้การควบคุมสำหรับการตั้งค่าตัวเลือก อาจมีประโยชน์มากกว่าที่ฉันยังไม่ได้พิจารณา
underscore_d
โดยการใช้ไซต์ของเรา หมายความว่าคุณได้อ่านและทำความเข้าใจนโยบายคุกกี้และนโยบายความเป็นส่วนตัวของเราแล้ว
Licensed under cc by-sa 3.0 with attribution required.