grml-quickconfig.8

   1 .TH grml-quickconfig 8
   2 .SH "NAME"
   3 grml-quickconfig \- get fast access to some basic grml-scripts
   4 .SH SYNOPSIS
   5 .B grml-quickconfig [menudir]
   6 .SH DESCRIPTION
   7 This manual page documents briefly the
   8 .B grml-quickconfig
   9 command.
  10 .SH OPTIONS
  11 .TP
  12 .B menudir
  13 Directory to load the menu files from. Menu files have to end with '*.sh'.
  14
  15 If menudir is an existing directory then files will be directly loaded from
  16 the specified directory. If it is not a directory it will be loaded from
  17 .B /usr/share/grml-quickconfig/MENUDIR/
  18 instead (if exists).
  19
  20 If no option is provided the bootparameter
  21 .B menu
  22 (if present) is used as directory.
  23 .SH NOTES
  24 grml-quickconfig provides a console based interface to get fast
  25 access to some basic grml-scripts like for example grml-network,
  26 netcardconfig, grml-lang, grml-x and grml2hd.
  27 .SH USAGE EXAMPLES
  28 .TP
  29 .B grml-quickconfig
  30 Invoke the interface.
  31 .TP
  32 .B grml-quickconfig /opt/my_menu/
  33 Invoke the interface and load all files ending with '*.sh'.
  34 .TP
  35 .B grml-quickconfig network
  36 Test if 'network' is a directory (in the current working directory) and load all files ending with *.sh
  37 from it. If it is not a valid directory
  38 .B /usr/share/grml-quickconfig/network/
  39 is used instead.
  40 .SH Writing own menu entries
  41 A menu script is a shell script with some necessary information described in this section.
  42
  43 .SS API
  44 The following predefined functions are available to write a script displaying a menu entry:
  45 .TP
  46 .B print_line text
  47 Print the text in one line inside the menu.
  48 .TP
  49 .B print_starting_line
  50 Print the first line for a menu.
  51 .TP
  52 .B print_closing_line
  53 Print the closing line for a menu.
  54 .TP
  55 .B print_delim
  56 Print a delimiter line for a menu.
  57 .TP
  58 .B run COMMAND
  59 Print command and then execute it.
  60 .TP
  61 .B get_key VARIABLE_NAME
  62 Get one key from user.
  63 .TP
  64 .B Example
  65
  66  # get user input
  67    get_key INPUT
  68    [ "$INPUT" == "c" ] && echo "C pressed"
  69
  70  # print && execute grml-lang de
  71    run grml-lang de
  72
  73 .SS Predefined Variables
  74 The following variables are predefined and could be used in a menu script:
  75 .TP
  76 .B NORMAL
  77 Switch back to normal color
  78 .TP
  79 .B HIGHLIGHT
  80 Highlight the used key inside the menu.
  81 .TP
  82 .B Example
  83  print_line "Configure ${HIGHLIGHT}n${NORMAL}etwork"
  84 .SS MUST Provide
  85 .TP
  86 .B display_entry
  87 A function named display_entry to determine if this entry shall be displayed.
  88 .LP
  89 .RS
  90 .B Example
  91 .LP
  92 # Always display menu item
  93   display_entry() { return 0 }
  94
  95 # Only display menu item if specified program is available
  96   display_entry() {
  97       . /etc/grml/script-functions
  98       check4progs PROGRAM >/dev/null
  99       return $?
 100   }
 101
 102 .RE 1
 103 .TP
 104 .B LINE
 105 A variable used to determine what shall be done to generate a menu entry. Typically
 106 used in combination with print_line. Only used if display_entry returns 0.
 107 .LP
 108 .RS
 109 .B \ Example
 110  # print Configure network (grml-network)
 111  LINE='print_line "Configure ${HIGHLIGHT}n${NORMAL}etwork (${HIGHLIGHT_NAME}grml-network${NORMAL})"'
 112 .RE 1
 113 .SS Optional entries
 114 The following variables are optional and can be defined in a script but do not have to.
 115 .TP
 116 .B FUNCTION
 117 A variable specifying the code which should be executed if user selects this menu entry.
 118 The variable $INPUT can be used to get the user input.
 119 .RS
 120 .B \ Example
 121  # Print the key from the user
 122  FUNCTION='echo $INPUT'
 123
 124  # create a submenu
 125  submenu() { ... }
 126  FUNCTION='submenu'
 127 .RE 1
 128
 129 .TP
 130 .B KEY, array
 131 An array containing all possible keys for executing the code specified in the FUNCTION variable, e.g:
 132 .RS
 133  # execute code in FUNCTION if c, d or e is pressed.
 134 KEY=(c d e)
 135
 136 .SS Complete Example
 137  # language module for grml-quickconfig
 138  LINE='print_line "Set keyboard layout (${HIGHLIGHT_NAME}grml-lang${NORMAL}): \\
 139  ${HIGHLIGHT}d${NORMAL}e ${HIGHLIGHT}a${NORMAL}t ${HIGHLIGHT}c${NORMAL}h e${HIGHLIGHT}s${NORMAL} ${HIGHLIGHT}u${NORMAL}s"'
 140
 141  typeset -A lang_mapping
 142
 143  # map keys to language
 144  lang_mapping=(
 145      d de
 146      a at
 147      c ch
 148      s es
 149      u us
 150  )
 151
 152  # get all keys from assoc array
 153  KEY=(${(k)lang_mapping})
 154
 155  # $INPUT is the user input
 156  FUNCTION='run grml-lang ${lang_mapping[$INPUT]}'
 157
 158  # always display entry
 159  display_entry() {
 160      return 0
 161  }
 162
 163  ## END OF FILE #################################################################
 164  # vim:foldmethod=marker expandtab ai ft=zsh shiftwidth=3
 165
 166 .SH AUTHOR
 167 grml-quickconfig was written by the Grml Team <team@grml.org> and is based on the
 168 idea of Michael Schierl <schierlm-public@gmx.de>.
 169 .PP
 170 This manual page was written by Ulrich Dangel <mru@grml.org> and Michael Prokop
 171 <mika@grml.org> for the Grml project (but may be used by others).