The Installer UI
----------------

cdebconf, a smaller C implementation of the debconf specification,
is the main UI framework for the installer. Using cdebconf, it should be
possible to plug in new UI's with a minimum of difficulty.

So this document won't go into detail about how the UI will look. Instead,
it will talk about the structure and flow of the installation experience,
from a user's standpoint, and then from an implementation standpoint.

The user's view
---------------

Note that since cdebconf allows questions to be prioritized, it is possible
that the install process will skip over any or all of the questions.

The install begins with a bootloader. It is unlikely that this will change
significantly from what is used now.

After the kernel boots up, the first thing the user will see is whatever UI
is being used, configuring itself. This is equivalent to the current
installer asking if the screen supports color, and keyboard configuration.
It might also include language selection, mouse setup, etc. All up to the
individual UI. [ Language selection may do better as a separate module and
step, though. ]

Once the UI is configured, the user will see a list of every step in the
install process, with a proposed next step, and an alternate next step, at
the top. This is very similar to how the installer works now. We have
observed that this layout gives the user a great deal of flexibility, which
is very useful if something goes wrong and they have to run steps out of
order for some reason, or repeat a step. However, we also anticipate that 
people might not want to see this menu, and would rather go through a 
rigidly linear install process. Therefore, this menu will be a debconf
question asked at priority "medium", and so it might not actually be
displayed.

Anyway, each time an item is picked, the user will see one or more debconf
questions about it. They'll be able to go back and forward between these
questions -- and can even go all the way back to the menu to abort the
item. Assuming they go through the questions, though, eventually, the
question and answer sequence will end, and they will be returned to the menu,
typically with the next item selected.

At a minimum, the menu will probably contain the following items (and
probably several others):

  - Configure installation media (from floppy, cd, network, etc)
  - Partition disk
  - Format and mount partitions
  - Install base system
  - Install lilo (or silo, etc)
  - Make a rescue floppy
  - Reboot the system

Once the last item is picked, the system will boot up into a full debian
install, and the user will be prompted for additional information, much
as base-config does now.

Implementation
--------------

If only one UI is available on the install media, it will automatically be
used. If more than one UI is available, they will be prioritized, and each
will be configured. If one fails to configure, the next on the list is tried,
until one succeeds.

UI's will be impelemnted as some kind of loadable module for the debconf
implementation used by the installer. Implementation to be determined.

Each item in the main menu is provided by an installer module. Installer
modules indicate that they want to appear on the menu by including the
following special flag in their control file:

	installer-menu-item: nnn

Where nnn is a priority number. The priority number influences the
ordering of items in the menu; higher numbered items are closer to the
end of the menu. If this field does not appear, or has a value of 0, a module
will not appear on the main menu.

The priority numbers are assigned by the debian-install team. Find the
currently assigned numbers in menu-item-numbers.txt. 

Dependencies also influence the position of a module in the menu. A module
will never appear before another module which it (directly or indirectly)
depends on. Behaviour of circular dependencies is undefined.

The short description of the module is used as the text for its menu item.
If we are using a different language than English the
Description-$lang field will be used, just like debconf does.

When a menu item is selected, the module that provides it is configured if
it is not already configured (ie, if it is just unpacked onto the ramdisk).
If it is already configured, it is reconfigured -- its postinst script is
run again.

However, dependencies are honored before this configuration takes place. So
if a module depends on two other modules, and it is selected, both of those
modules will first be configured (if they aren't already).

Note that if a module depends on a virtual package, and more than one
package is available to satisfy that dependency, and none of them are
configured yet, the installer will generate a submenu listing the candidate
packages and let the user choose which to use. The submenu is generated
and ordered similarly to main menu. (TODO: what do we use for the
title and some help for the submenu?)
[ This needs some more thought, I think. ]

The above rules define what the menu looks like and the order of items on it.
There is one other key piece to consider -- the installer has to be able
to pick a reasonable default menu item. To accomplish this, we introduce
a new, special script, that is part of a module's control archive. It's called
the menutest script.

Menutest scripts should return a true value (0) if they think it would be a
good idea if their menu item was default, and a false value if it seems making
their menu item the default would not be a smart decision. For example in case
of a udeb providing an ethernet driver, the menutest script would run a
hardware detection routine and return 0 if the particular ethernet card was
installed.

Menutest scripts are optional. If a module does not have one, a simpler
default test is used: if the module is already configured, then it is not
made the default; if it is unpacked but not configured it is a candidate to 
be the default.

Each time, before the menu is displayed, but after it is ordered, the menutest
script of each menu item is run, in turn. The first menutest script to return
a true value makes its menu item the default.

A Menu Example
--------------

An example -- we have the following packages unpacked onto the installer's
ramdisk (leaving out the parts of their control files that don't matter):

Package: install-media
installer-menu-item: 14
Depends: retriever
Description: Configure installation media

Package: floppy-retriever
Provides: retriever

Package: partitions
installer-menu-item: 35
Depends: disk-driver
Description: Partition disk

Package: disk-driver

Package: format-partitions
installer-menu-item: 50
Depends: partitions, disk-driver
Description: Format and mount partitions

Package: install-base
installer-menu-item: 65
Depends: format-partitions, install-media
Description: Install base system

Package: install-lilo
installer-menu-item: 73
Depends: install-base
Description: Install lilo

Package: rescue-floppy
installer-menu-item: 78
Description: Make a rescue floppy

Package: reboot
installer-menu-item: 100
Description: Reboot the system

(Note that the above package and virtual package names are just examples.)

This set of package results in the following menu:

  - Configure installation media
  - Partition disk
  - Format and mount partitions
  - Install base system
  - Install lilo
  - Make a rescue floppy
  - Reboot the system

To understand why, order all the modules by their installer-menu-item's:

	install-media
	format-partitions	Depends: partitions
	install-base	 	Depends: format-partitions, install-media
	install-lilo    	Depends: install-base
	partitions
	rescue-floppy
	reboot

I've listed any dependencies on other modules that show up on the menu. In
each such case, they have to show up before the item that depends on them.
So partitions has to appear before format-partitions, which has to appear
before install-base. And install-media also has to appear before
install-base. And install-lilo has to appear after install-base. And that's it,
with those dependencies ordered properly, we have the menu order shown above.

It's worth noting that if the user starts up the installer, and picks "install
the base system" as their first step, the following happens:

  - install-media is configured
  - partitions is configured
  - format-partitions is configured
  - finally, install-base is configured

