| 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. |
|---|
