gui: Implement descriptive tree items.

[gsu.git] / README.md

diff --git a/README.md b/README.md
index a0417d171e93ad6b20b8e56a93b5085bbffe5c6e..bd4bf13ae1f12ae6ad2faaf6fb634c2604d21f23 100644 (file)
--- a/README.md
+++ b/README.md
@@ -14,19 +14,19 @@ 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___
 
 All gsu modules are contained in a git repository. Get a copy with
 
 
 ___Download___
 
 All gsu modules are contained in a git repository. Get a copy with
 

-               git clone git://git.tuebingen.mpg.de/gsu.git
+               git clone https://git.tuebingen.mpg.de/gsu.git

 
 

-There is also a [gitweb](http://git.tuebingen.mpg.de/gsu.git) page.
+There is also a [gitweb](https://git.tuebingen.mpg.de/gsu.git) page.

 
 ___Installation___
 
 
 ___Installation___
 


@@ -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"


@@ -420,23 +431,27 @@ contents of the kernel log buffer. Bash code which defines the menu
 tree could look like this:
 
                menu_tree='
 tree could look like this:
 
                menu_tree='

-                       load_average
-                       processes
-                       hardware/
-                               cpu
-                               scsi
-                       storage/
-                               df
-                               mdstat
-                       log/
-                               syslog
-                               dmesg
+                       load_average System load
+                       processes Running processes of a user
+                       hardware/ Hardware related information
+                               cpu Show prozessor type and features
+                               scsi Show SCSI devices
+                       storage/ Filesystems and software raid
+                               df List of mounted filesystems
+                               mdstat Status of software raid arrays
+                       log/ System and kernel logs
+                               syslog System log
+                               dmesg Kernel log

                '
 
                '
 

-In this tree, `hardware/`, `block_devices/` and `log/` are the only
-internal nodes. Note that these are written with a trailing slash
-character while the leaf nodes have no slash at the end. All entries
-of the menu tree must be indented by tab characters.
+Each line of the menu tree consists of an identifier, suffixed with an
+optional slash, and a description. The identifier becomes part of the
+name of a bash function and should only contain alphabetic characters
+and underscores. The description becomes the text shown as the menu
+item. Identifiers suffixed with a slash are regarded as internal nodes
+which represent submenus. In the above tree, `hardware/`, `storage/`
+and `log/` are internal nodes. All entries of the menu tree must be
+properly indented by tab characters.

 
 ___Action handlers___
 
 
 ___Action handlers___
 


@@ -452,7 +467,7 @@ handler for the `df` node:
                }
 
 The function name `lsi_df` is derived from the name of the script
                }
 
 The function name `lsi_df` is derived from the name of the script

-(`lsi`) and the name of the leaf node (`df`). The function simply
+(`lsi`) and the identifier of the leaf node (`df`). The function simply

 passes the output of the `df(1)` command as the first argument to the
 public gsu function `gsu_msgbox()` which runs dialog(1) to display
 a message box that shows the given text.
 passes the output of the `df(1)` command as the first argument to the
 public gsu function `gsu_msgbox()` which runs dialog(1) to display
 a message box that shows the given text.


@@ -472,7 +487,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")"
                }


@@ -485,24 +500,24 @@ to do is to source the gsu gui module and to call `gsu_gui()`:
 
 ___Example___
 
 
 ___Example___
 

-The complete lsi script below can be used as a starting point
-for your own gsu gui application. If you cut and paste it, be
-sure to not turn tab characters into space characters.
+The complete lsi script below can be used as a starting point for your
+own gsu gui application. If you cut and paste it, be sure to not turn
+tab characters into space characters. The script must be named "lsi".

 
                #!/bin/bash
 
                menu_tree='
 
                #!/bin/bash
 
                menu_tree='

-                       load_average
-                       processes
-                       hardware/
-                               cpu
-                               scsi
-                       storage/
-                               df
-                               mdstat
-                       log/
-                               syslog
-                               dmesg
+                       load_average System load
+                       processes Running processes of a user
+                       hardware/ Hardware related information
+                               cpu Show prozessor type and features
+                               scsi Show SCSI devices
+                       storage/ Filesystems and software raid
+                               df List of mounted filesystems
+                               mdstat Status of software raid arrays
+                       log/ System and kernel logs
+                               syslog System log
+                               dmesg Kernel log

                '
 
                lsi_load_average()
                '
 
                lsi_load_average()


@@ -515,7 +530,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 +655,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 +720,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 +738,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](https://people.tuebingen.mpg.de/maan/)