antiX gfxboot Configuration README
==================================
Gfxboot is highly configurable.  Some configuration changes
require a recompile but very many changes can be made by editing
the gfxboot.cfg file.  In addition, the user can create up to 3
custom menus by making text files called options1.men,
custom1.men, and custom2.men.


The gfxboot.cfg File
====================
This file is laid out in sections.  The sections are named like
this:

  [base]

The base section is processed first.  Only sections that appear
in the layout= line in the base section will be processed.  They
are read in the order they appear in that line.

NOTE: Options are "first come, first served" so in order to
override an existing setting your new setting must either be in
an earlier section or come before (above) the setting you want to
override.

Lines starting with the characters ; or # will be ignored.  You
assigned menus to Fn function keys with lines like:

  key.F1=help

You can assign more than 6 Fn keys but you are likely to run out
of room if you do.


gfxboot.cfg Settings
--------------------
The majority of the settings affect colors and the position of
elements on the screen.  Most, but not all, colors can be
adjusted.

The term "panel" refers to the row of Fn Function keys near the
bottom of the screen.  You can move it around with panel.xoffset
and panel.yoffset.  You adjust the gap between Fn keys with
panel.gap.

The term "sbox" stands for "selection box".  When enabled it
draws a box around each selected menu item in the panel.

Most of the gfxboot.cfg color options should be obvious.
Here are is a brief description of some of the less obvious
options that were added:

  timeout.fg              The color of the timeout icon(s)

  timeout.leftside        Move the timeout icons to the left of
                          the selected main menu item

  timeout.copies          Make this many timeout icons and cycle
                          through each one successively

  timeout.gap             The gap in pixels between multiple
                          timeout icons

  timeout.revframes       Run the timeout frames in reverse order

  timeout.test            Don't erase timeout icons when they normally
                          get erased.  This makes it easier to take
                          screen shots show the timeout icon(s).

  sbox.enabled            Draw a bordered box around each selected
                          item at the bottom of the screen

  menu.xoffset            Move the pop-up menus and their selected
                          items this many pixels to the *left*.

  panel.xoffset           Move the entire panel this many pixels
                          to the right

  panel.yoffset           Move the entire panel this many pixels up

  panel.gap               The gap between items in the panel

  main.rtl.xoff           Offset the main menu for right-to-left
                          languages

Custom Menus
============
You can create 3 different custom menus using files named
options1.men, custom1.men, and custom2.men.  You would make
corresponding Fn key assignments like this:

  key.F4=options1
  key.F5=custom1
  key.F6=custom2


Custom Menu file Format
-----------------------
The file format for .men files is straightforward.  The first
line is the title.  The following lines are the label followed by
optional spaces (not tabs) a back-tick character (`) and then the
boot parameters associated with the label.


Custom Desktop Menu
-------------------
TL;DR: don't use it

The Desktop menu can be customized by using a desktop.men file.
The format is slightly different.  There is no title line, just
menu entries.  The title is always "Desktop" (or a translations
thereof).  The last menu entry  for a command line interface will
be added automatically.

You can set a new/different default desktop by putting its name
in a file called:

    desktop

This will add a new entry at the top of the Desktop menu.  The
label will be whatever is set by this parameter and the parameter
will be the empty string.  The parameter string for the first
entry in the desktop.men file will now be used because it is no
longer the default.  If there is an entry in the desktop file
with a label that matches the default.desktop, it will be
ignored.

Finally, the desktop.men file may get overwritten when you run
the update-default-desktop program.  Therefore we suggest that
you don't use desktop.men as a 4th custom menu and just make use
of the 3 other menus that you can customize.

Predefined Function Keys
========================
Three of the Fn function keys were preassigned:

  F10   Power-off/Reboot
  F11   Toggle sbox enabled
  F12   Show boot parameters

Enabling the F7 Save Menu
=========================
If a file called enable.save exists and is not empty then if the
F7 menu does not exist or if it is set to "dpi" then it is
replaced by the "F7 Save" menu.  The purpose of this feature is
to allow us to enable the "F7 Save" menu only on Live systems on
read-write media.

Default Menu settings
=====================
The default entry for most of our menus can be selection with a
<menu-name>.def file.  The file must contain the parameters
of the default entry in the correct order and with the correct
spacing.  This format is convenient for setting the defaults to
the current menu choices since the only information we have to go
on is the list of all the boot parameters.

For historical reasons there are two exceptions to this rule.
Both the language and the timezone must have the leading
"<name>=" stripped off.  So you would use "fr" not "lang=fr"
and you would use "America/Denver" not "tz=American/Denver".


