#section: Introduction

	<sgml>
	A gurus is a set of dialogs used to perform a tasks. Because that
	tasks is either complex, or not performed often, it is broken
	into a set of very simple dialogs. Each dialog is generally
	verbose, and has only a few input fields (often one). The user
	can concentrate on the question at hand.

	Each dialog generally only have a "next", a "back" and a "help"
	button.

	To avoid writing redundant and error prone code, we create a
	bunch of TLMP
	framework components to take care of the details. This includes

	<itemize>
	<item>Compute the layout of the map and handle the display.
	<item>Update the map.
	<item>control the navigation in the map.
	</itemize>

	A guru may be used to create a new configuration or to review one.
	</sgml>

	(see <htmlurl
			name=http://www.solucorp.qc.ca/tlmp	
			url=http://www.solucorp.qc.ca/tlmp
		> for details about TLMP)

	#spec: guru / map / principles

#section: The eval and dialog nodes

	The goal of the TLMP frameworks is to reduce your work. You work
	may be presented like this:

	<sgml>
	<itemize>
	<item>Creating control graph.
	<item>For each node of the graph (a node is a dialog)
		you provide the implementation of the eval and dialog
		function.
	</itemize>
	</sgml>

	#subsection:
	#section: The eval function

		<sgml>
		This is generally a small function. It receives an object
		GURUPATH_STATUS and fill the following field:

		<itemize>
		<item>is_possible

			Is this dialog reachable ? Is it meaningful ?

			The variable is set to true or false based on
			previous answers (previous dialogs). For example
			a node requesting the default gateway is useless
			if the user has selected dhcp to configure the
			network interface.

		<item>is_filled

			Are the value presented in the dialog already filled ?

		<item>some_errors

			If the values are filled, they are validated. The validation
			may be extensive. For example, a dialog requesting the default
			gateway may check the following things;

			<itemize>
			<item>The IP number is valid.
			<item>The IP number is a member of one of the networks
				attached to the interfaces.
			</itemize>
		</itemize>

		If this eval function is the last node of a row, you can use
		the "setterminal" function. This function expects two
		string arguments:

		<itemize>
		<item>const char *shortext

			This is a short line which will be appended at the
			end of the row on the graphical map.

		<item>const char *longtext

			This is a paragraph shown (not yet, sorry) when the user
			move the mouse over one area of the map.
		</itemize>
		</sgml>

		You must also use the settitle function to set the title
		of this node dialog. The settitle is used in the eval function
		because the title is collected to enhance the map presentation
		and build the node dialog. The settitle function expect a single
		string.

	#section: The dialog function

		<sgml>
		This function describes the dialog to present. It receives
		a DIALOG object called dia, so the dialog may contains
		any fields type found in a normal Linuxconf dialog.

		Unlike a normal linuxconf dialog, this one expects a
		DIALOG::newline between fields as needed.

		In the dialog function, you have access to few function
		controlling the presentation:

		<itemize>
		<item>setintro(const char *);

			You pass the introduction text of the dialog here. This is
			generally several lines of explanation.

		<item>edit([HELP_FILE &]);

			This triggers the presentation of the dialog. It returns
			true if the user has accepted the input (by hitting next).
			It returns false if the user escape away (hit the "back" button).

			When edit returns true, you can validate the input. If they
			are wrong, you can present some errors (using xconf_error())
			and call edit again.

		<item>setbutinfo (int id, const char *title, const char *icon);

			This allows you to add extra buttons at the bottom of the
			dialog. If you do so, you will need a dobutton
			function.
		</itemize>
		</sgml>

	#section: The dobutton function

		This one is seldom used. If you need an extra button
		for a dialog (a probe button to configure a hardware
		component for example).

		The dobutton function is passing the id (int id) you passed
		using the setbutinfo() function.

	#endsub:

#section: TLMP components
	#subsection:
	#section: gurumanage
		#function: gurumanage
	#section: gurupath
		#spec: guru samples / basic gurupath

	#section: gurupath functions

		#function: gurupath
		#function: _F_gurupath::settitle
		#function: _F_gurupath::setintro
		#function: _F_gurupath::setterminal
		#function: _F_gurupath::edit
		#function: _F_gurupath::eval
		#function: _F_gurupath::dialog
		#function: _F_gurupath::path1
		#function: _F_gurupath::dobutton
		#ignore: _F_gurupath::path2
		#ignore: _F_gurupath::path3
		#ignore: _F_gurupath::path4
		#ignore: _F_gurupath::path5
		#ignore: _F_gurupath::path6

	#section: gurusteps
		#spec: gurusteps / principles

	#section: gurusteps functions

		<sgml>
		gurusteps provides the following tags
		<itemize>
		<item>eval1 through eval6. eval1 is mandatory.
		<item>dialog1 through dialog6. dialog1 is mandatory.
		<item>path1 through path6, all optional
		</itemize>
		</sgml>

		#function: gurusteps
		#function: _F_gurusteps::settitle
		#function: _F_gurusteps::setintro
		#function: _F_gurusteps::setterminal
		#function: _F_gurusteps::edit
		#function: _F_gurusteps::path1
		#ignore: _F_gurusteps::path2
		#ignore: _F_gurusteps::path3
		#ignore: _F_gurusteps::path4
		#ignore: _F_gurusteps::path5
		#ignore: _F_gurusteps::path6
		#ignore: _F_gurusteps::eval2
		#ignore: _F_gurusteps::eval3
		#ignore: _F_gurusteps::eval4
		#ignore: _F_gurusteps::eval5
		#ignore: _F_gurusteps::eval6
		#ignore: _F_gurusteps::dialog2
		#ignore: _F_gurusteps::dialog3
		#ignore: _F_gurusteps::dialog4
		#ignore: _F_gurusteps::dialog5
		#ignore: _F_gurusteps::dialog6

	#section: guruiter
		#spec: guruiter / principles

	#section: guruiter functions

		<sgml>
		guruiter provides the following tags
		<itemize>
		<item>eval, which is mandatory.
		<item>dialog, which is mandatory.
		<item>path1 through path6, all optional
		</itemize>
		</sgml>


		#function: guruiter
		#function: _F_guruiter::settitle
		#function: _F_guruiter::setintro
		#function: _F_guruiter::setterminal
		#function: _F_guruiter::edit
		#function: _F_guruiter::path1
		#ignore: _F_guruiter::path2
		#ignore: _F_guruiter::path3
		#ignore: _F_guruiter::path4
		#ignore: _F_guruiter::path5
		#ignore: _F_guruiter::path6
	#endsub:

#section: Samples
	#subsection:
	#section: A simple case

		#spec: guru samples / simple

	#section: A simple case, 2 branches

		#spec: guru samples / one choice

	#section: Iteration

		#spec: guru samples / repeating a step a few times

	#section: Combining gurus

		#spec: guru samples / combining chunk of code

	#endsub: