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

Question

Wenn nicht, gibt es eine De-facto-Norm? Im Grunde 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 im Grunde nur durch das Lesen der Hilfetexte der verschiedenen Tools herausgefunden, aber gibt es eine Liste mit Richtlinien oder so etwas? Soll ich zum Beispiel eckige Klammern oder Klammern verwenden? Wie verwendet man Abstände? Was ist, wenn das Argument eine Liste ist? Vielen Dank!

Answer 1

Normalerweise sollte Ihre Hilfeausgabe Folgendes enthalten:

• Beschreibung der Funktionen der App
• Verwendungssyntax, die:
  • Verwendet [options] um anzugeben, wohin die Optionen gehen
  • arg_name für ein erforderliches, singuläres Argument
  • [arg_name] für ein fakultatives, singuläres Argument
  • arg_name... für ein erforderliches Argument, von denen es viele geben kann (was selten ist)
  • [arg_name...] für ein arg, für das eine beliebige Zahl angegeben werden kann
  • beachten Sie, dass arg_name sollte ein beschreibender, kurzer Name in Klein- und Schlangenschrift sein
• Eine schön formatierte Liste von Optionen, jede:
  • mit einer kurzen Beschreibung
  • Anzeige des Standardwerts, wenn es einen solchen gibt
  • mit den möglichen Werten, falls dies zutrifft
  • Beachten Sie, dass, wenn eine Option eine Kurzform annehmen kann (z. B. -l ) oder eine Langform (z. B. --list ), fügen Sie sie zusammen in dieselbe Zeile ein, da ihre Beschreibungen identisch sind
• Kurzer Hinweis auf den Speicherort von Konfigurationsdateien oder Umgebungsvariablen, die die Quelle von Befehlszeilenargumenten sein könnten, z. B. GREP_OPTS
• Wenn es eine Man-Page gibt, geben Sie diese an, andernfalls einen kurzen Hinweis darauf, wo ausführlichere Hilfe zu finden ist

Beachten Sie außerdem, dass es zum guten Ton gehört, sowohl -h y --help um diese Meldung auszulösen und dass Sie diese Meldung anzeigen sollten, wenn der Benutzer die Befehlszeilensyntax durcheinanderbringt, z. B. ein erforderliches Argument auslässt.

Answer 2

Werfen Sie einen Blick auf docopt . Es handelt sich um einen formalen Standard für die Dokumentation (und das automatische Parsen) von Kommandozeilenargumenten.

Zum Beispiel...

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

Answer 3

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

Microsoft Befehlszeilen-Syntax IBM hat ähnliche Befehlszeilen-Syntax

---

• Text without brackets or braces

  Sie müssen folgende Angaben machen

• <Text inside angle brackets>

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

• [Text inside square brackets]

  Optionale Elemente

• {Text inside braces}

  Set der erforderlichen Elemente; wählen Sie eines aus

• Senkrechter Balken {a|b}

  Trennzeichen für sich gegenseitig ausschließende Positionen; wählen Sie eines

• Ellipsis <file> …

  Elemente, die wiederholt werden können

Answer 4

Wir verwenden Linux, ein weitgehend POSIX-kompatibles Betriebssystem. POSIX-Standards sollten es sein: Syntax der Dienstprogramm-Argumente .

• Eine Option ist ein Bindestrich, gefolgt von einem einzelnen alphanumerischen Zeichen, etwa so: -o .
• Eine Option kann ein Argument erfordern (das erscheinen muss unmittelbar nach der Option stehen muss); zum Beispiel, -o argument o -oargument .
• Optionen, die keine Argumente erfordern, können nach einem Bindestrich gruppiert werden, z. B., -lst ist gleichbedeutend mit -t -l -s .
• Die Optionen können in beliebiger Reihenfolge erscheinen, also -lst ist gleichbedeutend mit -tls .
• Optionen können mehrfach erscheinen.
• Optionen stehen vor anderen Nicht-Optionen Argumente: -lst keine Option.
• Le -- Argument beendet die Optionen.
• Le - wird normalerweise verwendet, um eine der Standardeingaben zu repräsentieren Ströme.

Answer 5

Der GNU Coding Standard ist eine gute Referenz für derartige Dinge. Dieser Abschnitt befasst sich mit der Ausgabe von --help . In diesem Fall ist es nicht sehr spezifisch. Sie können wahrscheinlich nicht viel falsch machen, wenn Sie eine Tabelle ausdrucken, die die kurzen und langen Optionen und eine kurze Beschreibung enthält. Versuchen Sie, die Abstände zwischen den einzelnen Argumenten so zu wählen, dass sie gut lesbar sind. Wahrscheinlich sollten Sie eine man Seite (und möglicherweise eine info Handbuch) für Ihr Werkzeug, um eine ausführlichere Erklärung zu erhalten.