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

239

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!

shell command-line command-line-arguments Yifan
fuente
8
Creo que GNU tiene algunas pistas. Me gustaría ver lo que la mayoría de las utilidades de GNU están haciendo.
Basile Starynkevitch
1
@DanielPryden Creo que la respuesta en esa pregunta es un poco engañosa. Ofrece enlaces que explican qué interruptores deberían aceptarse y no cómo --helpdebería verse la salida de . Pero ambas preguntas son un buen candidato para una fusión.
pmr
@pmr: Estoy de acuerdo, tal vez un mod pueda fusionar las preguntas por nosotros.
Daniel Pryden
2
Vería lo que están haciendo la mayoría de las utilidades de GNU, y lo haría de la otra manera.
Yakov Galka

Respuestas:

160

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.

davetron5000
fuente
3
¿Qué pasa si tengo dos formas de un solo argumento requerido? Por ejemplo, una forma más estándar de decir: usage: move (+|-)pixelses decir, cuando uno de + o - es obligatorio ? (Sé que puedo tener 2 líneas de uso, pero me gusta la idea de duplicarlas con cada nuevo argumento). ¿Puedes pensar en un ejemplo de una herramienta estándar?
Alois Mahdal
44
@AloisMahdal suelo ver {a|b|c|...}en las secciones de ayuda para guiones de servicio SysV / advenedizos, que requieren un argumento singular que es uno de a, b, c, etc. Por ejemplo, service sddmy sin un argumento en mi sistema imprime Usage: /etc/init.d/sddm {start|stop|status|restart|try-restart|force-reload}. Entonces, la mayoría de la gente probablemente lo entendería usage: move {+|-}pixels}, especialmente si se da un ejemplo:example: move +5
Braden Best
@JorgeBucaran, no deberían salir con el estado 0, ¿verdad? Creo que salir con el estado 2 es el estándar para los comandos de shell no válidos.
Inavda
91

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>...
Lily Finley
fuente
46

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

Ala de acero
fuente
16

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.
MotherDawg
fuente
2
Es común que el uso en GNU / Linux no siga exactamente este estándar. Ejecutar por ejemplo, man aptitudeque da salida a esta (entre otras cosas): aptitude [<options>...] {add-user-tag | remove-user-tag} <tag> <packages>.... Contiene {y} para enlazar comandos obligatorios alternativos. Creo que (y) podrían usarse para lo mismo como se usan en docopt .
jarno
Esta respuesta será mucho menos útil si el enlace proporcionado se cae. ¿Quizás podría resumir las partes importantes del documento vinculado en la respuesta misma?
domsson
11

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.

Jared Harley
fuente
99
Microsoft tiene una terrible ayuda de línea de comando para la mayoría de las utilidades, todo es tan horrible que hicieron que Powershell ocultara la línea de comando "normal" debajo de la alfombra.
Camilo Martin
25
No creo que la respuesta deba ser rechazada solo porque tiene una referencia al estándar de Microsoft. "todo es tan horrible" es una opinión subjetiva. De la misma manera, se puede decir que la línea de comando de UNIX es horrible y fea, pero mantengamos esas opiniones alejadas y seamos profesionales.
Dima
2
De acuerdo, esa no es la razón por la cual esta respuesta debe ser rechazada. Si se rechaza, debe ser porque a) la sección del documento que se ha citado no responde la pregunta en cuestión, yb) el documento vinculado no parece relevante. La pregunta pregunta si hay estándares para el "texto de ayuda" con un fuerte énfasis en la sintaxis utilizada para comunicar las sinopsis de uso de comandos. El documento no proferir una sintaxis tal, sino más bien cómo construir buenas aplicaciones de línea de comandos en general en el ecosistema PowerShell (por ejemplo, debe ser compatible con -?, -Help, -Version, etc.). La respuesta de IMO Steely Wing está más cerca de la marca.
Mark G.
9

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.

pmr
fuente
0

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.

cáscara
fuente
44
No no no. El comando debe tener una página de manual que incluya una referencia de uso detallada completa y -h|--helpdebe ser solo una referencia resumida. También puede incluir documentación más completa (tutoriales, etc.) en páginas HTML o de información. ¡Pero la página de manual debería estar allí!
ninjalj
Estoy de acuerdo con usted, @ninjalj, pero como dije, "Una tendencia más nueva", y con eso quiero decir que los dos sistemas que uso, UWin y MinGW, han ido con documentación incorporada. Creo que el documento incrustado tiene sus lugares, especialmente para el script pequeño a nivel de usuario, como lo que este usuario propone. ¿Debería tener que aprender nroff e .info? Pero bueno para mantenernos honestos, gracias por sus comentarios y buena suerte a todos.
shellter
Personalmente, cuando escribo someCommand --helpen mi shell, todo lo que necesito es un pequeño recordatorio del orden preciso en el que entran los argumentos, no una franja gigante de texto que llena la pantalla, lo que requiere que lo coloque lesssolo para verlo todo. La página de manual debe ser donde colocas la descripción detallada larga, no el texto de ayuda.
AJMansfield
Según el fabricante de docopt en su conferencia, menciona que POSIX tiene una norma para esto.
v.oddou
0

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

rluks
fuente
Con respecto a tar... si alguien va a hacer una utilidad divina para todo, como tar, haga que los interruptores cortos sean memorables e incluya una sección de "uso de ejemplo" en el --help. El 90% del tiempo que miro las instrucciones del alquitrán es para extraer un simple tar.gz.
Camilo Martin
" No hay una necesidad real de" ayuda estándar ". ¿Existe alguna "necesidad real" para la mayoría de las cosas que usamos? ¿O simplemente están allí para hacernos la vida mucho más fácil? Tener una forma acordada de representar opciones es útil no solo para los lectores, sino también, por ejemplo, sería útil para las personas que crean, por ejemplo, GUI que pueden controlar utilidades arbitrarias de línea de comandos y desean proporcionar controles para establecer sus opciones. Probablemente hay mejores usos que aún no consideré.
underscore_d