.TH grml-quickconfig 8
.SH "NAME"
grml-quickconfig \- get fast access to some basic grml-scripts
.SH SYNOPSIS
.B grml-quickconfig [menudir]
.SH DESCRIPTION
This manual page documents briefly the
.B grml-quickconfig
command.
.SH OPTIONS
.TP
.B menudir
Directory to load the menu files from. Menu files have to end with '*.sh'.

If menudir is an existing directory then files will be directly loaded from
the specified directory. If it is not a directory it will be loaded from
.B /usr/share/grml-quickconfig/MENUDIR/
instead (if present).

If no option is provided the bootparameter
.B menu
(if present) is used as directory.

If neither a commandline parameter nor a bootparameter is specified it will load the menu files from the default location
.B /usr/share/grml-quickconfig

If there exists a directory called
.B local
inside the default location it will be used for loading the menue.
.SH Determining menu directory:
.IP \(bu
Command  line argument
.IP \(bu
boot parameter menu
.IP \(bu
.B /usr/share/grml-quickconfig/local/
(if present)
.IP \(bu
.B /usr/share/grml-quickconfig/


.SH NOTES
grml-quickconfig provides a console based interface to get fast
access to some basic grml-scripts like for example grml-network,
netcardconfig, grml-lang, grml-x and grml-debootstrap.
.SH USAGE EXAMPLES
.TP
.B grml-quickconfig
Invoke the interface.
.TP
.B grml-quickconfig /opt/my_menu/
Invoke the interface and load all files ending with '*.sh'.
.TP
.B grml-quickconfig network
Test if 'network' is a directory (in the current working directory) and load all files ending with *.sh
from it. If it is not a valid directory
.B /usr/share/grml-quickconfig/network/
is used instead.
.SH Writing own menu entries
A menu script is a shell script with some necessary information described in this section.

.SS API
The following predefined functions are available to write a script displaying a menu entry:
.TP
.B print_line text
Print the text in one line inside the menu.
.TP
.B print_starting_line
Print the first line for a menu.
.TP
.B print_closing_line
Print the closing line for a menu.
.TP
.B print_delim
Print a delimiter line for a menu.
.TP
.B run COMMAND
Print command and then execute it.
.TP
.B get_key VARIABLE_NAME
Get one key from user.
.TP
.B Example

 # get user input
   get_key INPUT
   [ "$INPUT" == "c" ] && echo "C pressed"

 # print && execute grml-lang de
   run grml-lang de

.SS Predefined Variables
The following variables are predefined and could be used in a menu script:
.TP
.B NORMAL
Switch back to normal color
.TP
.B HIGHLIGHT
Highlight the used key inside the menu.
.TP
.B Example
 print_line "Configure ${HIGHLIGHT}n${NORMAL}etwork"

.SS Shortcuts
As highlighting the name as well as the keyboard shortcuts is common
in a menu entry there are two shortcuts for highlighting.
.SS Highlight a single character
To highlight a single character, for example the shortcut, use
.B ^
and the next character will be highlighted. If you want to just write ^ escape the
character with a backslash.
 print_line "Configure ^network \\^ is nice"
.SS Highlight a word
To highlight a range, for example the command, use
.B /word/
and the text between / wll be highlighted. If you want to just write / escape the
character with a backslash.
 print_line "Configure ^network (/grml-network/)"
.SS MUST Provide
.TP
.B display_entry
A function named display_entry to determine if this entry shall be displayed.
.LP
.RS
.B Example
.LP
# Always display menu item
  display_entry() { return 0 }

# Only display menu item if specified program is available
  display_entry() {
      . /etc/grml/script-functions
      check4progs PROGRAM >/dev/null
      return $?
  }

.RE 1
.TP
.B LINE
A variable used to determine what shall be done to generate a menu entry. Typically
used in combination with print_line. Only used if display_entry returns 0.
.LP
.RS
.B \ Example
 # print Configure network (grml-network)
 LINE='print_line "Configure ^network (/grml-network/)"'
.RE 1
.SS Optional entries
The following variables are optional and can be defined in a script but do not have to.
.TP
.B FUNCTION
A variable specifying the code which should be executed if user selects this menu entry.
The variable $INPUT can be used to get the user input.
.RS
.B \ Example
 # Print the key from the user
 FUNCTION='echo $INPUT'

 # create a submenu
 submenu() { ... }
 FUNCTION='submenu'
.RE 1

.TP
.B KEY, array
An array containing all possible keys for executing the code specified in the FUNCTION variable, e.g:
.RS
 # execute code in FUNCTION if c, d or e is pressed.
KEY=(c d e)

.SS Complete Example
 # language module for grml-quickconfig
 LINE='print_line "Set keyboard layout (/grml-lang/): ^de ^at ^ch e^s ^us"'

 typeset -A lang_mapping

 # map keys to language
 lang_mapping=(
     d de
     a at
     c ch
     s es
     u us
 )

 # get all keys from assoc array
 KEY=(${(k)lang_mapping})

 # $INPUT is the user input
 FUNCTION='run grml-lang ${lang_mapping[$INPUT]}'

 # always display entry
 display_entry() {
     return 0
 }

 ## END OF FILE #################################################################
 # vim:foldmethod=marker expandtab ai ft=zsh shiftwidth=3

.SH AUTHOR
grml-quickconfig was written by the Grml Team <team@grml.org> and is based on the
idea of Michael Schierl <schierlm-public@gmx.de>.
.PP
This manual page was written by Ulrich Dangel <mru@grml.org> and Michael Prokop
<mika@grml.org> for the Grml project (but may be used by others).