Gibt es ein Standardformat für Befehlszeilen- / Shell-Hilfetext?

239

Wenn nicht, gibt es einen De-facto-Standard? Grundsätzlich schreibe ich einen Befehlszeilen-Hilfetext wie folgt:

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

Ich habe das gemacht, indem ich im Grunde nur den Hilfetext verschiedener Tools gelesen habe, aber gibt es eine Liste von Richtlinien oder so? Verwenden Sie beispielsweise eckige Klammern oder Klammern? Wie verwende ich den Abstand? Was ist, wenn das Argument eine Liste ist? Vielen Dank!

shell command-line command-line-arguments Yifan
quelle
8
Ich denke, dass GNU einige Hinweise hat. Ich würde mir ansehen, was die meisten GNU-Dienstprogramme tun.
Basile Starynkevitch
1
@ DanielPryden Ich denke, die Antwort in dieser Frage ist etwas irreführend. Es enthält Links, die erklären, welche Schalter akzeptiert werden sollen und nicht, wie die Ausgabe von --helpaussehen soll. Beide Fragen sind jedoch ein guter Kandidat für eine Fusion.
PMR
@pmr: Ich stimme zu - vielleicht kann ein Mod die Fragen für uns zusammenführen.
Daniel Pryden
2
Ich würde mir ansehen, was die meisten GNU-Dienstprogramme tun, und es anders machen.
Yakov Galka

Antworten:

159

In der Regel sollte Ihre Hilfeausgabe Folgendes enthalten:

  • Beschreibung der Funktionen der App
  • Verwendungssyntax, die:
    • Wird verwendet, [options]um anzugeben, wohin die Optionen führen
    • arg_name für ein erforderliches, singuläres arg
    • [arg_name] für ein optionales, singuläres Argument
    • arg_name... für ein erforderliches Argument, von dem es viele geben kann (dies ist selten)
    • [arg_name...] für ein Argument, für das eine beliebige Nummer angegeben werden kann
    • Beachten Sie, dass arg_namedies ein beschreibender Kurzname in Kleinbuchstaben sein sollte
  • Eine schön formatierte Liste von Optionen, jede:
    • mit einer kurzen Beschreibung
    • Zeigt den Standardwert an, falls vorhanden
    • Anzeigen der möglichen Werte, falls zutreffend
    • Beachten Sie, dass, wenn eine Option eine Kurzform (z. B. -l) oder eine Langform (z. B. ) akzeptieren kann, --listdiese in derselben Zeile zusammengefasst werden, da ihre Beschreibungen identisch sind
  • Kurzer Indikator für den Speicherort von Konfigurationsdateien oder Umgebungsvariablen, die möglicherweise die Quelle für Befehlszeilenargumente sind, z GREP_OPTS
  • Wenn es eine Manpage gibt, geben Sie als solche an, andernfalls eine kurze Anzeige, wo detailliertere Hilfe zu finden ist

Beachten Sie außerdem, dass es eine gute Form ist, beide zu akzeptieren -hund --helpdiese Nachricht auszulösen, und dass Sie diese Nachricht anzeigen sollten, wenn der Benutzer die Befehlszeilensyntax durcheinander bringt, z. B. ein erforderliches Argument weglässt.

davetron5000
quelle
3
Was ist, wenn ich zwei Formen eines einzelnen erforderlichen Args habe? ZB eine üblichere Art zu sagen: usage: move (+|-)pixelsdh wann eine von + oder - ist obligatorisch ? (Ich weiß, dass ich zwei Verwendungszeilen haben kann, aber ich mag die Idee, sie mit jedem neuen Argument zu verdoppeln.) Können Sie sich ein Beispiel aus einem Standardwerkzeug vorstellen?
Alois Mahdal
4
@AloisMahdal ich in der Regel finden Sie {a|b|c|...}in den Hilfeabschnitte für SysV Init / Emporkömmling Dienstskripten, die ein einzigartiges Argument erfordern , die eine von ist a, b, c, etc. Zum Beispiel, service sddmohne ein Argument auf meinem System druckt Usage: /etc/init.d/sddm {start|stop|status|restart|try-restart|force-reload}. So würden die meisten Leute wahrscheinlich verstehen usage: move {+|-}pixels}, besonders wenn ein Beispiel gegeben wird:example: move +5
Braden Best
@JorgeBucaran sollten sie nicht mit Status 0 beenden, oder? Ich glaube, das Beenden mit Status 2 ist der Standard für ungültige Shell-Befehle.
Inavda
88

Schauen Sie sich docopt an . Es ist ein formaler Standard zum Dokumentieren (und automatischen Parsen) von Befehlszeilenargumenten.

Beispielsweise...

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
quelle
46

Ich denke, es gibt keine Standardsyntax für die Verwendung der Befehlszeile, aber die meisten verwenden diese Konvention:

Microsoft- Befehlszeilensyntax , IBM hat eine ähnliche Befehlszeilensyntax

  • Text without brackets or braces

    Elemente, die Sie wie gezeigt eingeben müssen

  • <Text inside angle brackets>

    Platzhalter, für den Sie einen Wert angeben müssen

  • [Text inside square brackets]

    Extras

  • {Text inside braces}

    Satz erforderlicher Gegenstände; wähle ein

  • Vertikale Leiste {a|b}

    Trennzeichen für sich gegenseitig ausschließende Gegenstände; wähle ein

  • Ellipse <file> …

    Elemente, die wiederholt werden können

Steely Wing
quelle
15

Wir verwenden Linux, ein größtenteils POSIX-kompatibles Betriebssystem. POSIX-Standards sollten es sein: Utility Argument Syntax .

  • Eine Option ist ein Bindestrich, gefolgt von einem einzelnen alphanumerischen Zeichen wie folgt : -o.
  • Für eine Option ist möglicherweise ein Argument erforderlich (das unmittelbar nach der Option angezeigt werden muss). zum Beispiel -o argumentoder -oargument .
  • Optionen, für die keine Argumente erforderlich sind, können nach einem Bindestrich gruppiert werden. Dies -lstentspricht beispielsweise-t -l -s .
  • Optionen können in beliebiger Reihenfolge angezeigt werden. ist also -lstgleichbedeutend mit-tls .
  • Optionen können mehrfach angezeigt werden.
  • Optionen stehen vor anderen Nichtoptionsargumenten: -lst Nichtoption.
  • Das -- Argument beendet Optionen.
  • Die -Option wird normalerweise verwendet, um einen der Standardeingabestreams darzustellen.
MotherDawg
quelle
2
Es ist üblich, dass die Verwendung in GNU / Linux nicht genau diesem Standard entspricht. Führen Sie zB das aus man aptitude, das dies (unter anderem) ausgibt : aptitude [<options>...] {add-user-tag | remove-user-tag} <tag> <packages>.... Es enthält {und} zum Binden alternativer Pflichtbefehle. Ich denke (und) könnte für das gleiche verwendet werden, wie sie in docopt verwendet werden .
Jarno
Diese Antwort ist viel weniger hilfreich, wenn der angegebene Link ausfällt. Vielleicht könnten Sie die wichtigen Teile des verknüpften Dokuments in der Antwort selbst zusammenfassen?
Domsson
11

Microsoft hat eine eigene Command Line Standard-Spezifikation :

Dieses Dokument richtet sich an Entwickler von Befehlszeilenprogrammen. Gemeinsam ist es unser Ziel, eine konsistente, zusammensetzbare Benutzererfahrung für die Befehlszeile zu bieten. Dadurch kann ein Benutzer eine Reihe von Kernkonzepten (Syntax, Benennung, Verhalten usw.) erlernen und dieses Wissen dann in die Arbeit mit einer großen Anzahl von Befehlen umsetzen. Diese Befehle sollten in der Lage sein, standardisierte Datenströme in einem standardisierten Format auszugeben, um eine einfache Komposition zu ermöglichen, ohne die Belastung durch das Parsen von Ausgabetextströmen. Dieses Dokument ist so geschrieben, dass es unabhängig von einer bestimmten Implementierung einer Shell, einer Reihe von Dienstprogrammen oder Technologien zur Befehlserstellung ist. Anhang J - Verwenden von Windows Powershell zur Implementierung des Microsoft Command Line Standard zeigt jedoch, wie die Verwendung von Windows PowerShell die kostenlose Implementierung vieler dieser Richtlinien ermöglicht.

Jared Harley
quelle
8
Microsoft hat für die meisten Dienstprogramme eine schreckliche Befehlszeilenhilfe. Alles ist so schrecklich, dass Powershell die "normale" Befehlszeile unter dem Teppich versteckt.
Camilo Martin
25
Ich denke nicht, dass die Antwort abgelehnt werden sollte, nur weil sie einen Verweis auf den Microsoft-Standard enthält. "Alles ist so schrecklich" ist eine subjektive Meinung. Auf die gleiche Weise kann man sagen, dass die Befehlszeile von UNIX schrecklich und hässlich ist, aber lassen Sie uns solche Meinungen fernhalten und Profis sein.
Dima
2
Einverstanden, deshalb sollte diese Antwort nicht abgelehnt werden. Wenn es abgelehnt wird, sollte dies daran liegen, dass a) der zitierte Abschnitt des Dokuments die vorliegende Frage nicht beantwortet und b) das verknüpfte Dokument nicht relevant erscheint. Bei der Frage wird gefragt, ob es Standards für „Hilfetext“ gibt, bei denen die Syntax für die Kommunikation von Befehlsverwendungssynopsen im Vordergrund steht. Das Dokument kredenzt keine solche Syntax , sondern wie gut apps Befehlszeile in dem Powershell - Ökosystem im Allgemeinen bauen (zB unterstützen muß -?, -Help, -Version, etc.). Die Antwort von IMO Steely Wing ist näher an der Marke.
Mark G.
9

Der GNU Coding Standard ist eine gute Referenz für solche Dinge. Dieser Abschnitt befasst sich mit der Ausgabe von --help. In diesem Fall ist es nicht sehr spezifisch. Sie können wahrscheinlich nichts falsch machen, wenn Sie eine Tabelle mit den kurzen und langen Optionen und einer kurzen Beschreibung drucken. Versuchen Sie, den Abstand zwischen allen Argumenten für die Lesbarkeit richtig zu machen. Sie möchten wahrscheinlich eine manSeite (und möglicherweise ein infoHandbuch) für Ihr Tool bereitstellen, um eine ausführlichere Erklärung zu erhalten.

pmr
quelle
0

Ja, du bist auf dem richtigen Weg.

Ja, eckige Klammern sind der übliche Indikator für optionale Elemente.

Wie Sie bereits skizziert haben, befindet sich oben eine Befehlszeilenübersicht, gefolgt von Details, idealerweise mit Beispielen für jede Option. (Ihr Beispiel zeigt Zeilen zwischen den einzelnen Optionsbeschreibungen, aber ich gehe davon aus, dass dies ein Bearbeitungsproblem ist und dass Ihr reales Programm eingerückte Optionslisten ohne dazwischen liegende Leerzeilen ausgibt. Dies wäre in jedem Fall der Standard.)

Ein neuerer Trend (vielleicht gibt es eine POSIX-Spezifikation, die dies behebt?) Ist die Eliminierung des Manpage-Systems zur Dokumentation und die Einbeziehung aller Informationen, die in einer Manpage als Teil der enthalten wären program --help Ausgabe enthalten . Dieses Extra enthält längere Beschreibungen, erläuterte Konzepte, Verwendungsbeispiele, bekannte Einschränkungen und Fehler, das Melden eines Fehlers und möglicherweise einen Abschnitt "Siehe auch" für verwandte Befehle.

Ich hoffe das hilft.

Shellter
quelle
4
Nein nein Nein. Der Befehl sollte eine Manpage enthalten, die eine vollständige detaillierte Verwendungsreferenz enthält, und -h|--helpsollte nur eine zusammengefasste Referenz sein. Sie können auch eine umfassendere Dokumentation (Tutorials usw.) in HTML- oder Infoseiten einfügen. Aber die Manpage sollte da sein!
Ninjalj
Ich stimme Ihnen zu, @ninjalj, aber wie gesagt "Ein neuer Trend", und damit meine ich die beiden Systeme, die ich verwende, UWin und MinGW, beide mit eingebetteter Dokumentation. Ich denke, eingebettetes Dokument hat seine Plätze, insbesondere für kleine Skripte auf Benutzerebene, wie das, was dieser Benutzer vorschlägt. Sollte er nroff und .info lernen müssen? Aber gut, um uns ehrlich zu halten, danke für Ihre Kommentare und viel Glück an alle.
Shellter
Persönlich, wenn ich someCommand --helpan meiner Shell tippe, brauche ich nur eine kleine Erinnerung an die genaue Reihenfolge der Argumente, nicht einen riesigen Textstreifen, der den Bildschirm ausfüllt, und ich muss ihn lessnur weiterleiten, um alles zu sehen. Auf der Manpage sollte sich die lange detaillierte Beschreibung befinden, nicht der Hilfetext.
AJMansfield
0

Ich würde offizielle Projekte wie Teer als Beispiel verfolgen. Meiner Meinung nach helfen msg. muss so einfach und beschreibend wie möglich sein. Anwendungsbeispiele sind auch gut. Es besteht kein wirklicher Bedarf an "Standardhilfe".

rluks
quelle
In Bezug auf tar... Wenn jemand ein Allzweck-Dienstprogramm wie Teer herstellen möchte, machen Sie bitte die kurzen Schalter unvergesslich und fügen Sie einen Abschnitt "Beispielverwendung" in das Feld ein --help. In 90% der Fälle schaue ich mir die Anweisungen von tar an, um eine einfache zu extrahieren tar.gz.
Camilo Martin
" Es besteht kein wirklicher Bedarf an" Standardhilfe ". "Gibt es einen" echten Bedarf "für die meisten Dinge, die wir verwenden? Oder sind sie nur da, um unser Leben viel einfacher zu machen? Eine vereinbarte Art der Darstellung von Optionen ist nicht nur für Leser nützlich, sondern wäre auch nützlich, wenn z. B. GUIs erstellt werden, die beliebige Befehlszeilenprogramme steuern können und Steuerelemente zum Festlegen ihrer Optionen bereitstellen möchten. Es gibt wahrscheinlich bessere Anwendungen, die ich noch nicht in Betracht gezogen habe.
underscore_d