Parsing heredoc comments in BASH script

There's no practical difference in terms of difficulty of extracting the information. The comments have a mild benefit of not being executable, so there's a marginal performance benefit to not creating the $DESCRIPTION variable, but you'd be hard pressed to measure it.

Of course, there's the additional issue that the syntax shown for the heredoc isn't valid shell. You'd need to think in terms of:

cat >/dev/null <<EOD
...
EOD

or perhaps (but perhaps not — unless you want to use $DESCRIPTION in the script itself):

DESCRIPTION=$(cat <<EOD
...
EOD
)

or, perhaps better still:

: DESCRIPTION = <<EOD
...
EOD

The colon command is a no-op; it evaluates its arguments and succeeds. I prefer this to either of the cat variants. The DESCRIPTION and = arguments are noise words; you could omit either or both without affecting the script. You would probably want to think about using quotes around the first EOD too:

: <<'EOD'
...$(cat this is not executed)...
EOD

Note that the : command and first cat alternatives do not initialize the shell variable $DESCRIPTION. If that's important, you're stuck with the command substitution $(...) version, noting that there are two lines marking the end of the assignment.

Let your description lines begin with a unique identifier, something like this:

(for example we take the characters: #> )

#!/bin/bash

#> This is a description header
#> 
#> This program will do z, y and X
#> because I want that

# this is normal comment

.... rest of program 
or some other stuff

To get your description:

grep "^#>" myscript.sh

will result in:

#> This is a description header
#> 
#> This program will do z, y and X
#> because I want that

This is way easier than trying to get:

1. a variable out of a document (which can only be done by partly sourcing it....which is another can of worms.)

2. Trying to retrive the part between (EOD) markers

3. Trying to heuristically determine which is comment or which is description.

The idea of having a variable that contains a description is very interesting.

The best way to retreive it from the program is to have the program print it for you. Don't work with anything other than just single or double quotes because that is the only way to incorporate linebreaks in your variable. We can also bypass the need for a variable by echoing the string directly.

You could have:

#!/bin/bash
#---------------------------------
[ "$1" = "DESCRIPTION" ] && echo '

Hello,

This nifty script does x, y and sometimes z
The nice thing is that linebreaks will be preserved.
This makes it as useful as a here document

you can choose between single or double quotes

' && exit
#---------------------------------

rest of script...

It does not look very pretty (though not bad either) but retreiving the description is extremely simple and without extra tools:

scriptname.sh DESCRIPTION