		      API for YaST2 installation proposal

Author:	 Stefan Hundhammer <sh@suse.de>
Updated: 2003-01-28


				  Motivation
				  ==========

After five releases, YaST2 is now smart enough to make reasonable proposals for
(near) every installation setting, thus it is no longer necessary to ask the
user that many questions during installation: Most users simply hit the [next]
button anyway.

Hence, YaST2 now collects all the individual proposals from its submodules and
presents them for confirmation right away. The user can change each individual
setting, but he is no longer required to go through all the steps just to
change some simple things. The only that (currently) really has to be queried
is the installation language - this cannot reasonably be guessed (yet?).

The new YaST2 installation includes the following steps:

- (Minimal) hardware probing - no user interaction required

- Language selection - user picks installation language

- Installation proposal - very much like the old installation summary just
  before the real installation started, only this time the user CAN change
  settings by clicking into the summary (or via a separate menu as a
  fallback).

- Create / format partitions according to proposal / user selection - no user
  interaction required

- Install software packages from CD / DVD / other installation media


After this, all that is remained left is basic system configuration like:

- X11
- Network interface(s)
- Network services
- Additional hardware (printer, sound card, scanner, ...)



				   Overview
				   ========


YaST2 installation modules should cooperate with the main program in a
consistent API. General usage:


- inst_proposal (main program) creates empty dialog with RichText widget

- inst_proposal calls each sub-module in turn to make proposal

- user may choose to change individual settings (i.e., clicks on a hyperlink)

  -> inst_proposal starts that module's sub-workflow which runs independently.
     After this, inst_proposal tells all subsequent (all?) modules to check
     their states and return whether a change of their proposal is necessary
     after the user interaction.

- main program calls each sub-module to write the settings to the system


			   The Dispatcher Interface
			   ========================

Each submodule provides a function dispatcher that can be called with
'CallFunction()'. The function to be called is passed as a parameter to this
dispatcher. Parameters to the function are passed as another parameter in a
map.  The result of each call is a map, the contents of which depend on the function
called.

The reason for this additional overhead is to provide extensibility and
reusability for the installation workflow: A list of submodules to be called is
read from file. This requires, however, that no explicit 'mod::func()' calls
are used in 'inst_proposal.ycp'. Rather, the list contains the name of the
submodule. Since each submodule is required to provide an identical API, this
is sufficient.

Example:

Proposal is to call

	 - input_devices (keyboard, mouse)
	 - partitioning
	 - software_selection
	 - boot_loader
	 - timezone

=> inst_proposal calls
   map result = CallFunction (input_devices( "MakeProposal", $[ "force_reset"     : false,
							        "language_changed": false ] ) );
   map result = CallFunction (partitioning ( "MakeProposal", $[ "force_reset"	  : false,
							        "language_changed": false ] ) );
   ...

If the user clicks on the hyperlink on "input_devices" in the proposal display,
inst_proposal calls

   map result = CallFunction (input_devices( "AskUser", $[ "has_next": true ] ) );



				 API functions
				 =============

NOTE: If any parameter is marked as "optional", it should only be specified if
it contains a meaningful value. Don't add it with a 'nil' value.


The dispatcher provides the following functions:


map MakeProposal( boolean force_reset, boolean language_changed );

	Make proposal for installation.

	Params:
		force_reset

		If 'true', discard anything that may be cached and start over
		from scratch. If 'false', use cached values from the last
		invocation if there are any.


		language_changed

		The installation language has changed since the last call of
		"MakeProposal". This is important only if there is a language
		change mechanism in one of the other submodules. If this parameter
		is "true", any texts the user can see in the proposal need to be
		retranslated. The internal translator mechanism will take care of
		this itself if the corresponding strings are once more put through
		it (the _("...") function). Only very few submodules that translate
		any strings internally based on internal maps (e.g., keyboard etc.)
		need to take more action.


	Returns a map containing:

		string preformatted_proposal (optional)

			Human readable proposal preformatted in HTML.
			Note: Use the HTML:: module for such formatting.


		list raw_proposal

			(only used if 'preformatted_proposal' is not present in
			the result map)

			Human readable proposal, not formatted yet.
			The caller will format each list item (string) as a
			HTML list item ( "<li> ... </li>" ).

			The caller will make a HTML unsorted list of this, e.g.:

			<ul>
			    <li>string from list element #1</li>
			    <li>string from list element #2</li>
			    <li>string from list element #3</li>
			    ...
			</ul>


		string warning (optional)

			Warning in human readable format without HTML tags
			other than <br>.

			The warning will be embedded in appropriate HTML format
			specifications according to 'warning_level' below.


		symbol warning_level (optional)

			Determines the severity and the visual display of the
			warning. Valid values:

			`notice
			`warning (default)
			`error
			`blocker
			`fatal

			`blocker will prevent the user from continuing the
			installation. If any proposal contains a `blocker
			warning, the "accept" button in the proposal dialog
			will be disabled - the user needs to fix that blocker
			before continuing.

			`fatal is like `blocker but also stops building
			the proposal

		boolean language_changed (optional)

			This module just caused a change of the installation
			language. This is only relevant for the "language"
			module.

		boolean mode_changed (optional)

			This module just caused a change of the installation
			mode. This is only relevant for the "inst mode"
			module.

		boolean rootpart_changed (optional)

			This module just caused a change of the root partition.
			This is only relevant for the "root part" module.



map AskUser( boolean has_next )

	Run an interactive workflow - let user decide upon values he might want
	to change. May contain one single dialog, a sequence of dialogs or one
	master dialog with one or more "expert" dialogs. The module is
	responsible for controlling the workflow sequence (i.e., "next", "back"
	buttons etc.).

	Submodules don't provide an "abort" button to abort the entire
	installation. If the user wishes to  do that, he can always go back to
	the main dialog (the installation proposal) and choose "abort" there.


	Params:
		has_next

		Use a "next" button even if the module by itself has only one
		step, thus would normally have an "OK" button - or would rename
		the "next" button to something like "finish" or "accept".

	Returns a map containing:

		symbol workflow_sequence

			(like in 7.3) - What does this mean?

			`next (default)
				Everything OK - continue with the next step in
				workflow sequence. - What workflow sequence?

			`back
				User requested to go back in the workflow sequence.

			`again
				Call this submodule again (i.e., re-initialize
				the submodule)

			`auto
				Continue with the workflow sequence in the
				current direction - forward if the last
				submodule returned `next, backward otherwise.

			`finish
				Finish the installation. This is specific to
				"inst_mode.ycp" when the user selected "boot
				system" there.


		boolean language_changed (optional)

			This module just caused a change of the installation
			language. This is only relevant for the "language"
			module.


map Description()

	Return human readable titles both for the RichText (HTML) widget and
	for menuentries.

	Returns a map containing:

		string rich_text_title

			(Translated) human readable title for this section in
			the RichText widget without any HTML formatting. This
			will be embedded in

			<h3><a href="???"> ... </a></h3>

			- so make sure not to add any additional HTML
			formatting.

			Keyboard shortcuts are not (yet?) supported, so don't
			include any '&' characters.

			Example: "Input devices"


		string menu_title

			(Translated) human readable menuentry for this
			section. Must contain a keyboard shortcut ('&'). Should
			NOT contain trailing periods ('...') - the caller will
			add them.

			Example: "&Input devices"


		string id

			Programmer readable unique identifier for this section.
			This is not auto-generated to keep the log file
			readable.

			Example: "input_dev"

	This map may be empty. In this case, this proposal section will
	silently be ignored. Proposals modules may use this if there is no
	useful proposal at all. Use with caution - this may be confusing for
	the user.

	Note: In this case, all other proposal functions must return a useful
	success value so they can be called without problems.


map Write()

	Write the proposed (and probably modified) settings to the system.
	It is up to the proposal dispatcher how it remembers the settings.
	The errors must be reported using the Report:: module to have
	the possibility to control the behaviour from the main program.

	This Write() function is optional. The dispatcher module is required
	to allow this function to be called without returning an error value
	if it isn't there.

	Returns a map containing:

		boolean success

			Returns true, if the settings were written
			successfully.
