Komut satırı / kabuk yardım metni için “standart” bir format var mı?

Değilse, fiili bir standart var mı? Temelde böyle bir komut satırı yardım metni yazıyorum:

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

Bunu temelde sadece çeşitli araçların yardım metnini okuduğumdan yaptım, ama bir rehberler listesi var mı? Örneğin, köşeli parantez veya parantez mi kullanırım? Boşluk nasıl kullanılır? Ya argüman bir liste ise? Teşekkürler!

Genellikle yardım çıktılarınız şunları içermelidir:

• Uygulamanın ne yaptığının açıklaması
• Kullanım söz dizimi:
  • [options]Seçeneklerin nereye gittiğini belirtmek için kullanır
  • arg_name gerekli, tekil bir argüman için
  • [arg_name] isteğe bağlı, tekil bir argüman için
  • arg_name... gerekli olabilecek bir argüman için çok fazla olabilir (bu nadirdir)
  • [arg_name...] herhangi bir sayı verilebilecek bir arg için
  • arg_namebunun açıklayıcı, kısa bir isim, altta yılan şeklinde olması gerektiğini unutmayın
• Her biri güzel biçimlendirilmiş seçenekler listesi:
  • kısa bir açıklamaya sahip olmak
  • Varsa varsayılan değeri gösteren
  • geçerliyse olası değerleri gösteren
  • Bir seçenek kısa bir formu (ör. -l) Veya uzun bir formu (ör. --list) Kabul edebiliyorsa, açıklamaları aynı olacağından bunları aynı satıra dahil edin.
• Komut satırı bağımsız değişkenlerinin kaynağı olabilecek yapılandırma dosyalarının veya ortam değişkenlerinin konumunun kısa göstergesi, ör. GREP_OPTS
• Bir kılavuz sayfası varsa, böyle belirtin, aksi takdirde daha ayrıntılı yardımın nerede bulunabileceğinin kısa bir göstergesi

'S iyi formu hem kabul etmek olduğunu ileri Not -hve --helpbu mesajı tetiklemek için ve bu mesajı göstermelidir ki eğer komut satırı sözdizimi, örneğin atlar gerekli bir argüman kadar kullanıcı messes.

Dokümana bir göz atın . Komut satırı bağımsız değişkenlerini belgelemek (ve otomatik olarak ayrıştırmak) için resmi bir standarttır.

Örneğin...

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

Komut satırı kullanımı için standart bir sözdizimi olduğunu düşünüyorum, ancak çoğu bu kural kullanın:

Microsoft Komut Satırı Sözdizimi , IBM benzer Komut Satırı Sözdizimine sahiptir

• Text without brackets or braces

  Gösterildiği gibi yazmanız gereken öğeler
  
  

• <Text inside angle brackets>

  Değer vermeniz gereken yer tutucu
  
  

• [Text inside square brackets]

  Isteğe bağlı öğeler
  
  

• {Text inside braces}

  Gerekli öğeler kümesi; birini seç
  
  

• Dikey çubuk {a|b}

  Karşılıklı münhasır ürünler için ayırıcı; birini seç
  
  

• eksilti <file> …

  Tekrarlanabilen öğeler
  
  

Çoğunlukla POSIX uyumlu bir işletim sistemi olan Linux çalıştırıyoruz. POSIX standartları şöyle olmalıdır: Yardımcı Program Bağımsız Değişken Sözdizimi .

• Bir seçenek bu gibi tek alfanümerik karakter ve ardından bir tire şöyledir: -o.
• Bir seçenek bir argüman gerektirebilir (seçenekten hemen sonra görünmelidir); örneğin, -o argumentveya -oargument.
• Bağımsız değişken gerektirmeyen seçenekler tire işaretinden sonra gruplandırılabilir, bu nedenle örneğin, -lsteşdeğerdir -t -l -s.
• Seçenekler herhangi bir sırada görünebilir; böylece -lsteşittir -tls.
• Seçenekler birden çok kez görünebilir.
• Seçenekler diğer seçenek olmayan bağımsız değişkenlerden önce gelir: -lstseçenek olmayan.
• --Argüman seçenekleri sonlandırır.
• Bu -seçenek tipik olarak standart giriş akışlarından birini temsil etmek için kullanılır.

Microsoft'un kendi Komut Satırı Standart belirtimi vardır :

Bu belge, komut satırı yardımcı programlarının geliştiricilerine odaklanmıştır. Toplu olarak, amacımız tutarlı, oluşturulabilir bir komut satırı kullanıcı deneyimi sunmaktır. Kullanıcının çekirdek kavramları (sözdizimi, adlandırma, davranışlar, vb.) Öğrenmesini ve daha sonra bu bilgiyi büyük bir komut kümesiyle çalışmaya dönüştürmesini sağlar. Bu komutlar, çıktı metninin akışlarını ayrıştırma yükü olmadan kolay kompozisyon sağlamak için standartlaştırılmış veri akışlarını standartlaştırılmış bir formatta çıktılayabilmelidir. Bu belge, bir kabuğun, yardımcı program grubunun veya komut oluşturma teknolojilerinin herhangi bir özel uygulamasından bağımsız olarak yazılmıştır; ancak, Ek J - Microsoft Komut Satırı Standardını uygulamak için Windows Powershell kullanma, Windows PowerShell kullanımının bu yönergelerin çoğunun nasıl ücretsiz olarak uygulanacağını gösterir.

GNU Kodlama Standardı bu gibi şeyler için iyi bir referanstır. Bu bölüm , çıktılarıyla ilgilidir --help. Bu durumda çok spesifik değildir. Kısa ve uzun seçenekleri ve kısa bir açıklamayı gösteren bir tablo yazdırırken büyük olasılıkla yanlış gidemezsiniz. Okunabilirlik için tüm argümanlar arasındaki boşluğu almaya çalışın. Muhtemelen daha ayrıntılı bir açıklama sağlamak için aracınız için bir mansayfa (ve muhtemelen bir infokılavuz) sağlamak istersiniz .

evet, doğru yoldasın.

evet, köşeli parantez isteğe bağlı öğeler için her zamanki göstergedir.

Tipik olarak, çizdiğiniz gibi, üstte bir komut satırı özeti, ardından ayrıntılar, her seçenek için örneklerle birlikte bulunur. (Örneğin, her seçenek açıklaması arasındaki satırları gösterir, ancak bunun bir düzenleme sorunu olduğunu ve gerçek programınızın aralarında boş satırlar olmadan girintili seçenek listeleri çıkardığını varsayıyorum. Bu, her durumda takip edilecek standart olacaktır.)

Daha yeni bir eğilim, (belki de buna değinen bir POSIX belirtimi var mı?), Man sayfa sisteminin dokümantasyon için ortadan kaldırılması ve program --helpçıktının bir parçası olarak bir sayfada olacak tüm bilgileri içermesidir . Bu ekstra, daha uzun açıklamalar, açıklanan kavramlar, kullanım örnekleri, bilinen sınırlamalar ve hatalar, bir hatanın nasıl rapor edileceği ve muhtemelen ilgili komutlar için 'ayrıca bakınız' bölümünü içerecektir.

Umarım bu yardımcı olur.

Örnek olarak katran gibi resmi projeleri takip ederdim. Bence msg. olabildiğince basit ve açıklayıcı olmalıdır. Kullanım örnekleri de iyidir. "Standart yardıma" gerek yoktur.