Apakah ada format "standar" untuk teks bantuan baris perintah / shell?

239

Jika tidak, apakah ada standar de facto? Pada dasarnya saya sedang menulis teks bantuan baris perintah seperti:

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

Saya membuatnya dari dasarnya hanya membaca teks bantuan dari berbagai alat, tetapi apakah ada daftar pedoman atau sesuatu? Misalnya, apakah saya menggunakan tanda kurung siku atau tanda kurung? Bagaimana cara menggunakan spasi? Bagaimana jika argumennya adalah daftar? Terima kasih!

shell command-line command-line-arguments Yifan
sumber
8
Saya pikir GNU memiliki beberapa petunjuk. Saya akan melihat apa yang dilakukan sebagian besar utilitas GNU.
Basile Starynkevitch
1
@DanielPryden Saya pikir jawaban dalam pertanyaan itu agak menyesatkan. Ini memberi tautan yang menjelaskan saklar apa yang harus diterima dan bukan bagaimana --helptampilan seharusnya. Namun kedua pertanyaan tersebut merupakan kandidat yang baik untuk bergabung.
sore
@ pmr: Saya setuju - mungkin seorang mod dapat menggabungkan pertanyaan untuk kita.
Daniel Pryden
2
Saya akan melihat apa yang dilakukan sebagian besar utilitas GNU, dan melakukannya dengan cara lain.
Yakov Galka

Jawaban:

160

Biasanya, hasil bantuan Anda harus mencakup:

  • Deskripsi tentang apa yang dilakukan aplikasi
  • Sintaks penggunaan, yang:
    • Penggunaan [options]untuk menunjukkan ke mana opsi pergi
    • arg_name untuk argumen tunggal yang diperlukan
    • [arg_name] untuk opsional, argumen tunggal
    • arg_name... untuk arg yang diperlukan yang mungkin ada banyak (ini jarang terjadi)
    • [arg_name...] untuk argumen yang nomornya dapat diberikan
    • perhatikan bahwa arg_nameharus berupa deskriptif, nama pendek, dalam huruf kecil, kasus ular
  • Daftar opsi yang diformat dengan baik, masing-masing:
    • memiliki deskripsi singkat
    • menunjukkan nilai default, jika ada
    • menunjukkan nilai yang mungkin, jika itu berlaku
    • Perhatikan bahwa jika suatu opsi dapat menerima formulir pendek (mis. -l) Atau formulir panjang (mis. --list), Sertakan bersama-sama pada baris yang sama, karena deskripsinya akan sama
  • Indikator singkat dari lokasi file konfigurasi atau variabel lingkungan yang mungkin menjadi sumber argumen baris perintah, misalnya GREP_OPTS
  • Jika ada halaman manual, sebutkan seperti itu, jika tidak, indikator singkat di mana bantuan yang lebih rinci dapat ditemukan

Perhatikan lebih lanjut bahwa itu adalah bentuk yang baik untuk menerima keduanya -hdan --helpmemicu pesan ini dan bahwa Anda harus menunjukkan pesan ini jika pengguna mengacaukan sintaks baris perintah, misalnya menghilangkan argumen yang diperlukan.

davetron5000
sumber
3
Bagaimana jika saya memiliki dua bentuk arg yang diperlukan? Misalnya cara yang lebih standar mengatakan: usage: move (+|-)pixelsyaitu ketika salah satu + atau - adalah wajib ? (Saya tahu saya dapat memiliki 2 baris penggunaan tapi saya suka ide menggandakannya dengan setiap argumen baru.) Dapatkah Anda memikirkan contoh dari alat standar?
Alois Mahdal
4
@AloisMahdal Saya biasanya melihat {a|b|c|...}di bagian bantuan untuk SysV Init script layanan / pemula, yang membutuhkan argumen tunggal yang merupakan salah satu dari a, b, c, dll Sebagai contoh, service sddmtanpa argumen pada sistem saya mencetak Usage: /etc/init.d/sddm {start|stop|status|restart|try-restart|force-reload}. Jadi kebanyakan orang mungkin akan mengerti usage: move {+|-}pixels}, terutama jika diberikan contoh:example: move +5
Braden Best
@JorgeBucaran mereka seharusnya tidak keluar dengan status 0 bukan? Saya percaya keluar dengan status 2 adalah standar untuk perintah shell yang tidak valid.
inavda
91

Lihatlah docopt . Ini adalah standar formal untuk mendokumentasikan (dan secara otomatis parsing) argumen baris perintah.

Sebagai contoh...

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>...
Lily Finley
sumber
46

Saya pikir tidak ada sintaks standar untuk penggunaan baris perintah, tetapi kebanyakan menggunakan konvensi ini:

Microsoft Command-Line Sintaks , IBM memiliki sejenis Command-Line Sintaks

  • Text without brackets or braces

    Item yang harus Anda ketik seperti yang ditunjukkan

  • <Text inside angle brackets>

    Placeholder yang harus Anda berikan nilainya

  • [Text inside square brackets]

    Item opsional

  • {Text inside braces}

    Set item yang dibutuhkan; Pilih satu

  • Bilah vertikal {a|b}

    Pemisah untuk barang-barang yang saling eksklusif; Pilih satu

  • Elipsis <file> …

    Item yang bisa diulang

Steely Wing
sumber
16

Kami menjalankan Linux, OS yang sebagian besar kompatibel dengan POSIX. Standar POSIX seharusnya: Utility Argument Syntax .

  • Sebuah pilihan adalah tanda hubung diikuti oleh karakter alfanumerik tunggal, seperti ini: -o.
  • Suatu opsi mungkin memerlukan argumen (yang harus segera muncul setelah opsi); misalnya, -o argumentatau -oargument.
  • Opsi yang tidak memerlukan argumen dapat dikelompokkan setelah tanda hubung, jadi, misalnya, -lstsetara dengan -t -l -s.
  • Opsi dapat muncul dalam urutan apa pun; dengan demikian -lstsetara dengan -tls.
  • Opsi dapat muncul beberapa kali.
  • Opsi mendahului argumen nonoption lainnya: -lstnonoption.
  • The --argumen berakhir pilihan.
  • The -opsi biasanya digunakan untuk mewakili salah satu aliran input standar.
MotherDawg
sumber
2
Adalah umum bahwa penggunaan dalam GNU / Linux tidak mengikuti persis standar ini. Run misalnya man aptitudeyang output ini (antara lain): aptitude [<options>...] {add-user-tag | remove-user-tag} <tag> <packages>.... Ini berisi {dan} untuk mengikat perintah wajib alternatif. Saya pikir (dan) dapat digunakan untuk hal yang sama seperti yang digunakan dalam docopt .
jarno
Jawaban ini akan sangat kurang membantu jika tautan yang disediakan rusak. Mungkin Anda bisa meringkas bagian-bagian penting dari dokumen yang ditautkan dalam jawaban itu sendiri?
domsson
11

Microsoft memiliki spesifikasi Command Line Standard mereka sendiri :

Dokumen ini difokuskan pada pengembang utilitas baris perintah. Secara kolektif, tujuan kami adalah menghadirkan pengalaman pengguna baris perintah yang konsisten dan dapat disusun. Pencapaian yang memungkinkan pengguna untuk mempelajari serangkaian konsep inti (sintaksis, penamaan, perilaku, dll) dan kemudian dapat menerjemahkan pengetahuan itu menjadi bekerja dengan seperangkat perintah besar. Perintah-perintah tersebut harus dapat mengeluarkan aliran data terstandarisasi dalam format terstandarisasi untuk memungkinkan komposisi yang mudah tanpa beban mem-parsing aliran teks keluaran. Dokumen ini ditulis untuk tidak tergantung pada implementasi spesifik dari shell, seperangkat utilitas atau teknologi pembuatan perintah; namun, Lampiran J - Menggunakan Windows Powershell untuk mengimplementasikan Microsoft Command Line Standard menunjukkan bagaimana menggunakan Windows PowerShell akan memberikan implementasi banyak panduan ini secara gratis.

Jared Harley
sumber
9
Microsoft memiliki bantuan baris perintah yang mengerikan untuk sebagian besar utilitas, semuanya begitu mengerikan sehingga mereka membuat Powershell untuk menyembunyikan baris perintah "biasa" di bawah karpet.
Camilo Martin
25
Saya tidak berpikir jawabannya harus diturunkan hanya karena memiliki referensi ke standar Microsoft. "Semuanya begitu mengerikan" adalah opini subjektif. Dengan cara yang sama dapat dikatakan bahwa baris perintah UNIX mengerikan dan jelek, tetapi mari kita jauhkan pendapat tersebut dan jadilah profesional.
Dima
2
Setuju, bukan karena itu jawaban ini harus diturunkan. Jika diturunkan, itu karena a) bagian dari dokumen yang dikutip tidak menjawab pertanyaan, dan b) dokumen yang ditautkan tampaknya tidak relevan. Pertanyaannya menanyakan apakah ada standar untuk "teks bantu" dengan penekanan besar pada sintaks yang digunakan untuk mengkomunikasikan synopses penggunaan perintah. Dokumen tidak mengajukan sintaks seperti melainkan bagaimana membangun aplikasi baris perintah baik secara umum dalam ekosistem PowerShell (misalnya harus mendukung -?, -Help, -Version, dll). Jawaban IMO Steely Wing lebih dekat dengan sasaran.
Mark G.
9

Standar Pengkodean GNU adalah referensi yang bagus untuk hal-hal seperti ini. Bagian ini berkaitan dengan output dari --help. Dalam hal ini tidak terlalu spesifik. Anda mungkin tidak dapat salah dengan mencetak tabel yang menunjukkan opsi pendek dan panjang dan deskripsi ringkas. Cobalah untuk mengatur jarak antara semua argumen agar mudah dibaca. Anda mungkin ingin memberikan manhalaman (dan mungkin infomanual) untuk alat Anda untuk memberikan penjelasan yang lebih rumit.

sore
sumber
0

ya, Anda berada di jalur yang benar.

ya, tanda kurung siku adalah indikator umum untuk item opsional.

Biasanya, seperti yang telah Anda sketsa, ada ringkasan commandline di bagian atas, diikuti oleh detail, idealnya dengan sampel untuk setiap opsi. (Contoh Anda menunjukkan baris di antara setiap deskripsi opsi, tapi saya berasumsi itu adalah masalah pengeditan, dan bahwa program Anda yang sebenarnya menampilkan daftar opsi indentasi tanpa ada baris kosong di antaranya. Ini akan menjadi standar untuk diikuti dalam hal apa pun.)

Tren yang lebih baru, (mungkin ada spesifikasi POSIX yang membahas hal ini?), Adalah penghapusan sistem halaman manual untuk dokumentasi, dan termasuk semua informasi yang akan ada di halaman manual sebagai bagian dari program --helpoutput. Tambahan ini akan mencakup deskripsi yang lebih panjang, konsep yang dijelaskan, sampel penggunaan, batasan dan bug yang diketahui, cara melaporkan bug, dan mungkin bagian 'lihat juga' untuk perintah terkait.

Saya harap ini membantu.

kerang
sumber
4
Tidak tidak Tidak. Perintah tersebut harus memiliki halaman manual yang mencakup referensi lengkap tentang penggunaan, dan -h|--helpharus hanya referensi singkat. Anda juga dapat memasukkan dokumentasi yang lebih komprehensif (tutorial, dll ...) di halaman HTML atau info. Tapi manualnya harus ada di sana!
ninjalj
Saya setuju dengan Anda, @ninjalj, tetapi seperti yang saya katakan, "Tren yang lebih baru", dan maksud saya kedua sistem yang saya gunakan, UWin dan MinGW keduanya telah menggunakan dokumentasi yang disematkan. Saya pikir tertanam dokumen memiliki tempat itu, terutama untuk skrip tingkat pengguna kecil, seperti apa yang diusulkan pengguna ini. Haruskah dia belajar nroff dan .info? Tapi bagus untuk menjaga kami jujur, terima kasih atas komentar Anda dan semoga sukses untuk semua.
shellter
Secara pribadi, ketika saya mengetik someCommand --helpdi shell saya, semua yang saya butuhkan adalah pengingat kecil dari urutan tepat argumen masuk, bukan petak besar teks yang mengisi layar, mengharuskan saya menyalurkannya ke lesshanya untuk melihat semua itu. Halaman manual harus berada di tempat Anda meletakkan deskripsi panjang yang terperinci, bukan teks bantuan.
AJMansfield
menurut pembuat docopt dalam konferensinya ia menyebutkan POSIX memiliki norma untuk ini.
v.oddou
0

Saya akan mengikuti proyek resmi seperti tar sebagai contoh. Menurut pendapat saya, bantuan. harus sesederhana dan sejelas mungkin. Contoh penggunaannya juga bagus. Tidak ada kebutuhan nyata untuk "bantuan standar".

rluks
sumber
Mengenai tar... jika seseorang akan membuat utilitas utilitas all-do seperti tar, harap membuat sakelar pendek mudah diingat, dan sertakan bagian "contoh penggunaan" di --help. 90% dari waktu saya melihat instruksi tar itu untuk mengekstraksi yang sederhana tar.gz.
Camilo Martin
' Tidak ada kebutuhan nyata untuk "bantuan standar". 'Apakah ada "kebutuhan nyata" untuk sebagian besar hal yang kita gunakan? Atau apakah mereka ada di sana untuk membuat hidup kita lebih mudah? Memiliki cara yang disepakati untuk mewakili opsi berguna tidak hanya untuk pembaca, tetapi juga misalnya orang yang berguna akan membangun misalnya GUI yang dapat mengontrol utilitas baris perintah sewenang-wenang dan ingin memberikan kontrol untuk mengatur opsi mereka. Mungkin ada kegunaan yang lebih baik yang belum saya pertimbangkan.
underscore_d