Take the 2-minute tour ×
Unix & Linux Stack Exchange is a question and answer site for users of Linux, FreeBSD and other Un*x-like operating systems.. It's 100% free, no registration required.

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

share|improve this question

2 Answers 2

up vote 2 down vote accepted

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.

share|improve this answer
    
I made it a function. Thanks ! –  MrVaykadji Mar 25 at 23:28

I agree w/ Ouki regarding keeping it simple and within the script for now. When and if you decide you want a man page, you can transplant to there and leave a simplified help.

Examining 3 of 4 of your disadvantages to this approach vs. a separate file:

  • The main script called with myscript command would be lighter

    There would be a trivial number of bytes loaded into memory -- so trivial it would be silly to bother thinking about.

  • It simplifies the human-reading of the script

    If you are well organized, the opposite is true since having that help at hand in the source is a form of documentation for the code itself (see below).

  • It could even allow to display only the help page with a GUI, and/or print it.

    The emphasis on modularity in unix style systems means that you are better off not concerning yourself with this. If your script writes to standard output, the user is able to combine this with whatever tools s/he prefers regarding printing and display. There are few things more annoying than programs that strive to implement unnecessary features reflecting, e.g., the author's preferred means of viewing documentation. Don't do that. If it is a foreground command line tool, your normal output should be to the standard output stream and error to the standard error stream. Don't get crazy.

If you are unaware of "here" documents, this can simplify the task for you and keep the source tidier and more readable:

#!/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        

Notice there's a function called for the help option, which keeps the if block tidy. It also means you can put that function at the top, making it an obvious form of reference to the source itself.

You can indent the here doc in myHelp(), BTW -- tabs are ignored, but spaces are preserved. I did it that way here to prevent any confusing outcomes from cut n' paste.

share|improve this answer
    
Thank you, I used a function but with a echo -e for coloring and using tabs. –  MrVaykadji Mar 25 at 23:30

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.