Czy istnieje „standardowy” format tekstu pomocy wiersza poleceń / powłoki?

Jeśli nie, czy istnieje de facto standard? Zasadniczo piszę tekst pomocy w wierszu polecenia:

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

Zrobiłem to po prostu po przeczytaniu tekstu pomocy różnych narzędzi, ale czy istnieje lista wskazówek czy coś takiego? Na przykład, czy używam nawiasów kwadratowych lub nawiasów? Jak korzystać z odstępów? Co jeśli argument jest listą? Dzięki!

Zazwyczaj dane wyjściowe pomocy powinny obejmować:

• Opis działania aplikacji
• Składnia użycia, która:
  • Służy [options]do wskazania, dokąd idą opcje
  • arg_name dla wymaganego, pojedynczego arg
  • [arg_name] dla opcjonalnego pojedynczego arg
  • arg_name... dla wymaganego argumentu, którego może być wiele (jest to rzadkie)
  • [arg_name...] dla argumentu, dla którego można podać dowolną liczbę
  • zwróć uwagę, że arg_namepowinna to być opisowa, krótka nazwa, w dolnej, wężowej formie
• Ładnie sformatowana lista opcji, każda:
  • mając krótki opis
  • pokazując wartość domyślną, jeśli taka istnieje
  • pokazując możliwe wartości, jeśli to dotyczy
  • Pamiętaj, że jeśli opcja może zaakceptować krótki formularz (np. -l) Lub długi formularz (np. --list), Dołącz je razem w tym samym wierszu, ponieważ ich opisy będą takie same
• Krótki wskaźnik lokalizacji plików konfiguracyjnych lub zmiennych środowiskowych, które mogą być źródłem argumentów wiersza poleceń, np GREP_OPTS
• Jeśli jest strona podręcznika, wskaż jako taki, w przeciwnym razie krótki wskaźnik, gdzie można znaleźć bardziej szczegółową pomoc

Zwróć ponadto uwagę, że dobrą formą jest zaakceptowanie obu -hi --helpwyzwolenie tego komunikatu oraz że powinieneś pokazać ten komunikat, jeśli użytkownik zepsuje składnię wiersza poleceń, np. Pominie wymagany argument.

Spójrz na docopt . Jest to formalny standard dokumentowania (i automatycznego parsowania) argumentów wiersza poleceń.

Na przykład...

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

Myślę, że nie ma standardowej składni dla użycia wiersza poleceń, ale większość korzysta z tej konwencji:

Składnia wiersza polecenia Microsoft , IBM ma podobną składnię wiersza polecenia

• Text without brackets or braces

  Elementy, które musisz wpisać, jak pokazano
  
  

• <Text inside angle brackets>

  Symbol zastępczy, dla którego musisz podać wartość
  
  

• [Text inside square brackets]

  Przedmioty opcjonalne
  
  

• {Text inside braces}

  Zestaw wymaganych przedmiotów; Wybierz jeden
  
  

• Pionowy pasek {a|b}

  Separator dla przedmiotów wykluczających się wzajemnie; Wybierz jeden
  
  

• Elipsa <file> …

  Elementy, które można powtórzyć
  
  

Używamy Linuksa, systemu operacyjnego w większości zgodnego z POSIX. Standardy POSIX powinny być: Składnia argumentów narzędzia .

• Opcja jest myślnik, a następnie jednego znaku alfanumerycznego, tak: -o.
• Opcja może wymagać argumentu (który musi pojawić się natychmiast po opcji); na przykład -o argumentlub -oargument.
• Opcje, które nie wymagają argumentów, można pogrupować po łączniku, więc na przykład -lstjest równoważne z -t -l -s.
• Opcje mogą pojawiać się w dowolnej kolejności; -lstjest więc równoważne z -tls.
• Opcje mogą pojawić się wiele razy.
• Opcje poprzedzają inne argumenty -lstbraku opcji : brak opcji.
• --Argumentem kończy opcje.
• Ta -opcja jest zwykle używana do reprezentowania jednego ze standardowych strumieni wejściowych.

Microsoft ma własną specyfikację wiersza polecenia :

Ten dokument jest skierowany do twórców narzędzi wiersza poleceń. Podsumowując, naszym celem jest przedstawienie spójnego, składającego się doświadczenia użytkownika z linii poleceń. Osiągnięcie tego pozwala użytkownikowi nauczyć się podstawowego zestawu pojęć (składnia, nazewnictwo, zachowania itp.), A następnie móc przełożyć tę wiedzę na pracę z dużym zestawem poleceń. Polecenia te powinny być w stanie wyprowadzać znormalizowane strumienie danych w znormalizowanym formacie, aby umożliwić łatwą kompozycję bez konieczności analizowania strumieni tekstu wyjściowego. Ten dokument został napisany jako niezależny od jakiejkolwiek konkretnej implementacji powłoki, zestawu narzędzi lub technologii tworzenia poleceń; jednak Dodatek J - Używanie Windows Powershell do implementacji Microsoft Command Line Standard pokazuje, w jaki sposób użycie Windows PowerShell zapewni wdrożenie wielu z tych wytycznych za darmo.

Standard kodowania GNU jest dobrym odniesieniem do takich rzeczy. Ta sekcja dotyczy wyników --help. W tym przypadku nie jest bardzo konkretny. Prawdopodobnie nie możesz się pomylić z wydrukowaniem tabeli przedstawiającej krótkie i długie opcje oraz zwięzły opis. Spróbuj uzyskać odpowiedni odstęp między wszystkimi argumentami, aby zapewnić czytelność. Prawdopodobnie chcesz podać manstronę (i ewentualnie infoinstrukcję) swojego narzędzia, aby uzyskać bardziej szczegółowe wyjaśnienia.

tak, jesteś na dobrej drodze.

tak, nawiasy kwadratowe są zwykłym wskaźnikiem dla przedmiotów opcjonalnych.

Zazwyczaj, jak naszkicowałeś, u góry znajduje się podsumowanie linii poleceń, a następnie szczegóły, najlepiej z próbkami dla każdej opcji. (Twój przykład pokazuje linie pomiędzy opisami każdej opcji, ale zakładam, że jest to problem z edycją i że twój prawdziwy program wyświetla wcięte listy opcji bez pustych linii pomiędzy nimi. W każdym razie byłby to standard.)

Nowszym trendem (być może istnieje specyfikacja POSIX, która rozwiązuje ten problem?), Jest wyeliminowanie systemu stron podręcznika dla dokumentacji i uwzględnienie wszystkich informacji, które byłyby na stronie podręcznika jako część program --helpwyniku. Dodatek ten będzie zawierał dłuższe opisy, wyjaśnione pojęcia, przykłady użycia, znane ograniczenia i błędy, jak zgłosić błąd i ewentualnie sekcję „zobacz także” dotyczącą powiązanych poleceń.

Mam nadzieję, że to pomoże.

Jako przykład podążałbym za oficjalnymi projektami takimi jak tar. Moim zdaniem pomoc msg. musi być prosty i opisowy, jak to możliwe. Przykłady użycia są również dobre. Nie ma potrzeby „standardowej pomocy”.