Improved help messages (fixes #7)

doc/guide.rst

@@ -241,7 +241,7 @@ Special arguments
   This will generate the ``--help`` and ``-h`` action arguments that will print the usage information.
   Notice that the usage information is generated even if this macro is not used --- we print it when we think that there is something wrong with arguments that were passed.
 
-  The long program desription is a string passed to ``printf`` (so you may use ``\n`` to make it multiline etc.).
+  The long program desription is a string quoted in double quotation marks (so you may use environmental variables in it) and additionally, occurences of ``\n`` will be translated to a line break with indentation (use ``\\n`` to have the actual ``\n`` in the help description).
 
 * Version argument (a special case of an action argument):
   ::

src/stuff.m4

@@ -47,6 +47,11 @@ m4_define([argbash_api], [_argbash_persistent([$1], [$2])])
 m4_define([_argbash_persistent], [m4_set_add([_KNOWN_MACROS],[$1])m4_define([$1], [$2])])
 dnl IDEA: Assemble a whitelist of macros used in the script, then grep the source and report all suspicious strings that resemble misspelled argbash macros
 
+dnl
+dnl $1: The text to substitute
+dnl Regexp: Find beginning of backslashes, match for pairs, and if \\n is left, then substitute it for literal newline.
+m4_define([_SUBSTITUTE_LF_FOR_NEWLINE], [m4_bpatsubst([[$1]], [\([^\\]\)\(\\\\\)*\\n],  [\1\2
+		])])
 
 dnl
 dnl Checks that the n-th argument is an integer.
@@ -831,7 +836,7 @@ m4_define([_MAKE_HELP], [m4_do(
 ],
 			[m4_pushdef([argname1], <m4_dquote(argname0)[[]m4_ifnblank(m4_quote($][1), m4_quote(-$][1))]>)],
 			[m4_pushdef([argname], m4_if(_arg_type, [inf], [m4_default(_INF_REPR, argname1)], [[argname1($][@)]]))],
-			[_INDENT_()[printf "\t%s\n" "]argname[: ]_msg],
+			[_INDENT_()[printf "\t%s\n" "]argname[: ]_SUBSTITUTE_LF_FOR_NEWLINE(_msg)],
 			[_POS_ARG_HELP_DEFAULTS([argname], _arg_type, _min_argn, _defaults)],
 			[m4_popdef([argname])],
 			[m4_popdef([argname1])],
@@ -858,7 +863,7 @@ m4_define([_MAKE_HELP], [m4_do(
 			[dnl Bool have a long beginning with --no-
 ],
 			[m4_case(_arg_type, [bool], [,--no-]_argname)],
-			[: _arg_help],
+			[: _SUBSTITUTE_LF_FOR_NEWLINE(_arg_help)],
 			[dnl Actions don't have defaults
 ],
 			[dnl WAS: We format defaults help by print-quoting them with ' and stopping the help echo quotes " before the store value is subsittuted, so the message should really match the real default.

tests/regressiontests/Makefile

@@ -228,6 +228,13 @@ test-ddash: $(TESTDIR)/test-ddash.sh
 test-simple: $(TESTDIR)/test-simple.sh
 	$< pos | grep -q 'OPT_S=x,POS_S=pos,'
 	$< pos -o 'uf ta' | grep -q 'OPT_S=uf ta,POS_S=pos,'
+	$< -h | grep -q 'END-$$'
+	$< -h | grep -q '^\s*-BEGIN'
+	$< -h | grep -q '^		-BEGIN'
+	$< -h | grep -q -v '^\s*-BEGIN2'
+	$< -h | grep -q -v 'END2-$$'
+	$< -h | grep -q '^		-PBEGIN'
+	$< -h | grep -q 'PEND-$$'
 	ERROR=spurious 	$(REVERSE) $< -- one two
 	ERROR="last one was: 'two'" 	$(REVERSE) $< one two
 	ERROR="expect exactly 1" 	$(REVERSE) $< one two

tests/regressiontests/make/tests/tests-base.m4

@@ -85,6 +85,13 @@ ADD_TEST([test-ddash], [[
 ADD_TEST([test-simple], [[
 	$< pos | grep -q 'OPT_S=x,POS_S=pos,'
 	$< pos -o 'uf ta' | grep -q 'OPT_S=uf ta,POS_S=pos,'
+	$< -h | grep -q 'END-$$'
+	$< -h | grep -q '^\s*-BEGIN'
+	$< -h | grep -q '^		-BEGIN'
+	$< -h | grep -q -v '^\s*-BEGIN2'
+	$< -h | grep -q -v 'END2-$$'
+	$< -h | grep -q '^		-PBEGIN'
+	$< -h | grep -q 'PEND-$$'
 	ERROR=spurious 	$(REVERSE) $< -- one two
 	ERROR="last one was: 'two'" 	$(REVERSE) $< one two
 	ERROR="expect exactly 1" 	$(REVERSE) $< one two

tests/regressiontests/test-simple.m4

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# ARG_POSITIONAL_SINGLE([pos-arg],[@pos-arg@])
-# ARG_OPTIONAL_SINGLE([prefix],[o],[],[x])
+# ARG_POSITIONAL_SINGLE([pos-arg], [help line PEND-\n-PBEGIN])
+# ARG_OPTIONAL_SINGLE([prefix],[o],[help line END-\n-BEGIN line 2END-\\n-2BEGIN],[x])
 # ARG_VERSION([echo $0 FOO])
 # ARG_HELP([Testing program m4_fatal(BOOM!)], [m4_fatal([CRASH!])])
 # ARGBASH_GO()