Bash script : help file inside the script or in a different file

bashscriptingshell-script

I'm writing a script that has the vocation to be a fully featured program at the end. As far as I know, BASH is enough for his purpose (manage PPA's, kinda like Y-PPA). I would like to know how to output the help myscript --help.

Currently, help is written with echo -e directly inside the script and called with a if [ "$1" == "--help" ] || [ "$1" == "-h" ] (I plan on switching that to getopts soon).

But what's better ? To leave the help section inside the script or to just write a line to call another file containing the help ?

In my opinion, leaving it inside the script could be better because :

  • My program will remain a one text-file script
  • It saves space on the hard-drive
  • It avoids having an error with displaying another file that could be corrupted or in a different location

But having a different text-file containing the help could also be better because :

  • The main script called with myscript command would be lighter
  • It simplifies the human-reading of the script
  • It allows to update the help page separately if needed
  • It could even allow to display only the help page with a GUI, and/or print it.

So you see, I don't know what's the "usual" way of doing this. Thank you !

PS : please also note that since I'm planning to release a complete program, a man-page would be great so I would anyway have to provide more than 1 file, maybe simply a .deb

Best Answer

The 2 approaches I see here are more:

  • setting a inline section or a POD-like documentation to display as help, or
  • properly defining a .man file to add to your local man structure

I honestly don't see the point of having a separate file for that kind of help, unless you have a very big tool and the interface/GUI is already in different file(s).

So stay "plain and simple": all in one file regarding your command-line frontend.

You can still organize it as a chunk of inline-text or properly defined function which sole purpose is to display the help. So no ill done to the poor guy who will maintain your script in 10 years.

Related Question