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

Microsoft hat seine eigene Kommandozeile Standard-Spezifikation :

Dieses Dokument richtet sich an Entwickler von Kommandozeilen-Dienstprogrammen. Unser gemeinsames Ziel ist es, eine konsistente, kompatible Kommandozeilen-Benutzererfahrung zu bieten. Um dies zu erreichen, muss der Benutzer einen Kernsatz von Konzepten (Syntax, Benennung, Verhalten usw.) erlernen und dann in der Lage sein, dieses Wissen in die Arbeit mit einem großen Satz von Befehlen umzusetzen. Diese Befehle sollten in der Lage sein, standardisierte Datenströme in einem standardisierten Format auszugeben, um eine einfache Komposition zu ermöglichen, ohne die Last des Parsens 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 - Verwendung von Windows Powershell zur Implementierung des Microsoft Command Line Standard zeigt jedoch, wie die Verwendung von Windows PowerShell die Umsetzung vieler dieser Richtlinien kostenlos ermöglicht.

Answer 2

Es gibt keine Norm, aber http://docopt.org/ hat ihre Version einer Spezifikation für Hilfetexte für Befehlszeilentools erstellt.

Answer 3

Ja, Sie sind auf dem richtigen Weg.

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

In der Regel gibt es, wie Sie skizziert haben, oben eine Zusammenfassung der Befehlszeile, gefolgt von Details, idealerweise mit Beispielen für jede Option. (Ihr Beispiel zeigt Zeilen zwischen den einzelnen Optionsbeschreibungen, aber ich nehme an, dass dies ein Bearbeitungsproblem ist und dass Ihr echtes Programm eingerückte Optionslisten ohne Leerzeilen dazwischen ausgibt. Dies wäre auf jeden Fall der Standard, den man befolgen sollte).

Ein neuerer Trend (vielleicht gibt es eine POSIX-Spezifikation, die sich damit befasst?) ist die Abschaffung des Manpage-Systems für die Dokumentation und die Aufnahme aller Informationen, die in eine Manpage gehören würden, als Teil der program --help Ausgabe. Dieses Extra wird längere Beschreibungen, erläuterte Konzepte, Anwendungsbeispiele, bekannte Einschränkungen und Fehler, Hinweise zum Melden von Fehlern und möglicherweise einen Abschnitt "siehe auch" für verwandte Befehle enthalten.

Ich hoffe, das hilft.

Answer 4

Es kann ein bit Off-Topic, aber ich habe einmal zwei kleine Tools geschrieben, die die Erstellung und Pflege von Hilfeseiten für Kommandozeilen-Tools effizienter machen:

• Le HAUPTDOKLET das ein HTML-Dokument für die Hauptmethode eines Java-Programms erzeugt, indem es Javadoc-Kommentare im Quellcode verarbeitet
• Le HTML2TXT-Werkzeug die ein HTML-Dokument als reinen Text formatiert (was wir für unsere Hilfetexte brauchen)

Ich integriere diese beiden Tools in den MAVEN-Build-Prozess meiner Programme, damit sie bei jedem Build automatisch ausgeführt werden.

Zum Beispiel:

• Le entsprechende Quelldatei meines ZZFIND-Tools
• Le POM-Datei der das Projekt erstellt (und die beiden oben genannten Tools ausführt)
• Beispielhafte Ausgabe wenn ZZFIND mit der Option --help Kommandozeilenoption

Ich hoffe, dies ist für andere nützlich!?

Answer 5

Ich würde mich an offiziellen Projekten wie tar ein Beispiel nehmen. Meiner Meinung nach müssen die Hilfetexte so einfach und beschreibend wie möglich sein. Beispiele für die Verwendung sind auch gut. Es gibt keinen wirklichen Bedarf für eine "Standardhilfe".