aboutsummaryrefslogtreecommitdiffstats
path: root/doc/menu.txt
diff options
context:
space:
mode:
authorH. Peter Anvin <hpa@zytor.com>2008-02-28 16:04:08 -0800
committerH. Peter Anvin <hpa@zytor.com>2008-02-28 16:04:08 -0800
commit7cfa9099ea0aa53c6e3a24c9902b141d0aca6369 (patch)
tree5e561e798bb78336c789bd6088ad4a31d043feb4 /doc/menu.txt
parent49fc1592066392962c3041bc21c13b542e96d1b5 (diff)
downloadsyslinux-elf-7cfa9099ea0aa53c6e3a24c9902b141d0aca6369.tar.gz
syslinux-elf-7cfa9099ea0aa53c6e3a24c9902b141d0aca6369.tar.xz
syslinux-elf-7cfa9099ea0aa53c6e3a24c9902b141d0aca6369.zip
Rename text documentation from *.doc to *.txt
Rename plaintext documentation from doc/*.doc to doc/*.txt, to avoid the chronic problem of web sites thinking they're in MS-Word format. Sigh. As if Microsoft somehow had a monopoly on the word "document".
Diffstat (limited to 'doc/menu.txt')
-rw-r--r--doc/menu.txt476
1 files changed, 476 insertions, 0 deletions
diff --git a/doc/menu.txt b/doc/menu.txt
new file mode 100644
index 00000000..aa161bca
--- /dev/null
+++ b/doc/menu.txt
@@ -0,0 +1,476 @@
+There are two menu systems included with SYSLINUX, the advanced menu
+system, and the simple menu system.
+
+
++++ THE ADVANCED MENU SYSTEM +++
+
+The advanced menu system, written by Murali Krishnan Ganapathy, is
+located in the menu/ subdirectly. It allows the user to create
+hierarchial submenus, dynamic options, checkboxes, and just about
+anything you want. It requires that the menu is compiled from a
+simple C file, see menu/simple.c and menu/complex.c for examples.
+
+The advanced menu system doesn't support serial console at this time.
+
+See menu/README for more information.
+
+
++++ THE SIMPLE MENU SYSTEM +++
+
+The simple menu system is a single module located at
+com32/modules/vesamenu.c32 (graphical) or com32/modules/menu.c32 (text
+mode only). It uses the same configuration file as the regular
+SYSLINUX command line, and displays all the LABEL statements.
+
+To use the menu system, simply make sure [vesa]menu.c32 is in the
+appropriate location for your boot medium (the same directory as the
+configuration file for SYSLINUX, EXTLINUX and ISOLINUX, and the same
+directory as pxelinux.0 for PXELINUX), and put the following options
+in your configuration file:
+
+DEFAULT menu.c32
+PROMPT 0
+
+
+There are a few menu additions to the command line, all starting with
+the keywords MENU or TEXT; like the rest of the SYSLINUX config file
+language, it is case insensitive:
+
+MENU TITLE title
+
+ Give the menu a title. The title is presented at the top of
+ the menu.
+
+MENU HIDDEN
+
+ Do not display the actual menu unless the user presses a key.
+ All that is displayed is a timeout message.
+
+MENU SEPARATOR
+
+ Insert an empty line in the menu.
+
+MENU LABEL label
+
+ (Only valid after a LABEL statement.)
+ Changes the label displayed for a specific entry. This allows
+ you to have a label that isn't suitable for the command line,
+ for example:
+
+ # Soft Cap Linux
+ LABEL softcap
+ MENU LABEL Soft Cap ^Linux 9.6.36
+ KERNEL softcap-9.6.36.bzi
+ APPEND whatever
+
+ # A very dense operating system
+ LABEL brick
+ MENU LABEL ^Windows CE/ME/NT
+ KERNEL chain.c32
+ APPEND hd0 2
+
+ The ^ symbol in a MENU LABEL statement defines a hotkey.
+ The hotkey will be highlighted in the menu and will move the
+ menu cursor immediately to that entry.
+
+ Reusing hotkeys is disallowed, subsequent entries will not be
+ highlighted, and will not work.
+
+ Keep in mind that the LABELs, not MENU LABELs, must be unique,
+ or odd things will happen to the command-line.
+
+
+MENU INDENT count
+
+ (Only valid after a LABEL statement.)
+ Will add "count" spaces in front of the displayed menu entry.
+
+MENU DISABLE
+
+ (Only valid after a LABEL statement.)
+ Makes the entry unselectable. This allows you to make a
+ section in your menu with different options below it.
+ for example:
+
+ # Entries for network boots
+ LABEL -
+ MENU LABEL Network:
+ MENU DISABLE
+
+ # Soft Cap Linux
+ LABEL softcap
+ MENU LABEL Soft Cap ^Linux 9.6.36
+ MENU INDENT 1
+ KERNEL softcap-9.6.36.bzi
+ APPEND whatever
+
+ # Dos 6.22
+ LABEL dos
+ MENU LABEL ^Dos 6.22
+ MENU INDENT 1
+ KERNEL memdisk
+ APPEND initrd=dos622.imz
+
+ # Separator
+ MENU SEPARATOR
+
+ # Entries for local boots
+ LABEL -
+ MENU LABEL Local:
+ MENU DISABLE
+
+ # Windows 2000
+ LABEL w2k
+ MENU LABEL ^Windows 2000
+ MENU INDENT 1
+ KERNEL chain.c32
+ APPEND hd0 1
+
+ # Windows XP
+ LABEL xp
+ MENU LABEL Windows ^XP
+ MENU INDENT 1
+ KERNEL chain.c32
+ APPEND hd0 2
+
+MENU HIDE
+
+ (Only valid after a LABEL statement.)
+ Suppresses a particular LABEL entry from the menu.
+
+
+MENU DEFAULT
+
+ (Only valid after a LABEL statement.)
+ Indicates that this entry should be the default. If no
+ default is specified, use the first one.
+
+
+TEXT HELP
+Help text ...
+... which can span multiple lines
+ENDTEXT
+
+ (Only valid after a LABEL statement.)
+
+ Specifies a help text that should be displayed when a particular
+ selection is highlighted.
+
+
+MENU PASSWD passwd
+
+ (Only valid after a LABEL statement.)
+
+ Sets a password on this menu entry. "passwd" can be either a
+ cleartext password, a SHA-1 encrypted password (starting with
+ $4$), or and MD5 encrypted password (starting with $1$).
+
+ Use the included Perl scripts "sha1pass" or "md5pass" to
+ encrypt passwords. MD5 passwords are compatible with most
+ Unix password file utilities; SHA-1 passwords are probably
+ unique to SYSLINUX. Obviously, if you don't encrypt your
+ passwords they will not be very secure at all.
+
+ If you are using passwords, you want to make sure you also use
+ the settings "NOESCAPE 1", "PROMPT 0", and either set
+ "ALLOWOPTIONS 0" or use a master password (see below.)
+
+ If passwd is an empty string, this menu entry can only be
+ unlocked with the master password.
+
+
+MENU MASTER PASSWD passwd
+
+ Sets a master password. This password can be used to boot any
+ menu entry, and is required for the [Tab] and [Esc] keys to
+ work.
+
+
+MENU BACKGROUND background
+
+ For vesamenu.c32, sets the background image. The background
+ can either be a color (see MENU COLOR) or the name of an image
+ file, which should be 640x480 pixels and either in PNG or JPEG
+ format.
+
+
+MENU BEGIN [tagname]
+MENU END
+
+ Begin/end a submenu. The entries between MENU BEGIN and MENU
+ END form a submenu, which is marked with a > mark on the right
+ hand of the screen. Submenus inherit the properties of their
+ parent menus, but can override them, and can thus have their
+ own backgrounds, master passwords, titles, timeouts, messages
+ and so forth.
+
+
+MENU GOTO tagname
+
+ (Only valid after a LABEL statement.)
+
+ This label will transfer to the named submenu instead of
+ booting anything. To transfer to the top-level menu, specify
+ "menu goto .top".
+
+
+MENU EXIT [tagname]
+
+ (Only valid after a label statement inside MENU BEGIN ...
+ MENU END)
+
+ Exit to the next higher menu, or, if tagname is specified, to
+ the named menu.
+
+
+MENU QUIT
+
+ (Only valid after a LABEL statement.)
+
+ This label quits the menu system.
+
+ WARNING: if MENU MASTER PASSWD or ALLOWOPTIONS 0 is set, this
+ will still allow exiting to the CLI; however, a separate MENU
+ PASSWD can of course be set for this label.
+
+
+MENU START
+
+ (Only valid inside MENU BEGIN ... MENU END)
+
+ Indicates that the menu system should start at the menu being
+ defined instead of at the top-level menu.
+
+
+INCLUDE filename [tagname]
+MENU INCLUDE filename [tagname]
+
+ Include the contents of the configuration file filename at
+ this point.
+
+ In the case of MENU INCLUDE, the included data is only seen by
+ the menu system; the core syslinux code does not parse this
+ command, so any labels defined in it are unavailable.
+
+ If a tagname is included, the whole file is considered to have
+ been bracketed with a MENU BEGIN tagname ... MENU END pair,
+ and will therefore show up as a submenu.
+
+
+MENU AUTOBOOT message
+
+ Replaces the message "Automatic boot in # second{,s}...". The
+ symbol # is replaced with the number of seconds remaining.
+ The syntax "{singular,[dual,]plural}" can be used to conjugate
+ appropriately.
+
+
+MENU TABMSG message
+
+ Replaces the message "Press [Tab] to edit options".
+
+
+MENU NOTABMSG message
+
+ Takes the place of the TABMSG message if option editing is
+ disabled. Defaults to blank.
+
+
+MENU PASSPROMPT message
+
+ Replaces the message "Password required".
+
+
+MENU COLOR element ansi foreground background shadow
+
+ Sets the color of element "element" to the specified color
+ sequence:
+
+ screen Rest of the screen
+ border Border area
+ title Title bar
+ unsel Unselected menu item
+ hotkey Unselected hotkey
+ sel Selection bar
+ hotsel Selected hotkey
+ disabled Disabled menu item
+ scrollbar Scroll bar
+ tabmsg Press [Tab] message
+ cmdmark Command line marker
+ cmdline Command line
+ pwdborder Password box border
+ pwdheader Password box header
+ pwdentry Password box contents
+ timeout_msg Timeout message
+ timeout Timeout counter
+ help Help text
+ msgXX Message (F-key) file attribute XX
+
+ ... where XX is two hexadecimal digits (the "plain text" is 07).
+
+ "ansi" is a sequence of semicolon-separated ECMA-48 Set
+ Graphics Rendition (<ESC>[m) sequences:
+
+ 0 reset all attributes to their defaults
+ 1 set bold
+ 4 set underscore (simulated with color on a color display)
+ 5 set blink
+ 7 set reverse video
+ 22 set normal intensity
+ 24 underline off
+ 25 blink off
+ 27 reverse video off
+ 30 set black foreground
+ 31 set red foreground
+ 32 set green foreground
+ 33 set brown foreground
+ 34 set blue foreground
+ 35 set magenta foreground
+ 36 set cyan foreground
+ 37 set white foreground
+ 38 set underscore on, set default foreground color
+ 39 set underscore off, set default foreground color
+ 40 set black background
+ 41 set red background
+ 42 set green background
+ 43 set brown background
+ 44 set blue background
+ 45 set magenta background
+ 46 set cyan background
+ 47 set white background
+ 49 set default background color
+
+ These are used (a) in text mode, and (b) on the serial
+ console.
+
+ "foreground" and "background" are color codes in #AARRGGBB
+ notation, where AA RR GG BB are hexadecimal digits for alpha
+ (opacity), red, green and blue, respectively. #00000000
+ represents fully transparent, and #ffffffff represents opaque
+ white.
+
+ "shadow" controls the handling of the graphical console text
+ shadow. Permitted values are "none" (no shadowing), "std" or
+ "standard" (standard shadowing - foreground pixels are
+ raised), "all" (both background and foreground raised), and
+ "rev" or "reverse" (background pixels are raised.)
+
+ If any field is set to "*" or omitted (at the end of the line)
+ then that field is left unchanged.
+
+
+ The current defaults are:
+
+ menu color screen 37;40 #80ffffff #00000000 std
+ menu color border 30;44 #40000000 #00000000 std
+ menu color title 1;36;44 #c00090f0 #00000000 std
+ menu color unsel 37;44 #90ffffff #00000000 std
+ menu color hotkey 1;37;44 #ffffffff #00000000 std
+ menu color sel 7;37;40 #e0000000 #20ff8000 all
+ menu color hotsel 1;7;37;40 #e0400000 #20ff8000 all
+ menu color disabled 1;30;44 #60cccccc #00000000 std
+ menu color scrollbar 30;44 #40000000 #00000000 std
+ menu color tabmsg 31;40 #90ffff00 #00000000 std
+ menu color cmdmark 1;36;40 #c000ffff #00000000 std
+ menu color cmdline 37;40 #c0ffffff #00000000 std
+ menu color pwdborder 30;47 #80ffffff #20ffffff std
+ menu color pwdheader 31;47 #80ff8080 #20ffffff std
+ menu color pwdentry 30;47 #80ffffff #20ffffff std
+ menu color timeout_msg 37;40 #80ffffff #00000000 std
+ menu color timeout 1;37;40 #c0ffffff #00000000 std
+ menu color help 37;40 #c0ffffff #00000000 std
+ menu color msg07 37;40 #90ffffff #00000000 std
+
+
+MENU MSGCOLOR fg_filter bg_filter shadow
+
+ Sets *all* the msgXX colors to a color scheme derived from the
+ fg_filter and bg_filter values. Background color zero is
+ always treated as transparent. The default corresponds to:
+
+ menu msgcolor #90ffffff #80ffffff std
+
+ This directive should come before any directive that
+ customizes individual msgXX colors.
+
+
+MENU WIDTH 80
+MENU MARGIN 10
+MENU PASSWORDMARGIN 3
+MENU ROWS 12
+MENU TABMSGROW 18
+MENU CMDLINEROW 18
+MENU ENDROW -1
+MENU PASSWORDROW 11
+MENU TIMEOUTROW 20
+MENU HELPMSGROW 22
+MENU HELPMSGENDROW -1
+MENU HIDDENROW -2
+MENU HSHIFT 0
+MENU VSHIFT 0
+
+ These options control the layout of the menu on the screen.
+ The values above are the defaults.
+
+ A negative value is relative to the calculated length of the
+ screen (25 for text mode, 28 for VESA graphics mode.)
+
+
+F1 textfile background
+...
+F12 textfile background
+
+ Displays full-screen help (also available at the command line.)
+ The same control code sequences as in the command line
+ interface are supported, although some are ignored.
+
+ Additionally, a second argument allows a different background
+ image (see MENU BACKGROUND for supported formats) to be displayed.
+
+
+The menu system honours the TIMEOUT command; if TIMEOUT is specified
+it will execute the ONTIMEOUT command if one exists, otherwise it will
+pick the default menu option.
+
+Normally, the user can press [Tab] to edit the menu entry, and [Esc]
+to return to the SYSLINUX command line. However, if the configuration
+file specifies ALLOWOPTIONS 0, these keys will be disabled, and if
+MENU MASTER PASSWD is set, they require the master password.
+
+The simple menu system supports serial console, using the normal
+SERIAL directive. However, it can be quite slow over a slow serial
+link; you probably want to set your baudrate to 38400 or higher if
+possible. It requires a Linux/VT220/ANSI-compatible terminal on the
+other end.
+
+
+ +++ USING AN ALTERNATE CONFIGURATION FILE +++
+
+
+It is also possible to load a secondary configuration file, to get to
+another menu. To do that, invoke menu.c32 with the name of the
+secondary configuration file.
+
+LABEL othermenu
+ MENU LABEL Another Menu
+ KERNEL menu.c32
+ APPEND othermenu.conf
+
+If you specify more than one file, they will all be read, in the order
+specified. The dummy filename ~ (tilde) is replaced with the filename
+of the main configuration file.
+
+# The file graphics.conf contains common color and layout commands for
+# all menus.
+LABEL othermenu
+ MENU LABEL Another Menu
+ KERNEL vesamenu.c32
+ APPEND graphics.conf othermenu.conf
+
+# Return to the main menu
+LABEL mainmenu
+ MENU LABEL Return to Main Menu
+ KERNEL vesamenu.c32
+ APPEND graphics.conf ~
+
+See also the MENU INCLUDE directive above.