syntax man

syntax - ¿Hay alguna especificación para la sección SINOPSIS de una página de manual?



(3)

Estoy tratando de escribir algunas especificaciones para ser compartidas entre un pequeño equipo y ser exigente con el formato en el que pongo algunos listados de comandos. ¿Existe alguna definición formal de la sintaxis utilizada en la sección SINOPSIS de las páginas del manual?

Desde Wikimedia Commons, aquí hay un ejemplo de una página de manual con la sección SINOPSIS de la que estoy hablando, donde el comando se enumera con los argumentos necesarios y opcionales que entiende.

man 7 man-pages:

Describe brevemente la interfaz del comando o función. Para los comandos, esto muestra la sintaxis del comando y sus argumentos (incluidas las opciones); la negrita se usa para el texto tal como está y la cursiva se usa para indicar argumentos reemplazables. Los corchetes ([]) rodean los argumentos opcionales, las barras verticales (|) las elecciones separadas y los puntos suspensivos (...) se pueden repetir. Para las funciones, muestra las declaraciones de datos requeridas o las directivas #include, seguidas de la declaración de la función.

No existe una definición formal de una página de manual en ninguna parte, ni siquiera en el estándar POSIX. La página de man(1) en su ejemplo es bastante típica: usted escribe las diferentes formas en que se puede usar un programa (a menudo solo una) con [] denotando opcional, negrita (o fuente de máquina de escribir con las macros mdoc ) denotando entrada de línea de comando literal y cursivas que denotan variables.

Las páginas de manual man(7) y mdoc(7) explicarán las convenciones más importantes. man(7) es para las páginas de manual de Unix de estilo antiguo y sigue siendo popular en Linux (vea man-pages(7) ); mdoc(7) proviene de 4.4BSD y es popular en sus derivados. Este último mantiene una separación más estricta de contenido y presentación y puede producir (IMHO) una salida de PDF / HTML más bonita