gui: Don't show items in menus.

[gsu.git] / README.md

diff --git a/README.md b/README.md
index a0417d171e93ad6b20b8e56a93b5085bbffe5c6e..1fbcef9872ce9f5ef0ae6bb642d8a501993f448b 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
 ___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___
 
 
 ___Download___
 


@@ -127,28 +127,34 @@ Example:
                        echo 'hello world'
                }
 
                        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,
 
 - 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.
                ##
 
                com_world()
                ##
                ## Print the string "hello world" to stdout.
                ##

-               ## Usage: world
+               ## Usage: world [-v]

                ##
                ## Any arguments to this function are ignored.
                ##
                ##
                ## 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.
                {
                ## 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:
                }
 
 Replace `hello` with the above and try:


@@ -263,7 +269,7 @@ for `gsu_getopts()` as follows:
 
                        gsu_getopts 't:v'
                        eval "$result"
 
                        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
 
                        [[ -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
                com_world()
                {
                        gsu_check_arg_count $# 0 0 # no arguments allowed

-                       (($ret < 0)) && return
+                       ((ret < 0)) && return

                        echo 'hello world'
                }
 
                        echo 'hello world'
                }
 


@@ -318,12 +324,17 @@ Example:
 
 ___HTML output___
 
 
 ___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___
 
 
 ___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 "$@"
                        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"
 
                        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"
                        local username
 
                        gsu_inputbox 'Enter username' "$LOGNAME"

-                       (($ret != 0)) && return
+                       ((ret != 0)) && return

                        username="$result"
                        gsu_msgbox "$(pgrep -lu "$username")"
                }
                        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"
                        local username
 
                        gsu_inputbox 'Enter username' "$LOGNAME"

-                       (($ret < 0)) && return
+                       ((ret < 0)) && return

                        username="$result"
                        gsu_msgbox "$(pgrep -lu "$username")"
                }
                        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.
 
 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:
 ___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_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.
 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)
 ----------
 - [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/)