Comprender la sinopsis en la página de manual

27

No he podido entender la sección SINOPSIS en la página de manual de un comando. Por ejemplo, veamos la página de manual de mansí mismo. Por man man:

SYNOPSIS
       man  [-C  file]  [-d]  [-D]  [--warnings[=warnings]]  [-R encoding] [-L
       locale] [-m system[,...]] [-M path] [-S list]  [-e  extension]  [-i|-I]
       [--regex|--wildcard]   [--names-only]  [-a]  [-u]  [--no-subpages]  [-P
       pager] [-r prompt] [-7] [-E encoding] [--no-hyphenation] [--no-justifi‐
       cation]  [-p  string]  [-t]  [-T[device]]  [-H[browser]] [-X[dpi]] [-Z]
       [[section] page ...] ...
       man -k [apropos options] regexp ...
       man -K [-w|-W] [-S list] [-i|-I] [--regex] [section] term ...
       man -f [whatis options] page ...
       man -l [-C file] [-d] [-D] [--warnings[=warnings]]  [-R  encoding]  [-L
       locale]  [-P  pager]  [-r  prompt]  [-7] [-E encoding] [-p string] [-t]
       [-T[device]] [-H[browser]] [-X[dpi]] [-Z] file ...
       man -w|-W [-C file] [-d] [-D] page ...
       man -c [-C file] [-d] [-D] page ...
       man [-hV]
  1. ¿La sección SINOPSIS describe la sintaxis del comando?
  2. ¿Qué significan esos [...]y el [...]interior [...]? ¿Significan algo opcional?
  3. ¿ |Significa OR?
  4. ¿Qué ,significa en [-m system[,...]]?
  5. ¿La sección SINOPSIS sigue las reglas utilizadas para las expresiones regulares?
Tim
fuente
Relacionado: "Convenciones de utilidad" en el estándar POSIX: pubs.opengroup.org/onlinepubs/9699919799/basedefs/…
Kusalananda

Respuestas:

25
  1. La sección de sinopsis generalmente da algunos ejemplos de casos de uso. A veces los subcomandos tienen diferentes opciones, por lo que se pueden mostrar varios ejemplos.
  2. Los corchetes []siempre indican interruptores opcionales, argumentos, opciones, etc.
  3. Sí, el tubo |significa o, particularmente cuando está dentro de corchetes o paréntesis.
  4. Los corchetes entre paréntesis solo significan que la segunda parte depende de la primera, y también es opcional. Algunos interruptores se pueden usar solos o agregarles un valor. Las comas al comienzo de un paréntesis indicarían que puede haber múltiples valores separados por comas.
  5. Se apoyan en los conceptos de Regex, pero están destinados a ser legibles por humanos, así que no sigas todas las reglas de escape, etc.
Caleb
fuente
¡Gracias! ¿Hay algunas referencias que expliquen la sintaxis de la sinopsis?
Tim
@Tim: Esa es una de las más locas que he visto, creo que si lees algunas más, te acostumbrarás. Es solo una convención, no mágica.
Caleb
9

Si desea una referencia, se basan libremente en EBNF .

Kim
fuente
3

Desde la manpágina del manual:


Las siguientes convenciones se aplican a la sección SINOPSIS y se pueden usar como guía en otras secciones. descripción de la sinopsis del hombre

El procesamiento exacto puede variar según el dispositivo de salida. Por ejemplo, man generalmente no podrá mostrar cursiva cuando se ejecuta en una terminal, y en su lugar usará texto subrayado o de color.

La ilustración de comando o función es un patrón que debe coincidir con todas las invocaciones posibles. En algunos casos, es aconsejable ilustrar varias invocaciones exclusivas como se muestra en la sección SINOPSIS de esta página del manual.

Jules Randolph
fuente
3

Otra fuente para comprender el significado de la sintaxis del argumento de utilidad de la línea de comandos serían las convenciones de sintaxis de argumentos de utilidad documentadas en el Capítulo 12 y las Expresiones regulares documentadas en el Capítulo 9 del estándar POSIX.1-2008 (Edición 2013).

Slothworks
fuente