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

239

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!

shell command-line command-line-arguments Yifan
źródło
8
Myślę, że GNU ma pewne wskazówki. Chciałbym spojrzeć na to, co robi większość narzędzi GNU.
Basile Starynkevitch,
1
@DanielPryden Myślę, że odpowiedź na to pytanie jest nieco myląca. Daje linki, które wyjaśniają, które przełączniki powinny być akceptowane, a nie jak --helppowinny wyglądać dane wyjściowe . Ale oba pytania są dobrym kandydatem do fuzji.
pmr
@pmr: Zgadzam się - być może mod może scalić za nas pytania.
Daniel Pryden
2
Spojrzałbym na to, co robi większość narzędzi GNU, i zrobiłbym to w drugą stronę.
Jakow Galka

Odpowiedzi:

160

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.

davetron5000
źródło
3
Co jeśli mam dwie formy jednego wymaganego arg? Np bardziej standardowy sposób mówiąc: usage: move (+|-)pixelsto znaczy kiedy jeden + lub - jest obowiązkowe ? (Wiem, że mogę mieć 2 wiersze użycia, ale podoba mi się pomysł podwojenia ich przy każdym nowym argumencie). Czy możesz pomyśleć o przykładzie ze standardowego narzędzia?
Alois Mahdal
4
@AloisMahdal zwykle zobaczyć {a|b|c|...}w sekcji pomocy dla SysV init / nowobogackich skryptów usług, które wymagają swoistą argument, że jest jednym z a, b, c, itd. Na przykład, service sddmbez argument w moim systemie wypisuje Usage: /etc/init.d/sddm {start|stop|status|restart|try-restart|force-reload}. Więc większość ludzi prawdopodobnie zrozumie usage: move {+|-}pixels}, zwłaszcza jeśli podany zostanie przykład:example: move +5
Braden Best
@JorgeBucaran nie powinni wychodzić ze statusem 0, czy powinni? Uważam, że wychodzenie ze statusem 2 jest standardem dla niepoprawnych poleceń powłoki.
inavda
91

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>...
Lily Finley
źródło
46

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ć

Steely Wing
źródło
16

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.
MotherDawg
źródło
2
Często zdarza się, że użycie w GNU / Linux nie jest zgodne z tym standardem. Run na przykład man aptitude, że wyprowadza to (między innymi): aptitude [<options>...] {add-user-tag | remove-user-tag} <tag> <packages>.... Zawiera {i} do wiązania alternatywnych poleceń obowiązkowych. Myślę, że (i) mogą być użyte w taki sam sposób, jak w docopt .
jarno
Ta odpowiedź będzie o wiele mniej pomocna, jeśli podany link zejdzie. Może mógłbyś streścić ważne części powiązanego dokumentu w samej odpowiedzi?
domsson,
11

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.

Jared Harley
źródło
9
Microsoft ma straszną pomoc w wierszu poleceń dla większości narzędzi, wszystko jest tak okropne, że zmusili Powershell do ukrywania „zwykłej” linii poleceń pod dywan.
Camilo Martin,
25
Nie sądzę, że odpowiedź powinna zostać zanegowana tylko dlatego, że zawiera odniesienie do standardu Microsoft. „wszystko jest okropne” to subiektywna opinia. W ten sam sposób można powiedzieć, że linia poleceń UNIXa jest okropna i brzydka, ale trzymajmy się z dala od takich opinii i bądźmy profesjonalistami.
Dima
2
Zgadzam się, nie dlatego ta odpowiedź powinna zostać odrzucona. W przypadku oceny negatywnej powinno to wynikać z tego, że a) sekcja cytowanego dokumentu nie odpowiada na pytanie, a b) dokument, do którego prowadzi link, nie wydaje się odpowiedni. Pytanie dotyczy tego, czy istnieją standardy dotyczące „tekstu pomocy” z dużym naciskiem na składnię używaną do komunikowania streszczeń użycia poleceń. Dokument nie ofiarować taką składnię, ale raczej jak budować dobre aplikacje wiersza poleceń w ogóle w ekosystemie PowerShell (np musi obsługiwać -?, -Help, -Version, itd.). Odpowiedź IMO Steely Wing jest bliżej znaku.
Mark G.
9

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.

pmr
źródło
0

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.

łobuz
źródło
4
Nie nie nie. Polecenie powinno mieć stronę podręczną, która zawiera pełne szczegółowe odniesienie do użycia, i -h|--helppowinno być tylko streszczonym odwołaniem. Możesz także dołączyć bardziej obszerną dokumentację (samouczki itp.) Do stron HTML lub informacyjnych. Ale strona podręcznika powinna tam być!
ninjalj
Zgadzam się z tobą, @ninjalj, ale jak powiedziałem: „Nowszy trend”, a przez to mam na myśli, że dwa systemy, których używam, UWin i MinGW, mają wbudowaną dokumentację. Myślę, że osadzony dokument ma swoje miejsca, szczególnie dla małych skryptów na poziomie użytkownika, takich jak to, co ten użytkownik proponuje. Czy powinien nauczyć się nroff i .info? Ale dobrze, abyśmy byli uczciwi, dziękuję za komentarze i życzymy powodzenia wszystkim.
łupacz
Osobiście, kiedy piszę someCommand --helpw mojej powłoce, potrzebuję tylko małego przypomnienia o dokładnej kolejności, w jakiej idą argumenty, a nie ogromnego pokosu tekstu, który wypełnia ekran, wymagając od niego włożenia go lesstylko po to, aby zobaczyć wszystko. Strona powinna znajdować się w miejscu, w którym należy umieścić długi szczegółowy opis, a nie tekst pomocy.
AJMansfield
według twórcy docopt na swojej konferencji wspomina, że ​​POSIX ma do tego normę.
v.oddou
0

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

rluks
źródło
Odnośnie tar... jeśli ktoś ma zamiar zrobić wszystko, co boskie, na przykład tar, spraw, aby krótkie przełączniki były niezapomniane, i dołącz sekcję „przykładowe użycie” w --help. W 90% przypadków patrzę na instrukcje tar, aby wyodrębnić prosty tar.gz.
Camilo Martin,
„ Nie ma potrzeby„ standardowej pomocy ”. „Czy istnieje jakakolwiek„ rzeczywista potrzeba ”większości rzeczy, których używamy? A może są po to, by ułatwić nam życie? Posiadanie uzgodnionego sposobu przedstawiania opcji jest użyteczny nie tylko dla czytelników, ale także np. Przydałoby się budowanie np. GUI, które mogą kontrolować dowolne narzędzia wiersza poleceń i chcą zapewnić kontrolę nad ustawieniem ich opcji. Są prawdopodobnie lepsze zastosowania, których jeszcze nie rozważałem.
underscore_d