¿Existe un formato "estándar" para el texto de ayuda de línea de comandos / shell?

Si no, ¿hay un estándar de facto? Básicamente, estoy escribiendo un texto de ayuda de línea de comando como este:

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

Lo hice básicamente leyendo el texto de ayuda de varias herramientas, pero ¿hay una lista de pautas o algo así? Por ejemplo, ¿uso corchetes o paréntesis? ¿Cómo usar el espaciado? ¿Qué pasa si el argumento es una lista? ¡Gracias!

Por lo general, su resultado de ayuda debe incluir:

• Descripción de lo que hace la aplicación
• Sintaxis de uso, que:
  • Se usa [options]para indicar a dónde van las opciones
  • arg_name para un argumento requerido, singular
  • [arg_name] para un argumento opcional, singular
  • arg_name... para un argumento requerido del cual puede haber muchos (esto es raro)
  • [arg_name...] para un argumento para el cual se puede suministrar cualquier número
  • tenga en cuenta que arg_namedebe ser un nombre corto descriptivo, en minúsculas, caso de serpiente
• Una lista de opciones bien formateadas, cada una:
  • teniendo una breve descripción
  • mostrando el valor predeterminado, si hay uno
  • mostrando los valores posibles, si eso aplica
  • Tenga en cuenta que si una opción puede aceptar un formulario corto (por ejemplo -l) o uno largo (por ejemplo --list), inclúyalos juntos en la misma línea, ya que sus descripciones serán las mismas.
• Breve indicador de la ubicación de los archivos de configuración o las variables de entorno que podrían ser la fuente de los argumentos de la línea de comandos, p. Ej. GREP_OPTS
• Si hay una página de manual, indique como tal, de lo contrario, un breve indicador de dónde se puede encontrar ayuda más detallada

Tenga en cuenta además que es una buena forma de aceptar ambos -hy --helpactivar este mensaje y que debe mostrar este mensaje si el usuario confunde la sintaxis de la línea de comandos, por ejemplo, omite un argumento requerido.

Echa un vistazo a docopt . Es un estándar formal para documentar (y analizar automáticamente) argumentos de línea de comando.

Por ejemplo...

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

Creo que no hay una sintaxis estándar para el uso de la línea de comandos, pero la mayoría usa esta convención:

Sintaxis de línea de comandos de Microsoft , IBM tiene una sintaxis de línea de comandos similar

• Text without brackets or braces

  Elementos que debe escribir como se muestra
  
  

• <Text inside angle brackets>

  Marcador de posición para el que debe proporcionar un valor
  
  

• [Text inside square brackets]

  Elementos opcionales
  
  

• {Text inside braces}

  Conjunto de artículos requeridos; elige uno
  
  

• Barra vertical {a|b}

  Separador para artículos mutuamente excluyentes; elige uno
  
  

• Elipsis <file> …

  Artículos que pueden repetirse
  
  

Estamos ejecutando Linux, un sistema operativo en su mayoría compatible con POSIX. Los estándares POSIX deberían ser: Sintaxis de argumento de utilidad .

• Una opción es un guión seguido de un único carácter alfanumérico, como esto: -o.
• Una opción puede requerir un argumento (que debe aparecer inmediatamente después de la opción); por ejemplo, -o argumento -oargument.
• Las opciones que no requieren argumentos se pueden agrupar después de un guión, por lo que, por ejemplo, -lstes equivalente a -t -l -s.
• Las opciones pueden aparecer en cualquier orden; de este modo -lstes equivalente a -tls.
• Las opciones pueden aparecer varias veces.
• Las opciones preceden a otros argumentos de no -lstopción : no opción.
• El --argumento termina las opciones.
• La -opción se usa generalmente para representar una de las secuencias de entrada estándar.

Microsoft tiene su propia especificación estándar de línea de comandos :

Este documento está enfocado a los desarrolladores de utilidades de línea de comando. Colectivamente, nuestro objetivo es presentar una experiencia de usuario de línea de comandos consistente y componible. Lograr eso le permite al usuario aprender un conjunto básico de conceptos (sintaxis, nomenclatura, comportamientos, etc.) y luego poder traducir ese conocimiento para trabajar con un gran conjunto de comandos. Esos comandos deberían poder generar flujos de datos estandarizados en un formato estandarizado para permitir una composición fácil sin la carga de analizar flujos de texto de salida. Este documento está escrito para ser independiente de cualquier implementación específica de un shell, conjunto de utilidades o tecnologías de creación de comandos; sin embargo, el Apéndice J: Uso de Windows Powershell para implementar el Estándar de línea de comandos de Microsoft muestra cómo usar Windows PowerShell proporcionará la implementación de muchas de estas pautas de forma gratuita.

El estándar de codificación GNU es una buena referencia para cosas como esta. Esta sección trata de la salida de --help. En este caso no es muy específico. Probablemente no pueda equivocarse al imprimir una tabla que muestra las opciones cortas y largas y una descripción sucinta. Intente obtener el espacio entre todos los argumentos correctos para la legibilidad. Probablemente desee proporcionar una manpágina (y posiblemente un infomanual) para que su herramienta proporcione una explicación más elaborada.

Sí, estás en el camino correcto.

Sí, los corchetes son el indicador habitual para artículos opcionales.

Normalmente, como ha esbozado, hay un resumen de la línea de comandos en la parte superior, seguido de detalles, idealmente con muestras para cada opción. (Su ejemplo muestra líneas entre la descripción de cada opción, pero supongo que se trata de un problema de edición, y que su programa real genera listados de opciones sangrados sin líneas en blanco. Este sería el estándar a seguir en cualquier caso).

Una tendencia más nueva, (¿tal vez hay una especificación POSIX que aborda esto?), Es la eliminación del sistema de páginas de manual para la documentación, e incluye toda la información que estaría en una página de manual como parte de la program --helpsalida. Este extra incluirá descripciones más largas, conceptos explicados, ejemplos de uso, limitaciones y errores conocidos, cómo informar un error y, posiblemente, una sección 'ver también' para los comandos relacionados.

Espero que esto ayude.

Seguiría proyectos oficiales como el alquitrán como ejemplo. En mi opinión ayuda msg. debe ser lo más simple y descriptivo posible. Los ejemplos de uso también son buenos. No hay una necesidad real de "ayuda estándar".