Bash script: archivo de ayuda dentro del script o en un archivo diferente?

Estoy escribiendo un guión que tiene la vocación de ser un programa completo al final. Hasta donde yo sé, BASH es suficiente para su propósito (administrar PPA, algo así como Y-PPA). Me gustaría saber cómo generar la ayuda myscript --help.

Actualmente, la ayuda se escribe echo -edirectamente dentro del script y se llama con un if [ "$1" == "--help" ] || [ "$1" == "-h" ](planeo cambiar eso a getopts pronto).

Pero que es mejor? ¿Para dejar la helpsección dentro del script o simplemente escribir una línea para llamar a otro archivo que contiene la ayuda?

En mi opinión, dejarlo dentro del script podría ser mejor porque:

• Mi programa seguirá siendo un script de archivo de texto
• Ahorra espacio en el disco duro
• Evita tener un error al mostrar otro archivo que podría estar dañado o en una ubicación diferente

Pero tener un archivo de texto diferente que contenga la ayuda también podría ser mejor porque:

• El guión principal llamado con myscriptcomando sería más claro
• Simplifica la lectura humana del guión.
• Permite actualizar la página de ayuda por separado si es necesario
• Incluso podría permitir mostrar solo la página de ayuda con una GUI y / o imprimirla.

Así que ya ves, no sé cuál es la forma "habitual" de hacer esto. Gracias !

PD: tenga en cuenta también que, dado que planeo lanzar un programa completo, una página de manual sería excelente, por lo que tendría que proporcionar más de 1 archivo, tal vez simplemente un archivo .deb

Los 2 enfoques que veo aquí son más:

• establecer una sección en línea o una documentación similar a POD para mostrar como ayuda, o
• definir correctamente un .manarchivo para agregar a su manestructura local

Sinceramente, no veo el punto de tener un archivo separado para ese tipo de ayuda, a menos que tenga una herramienta muy grande y la interfaz / GUI ya esté en diferentes archivos.

Así que mantente " claro y simple ": todo en un archivo con respecto a tu interfaz de línea de comandos.

Todavía puede organizarlo como un fragmento de texto en línea o una función definida adecuadamente cuyo único propósito es mostrar la ayuda. Así que no le ha hecho mal al pobre tipo que mantendrá su guión en 10 años.

Estoy de acuerdo con Ouki con respecto a mantenerlo simple y dentro del guión por ahora. Cuando y si decides que quieres una página de manual, puedes trasplantar allí y dejar una ayuda simplificada.

Examinando 3 de 4 de sus desventajas de este enfoque frente a un archivo separado:

• El script principal llamado con el comando myscript sería más claro

  Habría un número trivial de bytes cargados en la memoria, tan trivial que sería una tontería molestarse en pensar.

• Simplifica la lectura humana del guión.

  Si está bien organizado, lo contrario es cierto, ya que tener esa ayuda a mano en la fuente es una forma de documentación para el código en sí (ver más abajo).

• Incluso podría permitir mostrar solo la página de ayuda con una GUI y / o imprimirla.

  El énfasis en la modularidad en los sistemas de estilo Unix significa que es mejor no preocuparse por esto. Si su secuencia de comandos escribe en la salida estándar, el usuario puede combinar esto con las herramientas que prefiera con respecto a la impresión y la visualización. Hay pocas cosas más molestas que los programas que se esfuerzan por implementar características innecesarias que reflejan, por ejemplo, los medios preferidos del autor para ver la documentación. No hagas eso. Si se trata de una herramienta de línea de comandos en primer plano, su salida normal debería ser la secuencia de salida estándar y el error en la secuencia de error estándar. No te vuelvas loco.

Si no conoce los documentos "aquí" , esto puede simplificar la tarea y mantener la fuente más ordenada y legible:

#!/bin/bash

function myHelp () {
# Using a here doc with standard out.
cat <<-END
Usage:
------
   -h | --help
     Display this help
   -n
     Do nothing loudly.
END
}

doNothing=0;
while [ -n "$1" ]; do
    case "$1" in
        -h | --help)
            myHelp
            exit
            ;;
        -n)
            doNothing=1;
            shift
            ;;
    esac 
done 

if [ $doNothing -gt 0 ]; then
    echo -e "****\nDoing nothing!\n****"
fi        

Observe que hay una función llamada para la opción de ayuda, que mantiene el ifbloque ordenado. También significa que puede colocar esa función en la parte superior , por lo que es una forma obvia de referencia a la fuente misma.

Puede sangrar el documento aquí myHelp(), por cierto, las pestañas se ignoran, pero se conservan los espacios. Lo hice así para evitar resultados confusos de cortar y pegar.