menu/MENU_FORMAT

   1 A .menu file can be used to describe basic menu structures which can be converted
   2 into C code which can then be compiled into a .c32 file for use with SYSLINUX.
   3 The format of a .menu file is similar to an ini file, but with important
   4 differences.
   5
   6 Lines starting with # and ; are treated as comments. Blank lines are used to
   7 separate the attributes of one menu item from another. Multiple blank lines are
   8 equivalent to a single one.  In other contexts Blank lines are not significant.
   9
  10 Menus
  11 -----
  12 Each menu declaration starts with a line containing the name of menu in [ ].
  13 This is the "nickname" of the menu and should be different for different menus.
  14 This is not visible to the user of the menu system. The initial menu must
  15 be called "main"
  16
  17 The menu declaration is followed by lines which set the attributes of the menu.
  18 This is followed by a blank line and followed by declaration of menu items in
  19 that menu.
  20
  21 All lines which occur before the first menu declaration is considered as
  22 a global declaration.
  23
  24 Abstract Format
  25 ---------------
  26
  27 The overall format should look like this
  28
  29 --------------------------------------------------------
  30 <GLOBAL SETTINGS>
  31
  32 [menuname1]
  33
  34 <MENU SETTINGS>
  35
  36 <ITEM 1>
  37
  38 ...
  39
  40 <ITEM N>
  41
  42 [menuname2]
  43
  44 <MENU SETTINGS>
  45
  46 <ITEM A>
  47
  48 <ITEM B>
  49
  50 ----------------------------------------------------------
  51
  52 GLOBAL SETTINGS
  53 ---------------
  54 The following global settings are now supported. Many of the keywords
  55 accept what we call a "DOT COMMAND" as argument. Simply put they are
  56 instructions to the menu system to perform certain actions.
  57 The syntax and semantics of DOT COMMANDS are given later in the section
  58 titled "DOT COMMANDS".
  59
  60 videomode: (default 0xFF)  [Use with care]
  61    The textmode in which the whole menu system should operate.
  62    Must be a number (use 0x notation for hexadecimal).
  63    Lookup Ralph Brown Interrupt List and search for Video Mode
  64    to find a number to put here.
  65
  66    setting to 0xFF will mean, menu system will use the current
  67    video mode.
  68
  69 title:
  70    The title of the whole menu system
  71
  72 top, left, bot, right: (default 0,0,21,79)
  73    The area of the screen used by the menu system. The remaining
  74    part of the screen can be used by the user for anything.
  75
  76 helpdir: (default /isolinux/help)
  77    Location of the directory where help information is stored. The
  78    help files must be called "hlpNNNNN.txt" where NNNNN is the helpid.
  79
  80 pwdfile: (default /isolinux/passwd)
  81    The name of the password file which contains user, password and permissions
  82    See "passwd" file for details regarding format of this file
  83
  84 editrow: (default 23)
  85    the row on the screen where one can edit the command line. This must
  86    be outside the menu area. Set this to a negative number to disable
  87    editing the command line. In case of authenticated users, the current
  88    user must have "editcmd" permissions to edit the command line
  89
  90 pwdrow: (default 23)
  91    The row on the screen used for user authentication. Must be outside
  92    menu area (can be same as editrow). Set to negative to disable
  93    user authentication
  94
  95 skipif: (default 0)
  96    The OR of the bits in the Shift-flags any of which can cause the menu system
  97    to be skipped all together (0 means menu system always runs). It can also
  98    be a combination of "Alt","Ctrl","Shift","Caps","Ins","Scroll".
  99    When menu system starts it checks if any of the specified keys are On/pressed.
 100    If true, the system exits immediately and executes the skipcmd.
 101
 102    e.g. setting it to "shift-alt-caps" means menu will be skipped if alt OR shift
 103    is pressed OR caps is on. setting to "0" means menu will always run.
 104
 105 skipcmd: (default .exit)
 106    valid terminal commands: .exit .ignore or any syslinux command
 107    command to execute if menu system is skipped. This must be a non-trivial
 108    syslinux command if skipcondn is not "0". ".exit" means menu system
 109    quits back to the boot prompt.
 110
 111 startfile: (default "")
 112    if non-empty the system will display the contents of this file before launching
 113    the menusystem. This happens only if the menusystem is not skipped. Can be used
 114    to display licensing, usage or welcome messages. A file with given name
 115    is expected to be found in the helpdir directory.
 116
 117 exitcmd: (default .exit)
 118    valid terminal commands: .exit .repeat or any syslinux command
 119    The default command to execute when user quits the menu system.
 120
 121 exitcmdroot: (default =exitcmd)
 122    Same as exitcmd except applies when current user has "root" privileges. If not
 123    specified, it is assumed to be the same as exitcmd
 124
 125 timeout: (default 3000)
 126    The amount of time (in multiple of 0.1 seconds) to wait for user keypress. If no
 127    key pressed for specified duration then the timeoutcmd is executed.
 128
 129 totaltimeout: (default 0)
 130    The total amount of time (in multiples of 0.1 seconds) the system will wait for
 131    user to make a decision. If no decision has been made in the specified duration
 132    totaltimeoutcmd will be executed
 133
 134    NOTE: This does not include the time spent browsing the help system or
 135    the time taken for the user to enter his/her authentication credentials.
 136
 137 timeoutcmd: (default .beep)
 138    valid terminal commands: .wait .enter .escape or any syslinux command
 139    command to execute when we timeout waiting for user input. The commands
 140    .enter and .escape tell the menu system to pretend the user typed ENTER or
 141    ESCAPE on the keyboard, while .wait tells the menusystem to wait for one
 142    more time period
 143
 144 totaltimeoutcmd: (default .wait)
 145    choices are the same as for timeoutcmd
 146
 147 MENU SETTINGS
 148 -------------
 149
 150 title: (must be specified)
 151    Title of this menu
 152
 153 row,col: [Usage not recomended]
 154    position in screen where this menu should be placed. By default the
 155    system will choose an appropriate location.
 156
 157 ITEM ATTRIBUTES
 158 ---------------
 159
 160 item:
 161       The string displayed to the user. Characters enclosed in < > are highlighted.
 162
 163 shortcut: (default -1) valid values A-Za-z0-9 or -1 [Usage not recommended]
 164       Sets the shortcut key for this item. If set to -1, the system scans for the first
 165       highlighted letter in the given range and sets that as the shortcut key.
 166
 167 info: (default same as data)
 168       Additional textual information displayed in the status bar
 169
 170 type:
 171       the type of entry this item represents. This is one of the following:
 172
 173       run:       choosing this will run something in SYSLINUX
 174                  use data to specify the actual command to execute
 175       exitmenu:  exit to parent menu
 176       submenu:   choosing will open up submenu
 177                  use data to specify the "nickname" of the menu
 178                  which should come here
 179       sep:       Position a separator here
 180       inactive:  menu item is disabled
 181       checkbox:  this is a checkbox
 182                  use state to set initial state
 183       invisible: User does not see this item
 184       radioitem: One choice in a radiomenu
 185       radiomenu: Allow user to choose one of many choices
 186                  (initial choice is always NULL)
 187       login:     Selecting this will allow user to login to system
 188
 189 data:
 190       for run items, the syslinux command to execute
 191       for submenus and radiomenus, nickname of menu
 192       for checkboxes, string to be added to kernel command line (if set)
 193       for radioitems, string to be added to kernel command line (if chosen)
 194
 195 ipappend:
 196       ipappend flag to pass to PXELINUX (harmless for other variants of SYSLINUX)
 197       See syslinux documentation for meaning of the FLAGS
 198
 199 helpid: (default 65535 which is not a valid id)
 200       associates a context for the help system.
 201
 202 state: (default 0)
 203       Initial state of a checkbox (for other items this has no meaning)
 204
 205 perms: (default "")
 206       string containing the name of the permission which user must
 207       have to activate this item. For eg. if this item is a submenu
 208       then user needs the permission in order to open the submenu
 209
 210 argsmenu: (default "")
 211       Name of the menu to be scanned for setting additional arguments to
 212       pass to command line when this item is chosen for execution. Submenus
 213       of specified menu are also scanned. Only checkboxes and radiomenu's
 214       are scanned. Items of other type in this menu is silently ignored.
 215
 216
 217 DOT COMMANDS
 218 ------------
 219 Dot commands are basically instructions to the menu system to do certain things.
 220
 221 A "single command" is one of the following
 222
 223 [NT] A syslinux command (any DOT command not starting with a "." is assumed to be this)
 224 [NT] .beep [n]
 225 [NT] .help <file>
 226 [NT] .nop
 227 [T]  .exit or .quit (equivalent)
 228 [T]  .repeat or .wait or .ignore (all three are equivalent)
 229
 230 A dot command is a sequence of "single commands" separated by a "%". When a dot command
 231 is executed the system executes all the given "single commands" in the specified order.
 232 All the commands marked "[T]" are terminal commands, i.e. when the system encounters
 233 such a command it stops processing the dot command and returns the terminal command
 234 which caused the termination to the caller (who usually interprets the command
 235 appropriately).
 236
 237 All commands marked with [NT] are non-terminal commands, i.e. once these commands are
 238 processed the system continues to process the remaining "single commands" specified in
 239 the "DOT COMMAND".
 240
 241 Note: The case of a syslinux command is tricky. When executed, the command should never return
 242 (if the specified kernel exists) so the fact that we consider it a [NT] should be taken with
 243 a pinch of salt. However, if the syslinux command does return (in case of no kernel), then
 244 remaining "single commands" are processed. In particular "ker1 arg1 % ker2 arg2 % ker3 args"
 245 has the effect of executing the first kernel which exists
 246
 247 .nop:
 248    Does nothing.
 249 .beep:
 250    .beep [n] produces a beep n times. n must be between 0 and 9. If not specified n=1.
 251    (hence .beep 0 is equivalent to .nop)
 252 .help:
 253    .help <file>
 254    Displays the help file <file> which is assumed to be in the "help" directory. Its name
 255    does not have to be in the form "hlpNNNNN.txt" (as required by the context sensitive help).
 256    Executing this command will mean the appropriate help screen is displayed till the user hits
 257    ESCAPE
 258
 259 The meaning of the Terminal commands can vary with the context in which it is used. For example,
 260 a ".enter" or ".escape" does not have any meaning in the "onerrorcmd" context but it has a meaning
 261 in the "ontimeout" context. In case the user gives a Terminal command which does not make sense, it
 262 is upto the code (in this case adv_menu.tpl) to do what it pleases.