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

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!

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.

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

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
  
  

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.

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.

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.

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.

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