X-Git-Url: http://git.tuebingen.mpg.de/?a=blobdiff_plain;f=README.md;h=1fbcef9872ce9f5ef0ae6bb642d8a501993f448b;hb=refs%2Fheads%2Fpu;hp=58d28a0c8d93e0df6608cad1f881cae8c2aa2080;hpb=78e27762f692e7896614450bbe9e06140c7694af;p=gsu.git

diff --git a/README.md b/README.md
index 58d28a0..1fbcef9 100644
--- a/README.md
+++ b/README.md
@@ -127,28 +127,34 @@ Example:
 			echo 'hello world'
 		}
 
-The subcommand documentation consists of three parts:
+The subcommand documentation consists of the following parts:
 
 - The summary. One line of text,
 - the usage/synopsis string,
-- free text section.
+- free text section 1,
+- options (if any),
+- free text section 2.
 
-The three parts should be separated by lines consisting of two `#` characters
-only. Example:
+The last three parts are optional. All parts should be separated by
+lines consisting of two `#` characters only. Example:
 
 		com_world()
 		##
 		## Print the string "hello world" to stdout.
 		##
-		## Usage: world
+		## Usage: world [-v]
 		##
 		## Any arguments to this function are ignored.
 		##
+		## -v: Enable verbose mode
+		##
 		## Warning: This subcommand may cause the top most line of your terminal to
 		## disappear and may cause DATA LOSS in your scrollback buffer. Use with
 		## caution.
 		{
-			echo 'hello world'
+			printf 'hello world'
+			[[ "$1" == '-v' ]] && printf '!'
+			printf '\n'
 		}
 
 Replace `hello` with the above and try:
@@ -263,7 +269,7 @@ for `gsu_getopts()` as follows:
 
 			gsu_getopts 't:v'
 			eval "$result"
-			(($ret < 0)) && return
+			((ret < 0)) && return
 
 			[[ -z "$o_t" ]] && o_t='ext3' # default to ext3 if -t is not given
 			[[ "$o_v" == 'true' ]] && awk_field=0 # $0 is the whole line
@@ -289,7 +295,7 @@ print an error message if one or more arguments are given. With
 		com_world()
 		{
 			gsu_check_arg_count $# 0 0 # no arguments allowed
-			(($ret < 0)) && return
+			((ret < 0)) && return
 			echo 'hello world'
 		}
 
@@ -318,12 +324,17 @@ Example:
 
 ___HTML output___
 
-The output of the auto-generated man subcommand is a suitable input for the
-grutatxt plain text to html converter. Hence
+The auto-generated man subcommand produces plain text, html, or
+roff output.
+
+		./hello man -m html > index.html
 
-		./hello man | grutatxt > index.html
+is all it takes to produce an html page for your
+application. Similarly,
 
-is all it takes to produce an html page for your application.
+		./hello man -m roff > hello.1
+
+creates a manual page.
 
 ___Interactive completion___
 
@@ -355,7 +366,7 @@ Let's have a look at the completer for the above `fs` subcommand.
 			local optstring='t:v'
 
 			gsu_complete_options $optstring "$@"
-			(($ret > 0)) && return
+			((ret > 0)) && return
 
 			gsu_cword_is_option_parameter $optstring "$@"
 			[[ "$result" == 't' ]] && awk '{print $3}' "$f"
@@ -472,7 +483,7 @@ as follows.
 			local username
 
 			gsu_inputbox 'Enter username' "$LOGNAME"
-			(($ret != 0)) && return
+			((ret != 0)) && return
 			username="$result"
 			gsu_msgbox "$(pgrep -lu "$username")"
 		}
@@ -515,7 +526,7 @@ sure to not turn tab characters into space characters.
 			local username
 
 			gsu_inputbox 'Enter username' "$LOGNAME"
-			(($ret < 0)) && return
+			((ret < 0)) && return
 			username="$result"
 			gsu_msgbox "$(pgrep -lu "$username")"
 		}
@@ -640,6 +651,13 @@ following two statements are equivalent
 If an option is set both in the environment and in the config file,
 the environment takes precedence.
 
+The `$gsu_config_file` variable can actually contain more than one
+filename, separated by spaces. The config files are processed in
+order, so that an option that is specified in the second config file
+overwrites the definition given in the first. This is useful for
+applications which implement a system-wide config file in addition
+to a per-user config file.
+
 ___Checking config options___
 
 The gsu config module defines two public functions for this purpose:
@@ -698,6 +716,10 @@ Defaults to `~/.${gsu_name}.rc`.
 - `$gsu_config_var_prefix`. Used by the config module to set up
 the variables defined in `$gsu_options`.
 
+- `$gsu_package`. Text shown at the bottom left of the man page,
+usually the name and version number of the software package. Defaults
+to `$gsu_name`.
+
 License
 -------
 gsu is licensed under the  GNU LESSER GENERAL PUBLIC LICENSE (LGPL), version 3.
@@ -712,4 +734,4 @@ References
 ----------
 - [bash](http://www.gnu.org/software/bash/bash.html)
 - [dialog](http://www.invisible-island.net/dialog/dialog.html)
-- [grutatxt](http://triptico.com/software/grutatxt.html)
+- [The author's home page](http://people.tuebingen.mpg.de/maan/)