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 present).
  19
  20 If no option is provided the bootparameter
  21 .B menu
  22 (if present) is used as directory.
  23
  24 If neither a commandline parameter nor a bootparameter is specified it will load the menu files from the default location
  25 .B /usr/share/grml-quickconfig
  26
  27 If there exists a directory called
  28 .B local
  29 inside the default location it will be used for loading the menue.
  30 .SH Determining menu directory:
  31 .IP \(bu
  32 Command  line argument
  33 .IP \(bu
  34 boot parameter menu
  35 .IP \(bu
  36 .B /usr/share/grml-quickconfig/local/
  37 (if present)
  38 .IP \(bu
  39 .B /usr/share/grml-quickconfig/
  40
  41
  42 .SH NOTES
  43 grml-quickconfig provides a console based interface to get fast
  44 access to some basic grml-scripts like for example grml-network,
  45 netcardconfig, grml-lang, grml-x and grml-debootstrap.
  46 .SH USAGE EXAMPLES
  47 .TP
  48 .B grml-quickconfig
  49 Invoke the interface.
  50 .TP
  51 .B grml-quickconfig /opt/my_menu/
  52 Invoke the interface and load all files ending with '*.sh'.
  53 .TP
  54 .B grml-quickconfig network
  55 Test if 'network' is a directory (in the current working directory) and load all files ending with *.sh
  56 from it. If it is not a valid directory
  57 .B /usr/share/grml-quickconfig/network/
  58 is used instead.
  59 .SH Writing own menu entries
  60 A menu script is a shell script with some necessary information described in this section.
  61
  62 .SS API
  63 The following predefined functions are available to write a script displaying a menu entry:
  64 .TP
  65 .B print_line text
  66 Print the text in one line inside the menu.
  67 .TP
  68 .B print_starting_line
  69 Print the first line for a menu.
  70 .TP
  71 .B print_closing_line
  72 Print the closing line for a menu.
  73 .TP
  74 .B print_delim
  75 Print a delimiter line for a menu.
  76 .TP
  77 .B run COMMAND
  78 Print command and then execute it.
  79 .TP
  80 .B get_key VARIABLE_NAME
  81 Get one key from user.
  82 .TP
  83 .B Example
  84
  85  # get user input
  86    get_key INPUT
  87    [ "$INPUT" == "c" ] && echo "C pressed"
  88
  89  # print && execute grml-lang de
  90    run grml-lang de
  91
  92 .SS Predefined Variables
  93 The following variables are predefined and could be used in a menu script:
  94 .TP
  95 .B NORMAL
  96 Switch back to normal color
  97 .TP
  98 .B HIGHLIGHT
  99 Highlight the used key inside the menu.
 100 .TP
 101 .B Example
 102  print_line "Configure ${HIGHLIGHT}n${NORMAL}etwork"
 103
 104 .SS Shortcuts
 105 As highlighting the name as well as the keyboard shortcuts is common
 106 in a menu entry there are two shortcuts for highlighting.
 107 .SS Highlight a single character
 108 To highlight a single character, for example the shortcut, use
 109 .B ^
 110 and the next character will be highlighted. If you want to just write ^ escape the
 111 character with a backslash.
 112  print_line "Configure ^network \\^ is nice"
 113 .SS Highlight a word
 114 To highlight a range, for example the command, use
 115 .B /word/
 116 and the text between / wll be highlighted. If you want to just write / escape the
 117 character with a backslash.
 118  print_line "Configure ^network (/grml-network/)"
 119 .SS MUST Provide
 120 .TP
 121 .B display_entry
 122 A function named display_entry to determine if this entry shall be displayed.
 123 .LP
 124 .RS
 125 .B Example
 126 .LP
 127 # Always display menu item
 128   display_entry() { return 0 }
 129
 130 # Only display menu item if specified program is available
 131   display_entry() {
 132       . /etc/grml/script-functions
 133       check4progs PROGRAM >/dev/null
 134       return $?
 135   }
 136
 137 .RE 1
 138 .TP
 139 .B LINE
 140 A variable used to determine what shall be done to generate a menu entry. Typically
 141 used in combination with print_line. Only used if display_entry returns 0.
 142 .LP
 143 .RS
 144 .B \ Example
 145  # print Configure network (grml-network)
 146  LINE='print_line "Configure ^network (/grml-network/)"'
 147 .RE 1
 148 .SS Optional entries
 149 The following variables are optional and can be defined in a script but do not have to.
 150 .TP
 151 .B FUNCTION
 152 A variable specifying the code which should be executed if user selects this menu entry.
 153 The variable $INPUT can be used to get the user input.
 154 .RS
 155 .B \ Example
 156  # Print the key from the user
 157  FUNCTION='echo $INPUT'
 158
 159  # create a submenu
 160  submenu() { ... }
 161  FUNCTION='submenu'
 162 .RE 1
 163
 164 .TP
 165 .B KEY, array
 166 An array containing all possible keys for executing the code specified in the FUNCTION variable, e.g:
 167 .RS
 168  # execute code in FUNCTION if c, d or e is pressed.
 169 KEY=(c d e)
 170
 171 .SS Complete Example
 172  # language module for grml-quickconfig
 173  LINE='print_line "Set keyboard layout (/grml-lang/): ^de ^at ^ch e^s ^us"'
 174
 175  typeset -A lang_mapping
 176
 177  # map keys to language
 178  lang_mapping=(
 179      d de
 180      a at
 181      c ch
 182      s es
 183      u us
 184  )
 185
 186  # get all keys from assoc array
 187  KEY=(${(k)lang_mapping})
 188
 189  # $INPUT is the user input
 190  FUNCTION='run grml-lang ${lang_mapping[$INPUT]}'
 191
 192  # always display entry
 193  display_entry() {
 194      return 0
 195  }
 196
 197  ## END OF FILE #################################################################
 198  # vim:foldmethod=marker expandtab ai ft=zsh shiftwidth=3
 199
 200 .SH AUTHOR
 201 grml-quickconfig was written by the Grml Team <team@grml.org> and is based on the
 202 idea of Michael Schierl <schierlm-public@gmx.de>.
 203 .PP
 204 This manual page was written by Ulrich Dangel <mru@grml.org> and Michael Prokop
 205 <mika@grml.org> for the Grml project (but may be used by others).