subcommand: Fix and document return value of gsu_complete_options().

[gsu.git] / README.md

diff --git a/README.md b/README.md
index a0417d171e93ad6b20b8e56a93b5085bbffe5c6e..0d2c9e236bf437c711cf1e26aa22f6777eeff179 100644 (file)
--- a/README.md
+++ b/README.md
@@ -14,11 +14,11 @@ gsu is very easy to install:
 ___Requirements___
 
 gsu is implemented in bash, and thus gsu depends on bash. Bash version
-3 is required, version 4 is recommended. Besides bash, gsu depends
-only on programs which are usually installed on any Unix system (awk,
-grep, sort, ...). Care has been taken to not rely on GNU specific
-behavior of these programs, so it should work on non GNU systems
-(MacOS, FreeBSD, NetBSD) as well. The gui module depends on the dialog utility.
+4.3 is required. Besides bash, gsu depends only on programs which are
+usually installed on any Unix system (awk, grep, sort, ...). Care has
+been taken to not rely on GNU specific behavior of these programs,
+so it should work on non GNU systems (MacOS, FreeBSD, NetBSD) as
+well. The gui module depends on the dialog utility.
 
 ___Download___
 
@@ -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:
@@ -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___
 
@@ -698,6 +709,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 +727,3 @@ 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)