Formatted help with here documents (proposal)

[accetto]

The problem with help texts in argbash is, that they must be inside shell comments. It makes their formatting really hard. However, I've found out, that using here documents is actually possible, so I'm already using it for some time. The argbash generates quite usable results out-of-the-box and I'm almost sure, that @matejak can further improve it.

This could be also partially related to the issue #82.

Let's look at some example.

I've generated a simple script scrap.sh. This is the beginning of the file:

#!/bin/bash

# Created by argbash-init v2.10.0
# ARG_HELP([<The general help message of my script>],[
<< ---
This is a formatted long description:

Some list can come here:
    - item 1
    - item 2

Yet another list:
    (1) remark 1
    (2) remark 2

Maybe some closing hints too.
---
#])
# ARGBASH_GO()
# needed because of Argbash --> m4_ignore([
### START OF CODE GENERATED BY Argbash v2.10.0 one line above ###
# Argbash is a bash code generator used to get arguments parsing right.
# Argbash is FREE SOFTWARE, see https://argbash.io for more info

and this is the help output:

utils> ./scrap.sh -h
<The general help message of my script>
Usage: ./scrap.sh [-h|--help]
        -h, --help: Prints help

<< ---
This is a formatted long description:

Some list can come here:
        - item 1
        - item 2

Yet another list:
        (1) remark 1
        (2) remark 2

Maybe some closing hints too.
---
#

It's already pretty acceptable, but with some changes in the generated code it could be even better.

This is the generated print_help() procedure:

print_help()
{
    printf '%s\n' "<The general help message of my script>"
    printf 'Usage: %s [-h|--help]\n' "$0"
    printf '\t%s\n' "-h, --help: Prints help"
    printf '\n%s\n' "
<< ---
This is a formatted long description:

Some list can come here:
    - item 1
    - item 2

Yet another list:
    (1) remark 1
    (2) remark 2

Maybe some closing hints too.
---
#"
}

However, if it would look like this:

print_help()
{
    printf '%s\n' "<The general help message of my script>"
    printf 'Usage: %s [-h|--help]\n' "$0"
    printf '\t%s\n' "-h, --help: Prints help"
    cat << ---

This is a formatted long description:

Some list can come here:
    - item 1
    - item 2

Yet another list:
    (1) remark 1
    (2) remark 2

Maybe some closing hints too.
---
}

then the help output would be much nicer:

utils> ./scrap.sh -h
<The general help message of my script>
Usage: ./scrap.sh [-h|--help]  
        -h, --help: Prints help

This is a formatted long description:

Some list can come here:
        - item 1
        - item 2

Yet another list:
        (1) remark 1
        (2) remark 2

Maybe some closing hints too.

Unfortunatelly I have no M4 skill, so I cannot offer an implementation proposal, but maybe @matejak could find something out?

[matejak]

I see what I can do, your proposal is really intriguing.