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

Spójrz na docopt . Jest formalnym standardem dokumentowania (i automatycznego parsowania) argumentów linii 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 użycia wiersza poleceń, ale większość używa tej konwencji:

Microsoft składnia wiersza poleceń , IBM ma podobną składnię wiersza poleceń

• Text without brackets or braces

  Elementy, które musisz wpisać jak pokazano
  
  

• <Text inside angle brackets>

  Placeholder, dla którego musisz podać wartość
  
  

• [Text inside square brackets]

  Opcjonalnie pozycje
  
  

• {Text inside braces}

  Zestaw wymaganych elementów; wybierz jeden
  
  

• Pionowy pasek {a|b}

  Separator dla wzajemnie wykluczających się elementów; wybierz jeden
  
  

• Elipsa <file> …

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

Używamy Linuksa, systemu operacyjnego w większości zgodnego z POSIX. Standard POSIX powinien być: składnia argumentu użytkowego .

• opcja jest myślnikiem, po którym następuje pojedynczy znak alfanumeryczny, Tak: -o.
• opcja może wymagać argumentu (który musi się pojawić bezpośrednio po opcji); na przykład -o argument lub -oargument.
• opcje, które nie wymagają argumentów, można pogrupować po myślniku, więc na przykład -lst jest równoważne -t -l -s.
• opcje mogą pojawiać się w dowolnej kolejności; zatem -lst jest równoważne -tls.
• opcje mogą pojawić się wiele razy.
• opcje poprzedzają inne nieopcje arguments: -lst nonoption.
• argument -- kończy opcje.
• opcja - jest zwykle używana do reprezentowania jednego ze standardowych wejść strumienie.

Microsoft ma własną standardową specyfikację linii poleceń :

Ten dokument jest skierowany do twórców narzędzi wiersza poleceń. Naszym wspólnym celem jest przedstawienie spójnego, składowego interfejsu użytkownika wiersza poleceń. Osiągnięcie tego pozwala użytkownikowi nauczyć się podstawowego zestawu pojęć (składnia, nazewnictwo, zachowania itp.), a następnie być w stanie przełożyć tę wiedzę na pracę z dużym zestawem poleceń. Polecenia te powinny być w stanie generować standardowe strumienie danych w znormalizowanym formacie umożliwiającym łatwą kompozycję bez obciążania strumieni tekstu wyjściowego. Dokument ten jest napisany jako niezależny od konkretnej implementacji powłoki, zestawu narzędzi lub technologii tworzenia poleceń; jednak dodatek J-używanie Windows Powershell do implementacji standardu wiersza poleceń Microsoft pokazuje, w jaki sposób korzystanie z Windows PowerShell zapewni implementację wielu z tych wytycznych za darmo.

Standard kodowania GNU jest dobrym odniesieniem do takich rzeczy. Ta sekcja dotyczy wyjścia --help. W tym przypadku nie jest to bardzo specyficzne. Prawdopodobnie nie możesz się pomylić z wydrukowaniem tabeli pokazującej krótkie i długie opcje oraz zwięzły opis. Spróbuj uzyskać odstępy między wszystkimi argumentami w odpowiedni sposób dla czytelności. Prawdopodobnie chcesz podać stronę man (i ewentualnie instrukcję info) dla swojego narzędzia, aby zapewnić bardziej rozbudowane Wyjaśnienie.

Tak, jesteś na dobrej drodze.

Tak, nawiasy kwadratowe są zwykle wskaźnikiem dla elementów opcjonalnych.

Zazwyczaj, jak już naszkicowałeś, na górze znajduje się podsumowanie wiersza poleceń, a następnie szczegóły, najlepiej z przykładami dla każdej opcji. (Twój przykład pokazuje linie pomiędzy każdym opisem 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 między nimi. To byłby standard do naśladowania w w każdym razie.)

Nowszy trend, (może istnieje Specyfikacja POSIX, która rozwiązuje ten problem?), eliminuje System stron podręcznika dla dokumentacji i zawiera wszystkie informacje, które mogłyby znaleźć się na stronie podręcznika jako część wyjścia program --help. Ten dodatek będzie zawierał dłuższe opisy, objaśnione koncepcje, przykłady użycia, znane ograniczenia i błędy, sposób zgłaszania błędu i ewentualnie sekcję "Zobacz także" dla powiązanych poleceń.

Jako przykład posłużyłbym się oficjalnymi projektami, takimi jak tar. Moim zdaniem pomóc msg. musi być prosty i opisowy, jak to możliwe. Przykłady użycia są również dobre. Nie ma realnej potrzeby "standardowej pomocy".