X-Git-Url: http://git.tuebingen.mpg.de/?a=blobdiff_plain;f=README.md;h=44e111fb00b363f848bb72d36596163d5329e519;hb=HEAD;hp=58d28a0c8d93e0df6608cad1f881cae8c2aa2080;hpb=78e27762f692e7896614450bbe9e06140c7694af;p=gsu.git diff --git a/README.md b/README.md index 58d28a0..bd4bf13 100644 --- a/README.md +++ b/README.md @@ -24,9 +24,9 @@ ___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___ @@ -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" @@ -420,23 +431,27 @@ contents of the kernel log buffer. Bash code which defines the menu 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___ @@ -452,7 +467,7 @@ handler for the `df` node: } 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. @@ -472,7 +487,7 @@ as follows. local username gsu_inputbox 'Enter username' "$LOGNAME" - (($ret != 0)) && return + ((ret != 0)) && return 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___ -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=' - 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() @@ -515,7 +530,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 +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. +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 +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_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 +738,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](https://people.tuebingen.mpg.de/maan/)