sys/boot/forth/menusets.4th.8

   1 .\" Copyright (c) 2012 Devin Teske
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd November 5, 2012
  28 .Dt MENUSETS.4TH 8
  29 .Os
  30 .Sh NAME
  31 .Nm menusets.4th
  32 .Nd FreeBSD dynamic submenu boot module
  33 .Sh DESCRIPTION
  34 The file that goes by the name of
  35 .Nm
  36 is a set of commands designed to add submenu functionality to the dynamic menu
  37 system provided by
  38 .Xr menu.4th 8 .
  39 Submenus are managed through a system of carefully named environment variables.
  40 The commands of
  41 .Nm
  42 by themselves are not enough for most uses.
  43 Please refer to the examples below for the most common situations, and to
  44 .Xr menu.4th 8
  45 for additional commands.
  46 .Pp
  47 Before using any of the commands provided in
  48 .Nm ,
  49 it must be included
  50 through the command:
  51 .Pp
  52 .Dl include menusets.4th
  53 .Pp
  54 This line is present in the default
  55 .Pa /boot/menu-commands.4th
  56 file, so it is not needed (and should not be re-issued) in a normal setup.
  57 .Pp
  58 The commands provided by it are:
  59 .Pp
  60 .Bl -tag -width menuset-loadinitial -compact -offset indent
  61 .It Ic menuset-loadsetnum
  62 Takes a single integer on the stack to identify the menuset environment
  63 variables to be activated (see environment variables below).
  64 .It Ic menuset-loadinitial
  65 If $menuset_initial is set, passes the value to menuset-loadsetnum.
  66 The value must be a number.
  67 .It Ic menusets-unset
  68 Unsets the environment variables associated with all menusets.
  69 Increments starting at 1 and stops at the first unconfigured menuset.
  70 A menuset is considered configured if the caption for item 1 is set.
  71 .El
  72 .Pp
  73 The environment variables that effect its behavior are:
  74 .Bl -tag -width bootfile -offset indent
  75 .It Va menuset_initial
  76 Number to pass to menuset-loadsetnum when menuset-loadinitial is called.
  77 .It Va menuset_nameN
  78 Used to give a name to a menuset.
  79 .El
  80 .Pp
  81 When a menuset is NOT given a name (the default),
  82 menuset N is comprised of the following environment variables:
  83 .Pp
  84 .Bl -tag -width menusetN_caption[x][y] -compact -offset indent
  85 .It Va ansisetN_caption[x]
  86 -> ansi_caption[x]
  87 .It Va ansisetN_caption[x][y]
  88 -> ansi_caption[x][y]
  89 .It Va menusetN_acpi
  90 -> menu_acpi
  91 .It Va menusetN_caption[x]
  92 -> menu_caption[x]
  93 .It Va menusetN_caption[x][y]
  94 -> menu_caption[x][y]
  95 .It Va menusetN_command[x]
  96 -> menu_command[x]
  97 .It Va menusetN_init
  98 ->
  99 .Dq Li evaluated
 100 .It Va menusetN_init[x]
 101 -> menu_init[x]
 102 .It Va menusetN_keycode[x]
 103 -> menu_keycode[x]
 104 .It Va menusetN_options
 105 -> menu_options
 106 .It Va menusetN_optionstext
 107 -> menu_optionstext
 108 .It Va menusetN_reboot
 109 -> menu_reboot
 110 .It Va toggledsetN_ansi[x]
 111 -> toggled_ansi[x]
 112 .It Va toggledsetN_text[x]
 113 -> toggled_text[x]
 114 .El
 115 .Pp
 116 When you choose to give a menuset a name (by setting $menuset_nameN),
 117 menuset N is instead comprised of the following environment variables:
 118 .Pp
 119 .Bl -tag -width NAMEmenu_caption[x][y] -compact -offset indent
 120 .It Va NAMEansi_caption[x]
 121 -> ansi_caption[x]
 122 .It Va NAMEansi_caption[x][y]
 123 -> ansi_caption[x][y]
 124 .It Va NAMEmenu_acpi
 125 -> menu_acpi
 126 .It Va NAMEmenu_caption[x]
 127 -> menu_caption[x]
 128 .It Va NAMEmenu_caption[x][y]
 129 -> menu_caption[x][y]
 130 .It Va NAMEmenu_command[x]
 131 -> menu_command[x]
 132 .It Va NAMEmenu_init
 133 ->
 134 .Dq Li evaluated
 135 .It Va NAMEmenu_init[x]
 136 -> menu_init[x]
 137 .It Va NAMEmenu_keycode[x]
 138 -> menu_keycode[x]
 139 .It Va NAMEmenu_options
 140 -> menu_options
 141 .It Va NAMEmenu_optionstext
 142 -> menu_optionstext
 143 .It Va NAMEmenu_reboot
 144 -> menu_reboot
 145 .It Va NAMEtoggled_ansi[x]
 146 -> toggled_ansi[x]
 147 .It Va NAMEtoggled_text[x]
 148 -> toggled_text[x]
 149 .El
 150 .Pp
 151 where
 152 .Dq Li NAME
 153 is the value of $menuset_nameN.
 154 In the case of $NAMEmenu_init ($menusetN_init when $menuset_nameN is unset),
 155 the value is evaluated as an FICL statement.
 156 This can be used to dynamically adjust the menuset variables right before the
 157 menu is activated.
 158 .Pp
 159 In addition,
 160 .Nm
 161 provides the following FICL words:
 162 .Pp
 163 .Bl -tag -width menuset -compact -offset indent
 164 .It Ic menuset-checksetnum ( N -- )
 165 Given a single integer on the stack, sets a global variable
 166 .Va menuset_use_name
 167 to a boolean based on whether $menuset_nameN is set (true) or not (false).
 168 Also sets $affix temporary variable (prefix or infix depending on
 169 menuset_use_name).
 170 Automatically called by menuset-loadsetnum and menusets-unset.
 171 .It Ic menuset-loadvar ( -- )
 172 Used indirectly to shorten syntax and mitigate dictionary size.
 173 Requires the following temporary environment variables:
 174 .Pp
 175 .Bl -tag -width affix -compact -offset indent
 176 .It Va type
 177 should be set to one of: menu toggled ansi
 178 .It Va var
 179 should be set to one of: caption command keycode text ...
 180 .It Va affix
 181 either a prefix (menuset_use_name is true) or infix (menuset_use_name is false)
 182 .El
 183 .Pp
 184 If the global
 185 .Va menuset_use_name
 186 is true, the variable ${type}_${var} is made to
 187 equal the value of the variable ${affix}${type}_${var}
 188 (note: in this case menuset-checksetnum has set $affix to $menuset_nameN).
 189 Otherwise (when
 190 .Va menuset_use_name
 191 is false), the variable ${type}_${var} is made to
 192 equal the value of the variable ${type}set${affix}_${var}
 193 (note: in this case menuset-checksetnum has set $affix to N).
 194 .Pp
 195 Both the global variable
 196 .Va menuset_use_name
 197 and the environment variable $affix are automatically handled by
 198 menuset-checksetnum above (which is automatically called by
 199 menuset-loadsetnum).
 200 .It Ic menuset-unloadvar ( -- )
 201 Used indirectly to shorten syntax and mitigate dictionary size.
 202 Like menuset-loadvar except it unsets the menuset variable.
 203 If global
 204 .Va menuset_use_name
 205 is true ($affix is $menuset_nameN),
 206 variable ${affix}${type}_${var} is unset.
 207 Otherwise, $affix is N and variable ${type}set${affix}_${var} is unset.
 208 .It Ic menuset-loadmenuvar ( -- )
 209 Sets $type to
 210 .Dq menu
 211 and calls menuset-loadvar.
 212 .It Ic menuset-unloadmenuvar ( -- )
 213 Sets $type to
 214 .Dq menu
 215 and calls menuset-unloadvar.
 216 .It Ic menuset-loadxvar ( -- )
 217 Like menuset-loadvar except it takes an additional temporary variable $x.
 218 If the global
 219 .Va menuset_use_name
 220 is true (making $affix equal $menuset_nameN),
 221 sets variable ${type}_${var}[${x}] to variable ${affix}${type}_${var}[${x}].
 222 Otherwise ($affix being N), sets the same variable to instead
 223 ${type}set{affix}_${var}[${x}].
 224 .It Ic menuset-unloadxvar ( -- )
 225 Like menuset-loadxvar except it unsets the menuset variable.
 226 If global
 227 .Va menuset_use_name
 228 is true, unsets ${affix}${type}_${var}[${x}].
 229 Otherwise, unsets ${type}set${affix}_${var}[${x}].
 230 .It Ic menuset-loadansixvar ( -- )
 231 Sets $type to
 232 .Dq ansi
 233 and calls menuset-loadxvar
 234 .It Ic menuset-unloadansixvar ( -- )
 235 Sets $type to
 236 .Dq ansi
 237 and calls menuset-unloadxvar
 238 .It Ic menuset-loadmenuxvar ( -- )
 239 Sets $type to
 240 .Dq ansi
 241 and calls menuset-loadxvar
 242 .It Ic menuset-unloadmenuxvar ( -- )
 243 Sets $type to
 244 .Dq ansi
 245 and calls menuset-unloadxvar
 246 .It Ic menuset-loadtoggledxvar ( -- )
 247 Sets $type to
 248 .Dq toggled
 249 and calls menuset-loadxvar
 250 .It Ic menuset-unloadtoggledxvar ( -- )
 251 Sets $type to
 252 .Dq toggled
 253 and calls menuset-unloadxvar
 254 .It Ic menuset-loadxyvar ( -- )
 255 Like menuset-loadxvar except it takes an additional temporary variable $y.
 256 If the global
 257 .Va menuset_use_name
 258 is true ($affix is $menuset_nameN),
 259 sets variable ${type}_${var}[${x}][${y}] to ${affix}${type}_${var}[${x}][${y}].
 260 Otherwise ($affix is N) sets the same variable to instead
 261 ${type}set${affix}_${var}[${x}][${y}].
 262 .It Ic menuset-unloadxyvar ( -- )
 263 Like menuset-loadxyvar except it unsets the menuset variable.
 264 If the global
 265 .Va menuset_use_name
 266 is true, unsets ${affix}${type}_${var}[${x}][${y}].
 267 Otherwise, unsets ${type}set${affix}_${var}[${x}][${y}].
 268 .It Ic menuset-loadansixyvar ( -- )
 269 Sets $type to
 270 .Dq ansi
 271 and calls menuset-loadxyvar.
 272 .It Ic menuset-unloadansixyvar ( -- )
 273 Sets $type to
 274 .Dq ansi
 275 and calls menuset-unloadxyvar.
 276 .It Ic menuset-loadmenuxyvar ( -- )
 277 Sets $type to
 278 .Dq menu
 279 and calls menuset-loadxyvar.
 280 .It Ic menuset-unloadmenuxyvar ( -- )
 281 Sets $type to
 282 .Dq menu
 283 and calls menuset-unloadxyvar.
 284 .It Ic menuset-setnum-namevar ( N -- C-Addr/U )
 285 Takes a single integer on the stack and replaces it with a string (in c-addr/u
 286 format) whose value is
 287 .Dq menuset_nameN .
 288 For example, if given 1 returns
 289 .Dq menuset_name1 .
 290 .It Ic menuset-cleanup ( N -- )
 291 Unsets all the various temporary variables, currently
 292 .Va type ,
 293 .Va var ,
 294 .Va x ,
 295 .Va y ,
 296 and
 297 .Va affix .
 298 .El
 299 .Pp
 300 For all values of
 301 .Dq Li x
 302 above, use any number between 1 through 9. Sorry, double-digits are not
 303 currently supported.
 304 For all values of
 305 .Dq Li N
 306 above, use any number between 1 and 65535.
 307 .Sh FILES
 308 .Bl -tag -width /boot/menu-commands.4th -compact
 309 .It Pa /boot/loader
 310 The
 311 .Xr loader 8 .
 312 .It Pa /boot/menu.4th
 313 Dynamic menu module.
 314 .It Pa /boot/menu-commands.4th
 315 Contains the goto_menu command.
 316 .It Pa /boot/menusets.4th
 317 .Nm
 318 itself.
 319 .It Pa /boot/loader.rc
 320 .Xr loader 8
 321 bootstrapping script.
 322 .El
 323 .Sh EXAMPLES
 324 A simple boot menu with a submenu:
 325 .Pp
 326 .Bd -literal -offset indent -compact
 327 include /boot/menu.4th
 328 include /boot/menu-commands.4th
 329 menu-init
 330 set menuset1_caption[1]="Boot"
 331 set menuset1_command[1]="boot"
 332 set menuset1_caption[2]="Submenu..."
 333 set menuset1_command[2]="2 goto_menu"
 334 set menuset2_caption[1]="Back"
 335 set menuset2_command[1]="1 goto_menu"
 336 set menuset_initial=2
 337 menuset-loadinitial
 338 menu-display
 339 .Ed
 340 .Pp
 341 The same boot menu with named menusets:
 342 .Pp
 343 .Bd -literal -offset indent -compact
 344 include /boot/menu.4th
 345 include /boot/menu-commands.4th
 346 menu-init
 347 set menuset_name1=main
 348 set mainmenu_caption[1]="Boot"
 349 set mainmenu_command[1]="boot"
 350 set mainmenu_caption[2]="Submenu..."
 351 set mainmenu_command[2]="2 goto_menu"
 352 set menuset_name2=sub
 353 set submenu_caption[1]="Back"
 354 set submenu_command[1]="1 goto_menu"
 355 .Ed
 356 .Sh SEE ALSO
 357 .Xr loader.conf 5 ,
 358 .Xr loader 8 ,
 359 .Xr loader.4th 8 ,
 360 .Xr menu.4th 8 ,
 361 .Xr beastie.4th 8
 362 .Sh HISTORY
 363 The
 364 .Nm
 365 set of commands first appeared in
 366 .Fx 10.0 .
 367 .Sh AUTHORS
 368 The
 369 .Nm
 370 set of commands was written by
 371 .An -nosplit
 372 .An Devin Teske Aq dteske@FreeBSD.org .