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

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!

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.

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>...

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
  
  

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.

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.

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.

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.

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".