added some more comments for DrakX code source and usage.

2 files changed, 322 insertions, 68 deletions

diff --git a/docs/README b/docs/README
index 71b23c84d..c7ac25e43 100644
--- a/docs/README
+++ b/docs/README
@@ -1,5 +1,5 @@
 Well here is a little description of what DrakX needs to work in comparison
-to the standard newt install.
+to the RH newt install.
 
 ********************************************************************************
 * CVS **************************************************************************
@@ -33,7 +33,8 @@ just have to issue:
 
 % gendistrib --noclean --distrib <DIRS>
 
-Where <DIRS> is the root of all the media that the install will see:
+Where <DIRS> is the root of all the media that the install will see, this first
+one is the main one :
 
 (1) network or 1-cdrom installs
 	DIRS == the root directory of the Distribution
@@ -41,10 +42,11 @@ Where <DIRS> is the root of all the media that the install will see:
 (2) multi-cdrom install
 	DIRS == the root directories of all the media that the install will see
 
-``gendistrib'' will scan, from the DIRS you provide, for some
-Mandrake/RPMS* directories containing some RPM packages. For multi-cd,
-please use Mandrake/RPMS, Mandrake/RPMS2, etc. For one CD or a network/hd
-volume, please use Mandrake/RPMS.
+``gendistrib'' will scan the file Mandrake/base/hdlists in the main root
+directory (the first one in DIRS) to search for all media used. Typically you
+use Mandrake/RPMS* for RPM packages repository.
+For multi-cd, please use Mandrake/RPMS or Mandrake/RPMS1, Mandrake/RPMS2, etc.
+For one CD or a network/hd volume, please use Mandrake/RPMS.
 
 Optionnally, you can modify ``Mandrake/base/rpmsrate''; this file manages
 the relative importance of the files, and thus their installation or not.
@@ -58,38 +60,62 @@ See below for information about these files.
 First here are the different things needed :
 
 Mandrake/base/hdlists
-	description of the available install media
+	description of the available install media.
+	format is one line for one medium as
+		<hdlist_name> <rpms_directory> <description>
+	<hdlist_name> should be match regexp /hdlist\S*.cz2?/
+	for example (two cd install) you get
+		hdlist1.cz	Mandrake/RPMS1	Boot CD
+		hdlist2.cz	Mandrake/RPMS2	Extension CD
 
 Mandrake/base/hdlist*.cz
 	table of rpm's headers, referred by ``hdlists''
-	! Need to be remade when Mandrake/RPMS changes (with ``gendistrib'') !
+	their contents can be listed using ``packdrake -l <hdlist_file>'' or
+	or ``parsehdlist <hdlist_file>''.
+	! Need to be remade when Mandrake/RPMS* changes (with ``gendistrib'') !
 
-Mandrake/base/depslist
+Mandrake/base/depslist.ordered
 	for each packages, tell which package it depends on. Also contains the
 	size for some (obscure) bloody reasons.
-	! Need to be remade when Mandrake/RPMS changes !
-	(with ``misc/gendepslist2 -o Mandrake/base/depslist Mandrake/base/hdlist.cz2'')
-
-Mandrake/base/depslist.ordered
-	more compact depslist with closure done, internally indexed
+	! Need to be remade when Mandrake/RPMS* changes !
+	(with ``gendistrib --noclean --distrib .'')
 
 Mandrake/base/compss
 	obsoletes comps. It store packages in different categories, generated
 	from the %{GROUP} field
+	! Need to be remade when Mandrake/RPMS* changes !
+	(with ``gendistrib --noclean --distrib .'')
 
 Mandrake/base/rpmsrate
 	ranks and classify packages, so that the installer will know which
-        ones to install (see beginning of perl-install/pkgs.pm for more)
+        ones to install. format is :
+		<intern_group>
+			<level> <packages>
+	where <intern_group> is a symbolic name used in Mandrake/base/compssUsers* files,
+	and <level> defines importance level as described below :
+		5	must have
+		4	important
+		3	very nice
+		2	nice
+		1	maybe
+	by default (for non expert), group selects packages for level 4 (important)
+	and 5 (must have). export mode add 3 (very nice) level. other level (below 2)
+	can only be selected using individual package selection.
 
 Mandrake/mdkinst
 	live system used on certain installs. See ``Ramdisk or not'' below for
 	more.
 
-Mandrake/base/mdkinst_stage2.gz
-	for the ramdisk. live sytem in ext2 filesystem gzipped.
+Mandrake/base/mdkinst_stage2.bz2
+	for the ramdisk. live sytem in ext2 filesystem bzipped2.
 	generated from Mandrake/mdkinst tree using misc/make_mdkinst_stage2
 	See ``Ramdisk or not'' below for more.
 
+Mandrake/base/rescue_stage2.bz2
+	rescue ramdisk. live sytem in ext2 filesystem bzipped2.
+	this is the ramdisk loaded when typing rescue on boot prompt.
+	there is no live system available, only the ramdisk is used.
+
 images/*.img
 	boot images to use with DrakX. Use:
 	- cdrom for cdrom install
@@ -97,17 +123,20 @@ images/*.img
 	- hd for hard-disk install
 	- pcmcia for pcmcia install (see ``PCMCIA install'' below for more)
 
-  the following modules have been removed from:
+	the following modules have been removed from:
           network.img: acenic sk98lin de4x5
           cdrom.img and hd.img: BusLogic seagate fdomain g_NCR5380 dc395x_trm tmscsim
           hd.img: dpt_i2o eata eata_pio eata_dma
           cdrom.img: aztcd gscd isp16 mcd mcdx optcd cm206 sjcd 
           pcmcia.img: apa1480_cb
-  they are now in "other.img", 
+	they are now in "other.img", 
+
+	blank.img is a blank boot image without a kernel nor initrd. this image
+	can be used to generate custom boot disk.
+
+	if you think one of those modules is used a lot, tell me, i may find some room
+	to put it back on the main floppies.
 
-  if you think one of those modules is used a lot, tell me, i may find some room
-  to put it back on the main floppies.
-	
 
 ********************************************************************************
 * logs *************************************************************************
@@ -161,6 +190,7 @@ The DrakX install is much bigger than the newt one. So the ramdisk which was
 used is getting big, and costs a lot in memory 
 (eg: the mdkinst_stage2 is 14MB - 23/09/99)
 (update! now size is 21MB - 24/01/01)
+(update! now size is 19MB - 26/04/01)
 
 |       | newt    | DrakX
 |-------+---------+----------------------------------------------------------
@@ -226,42 +256,6 @@ then, on another computer:
 % DISPLAY=test_machine:0 xwd -root | convert - screenshot.png
 
 ********************************************************************************
-* Adding a new step to DrakX ***************************************************
-********************************************************************************
-Say we want to add a question for setting "alawindows" option.
-We put it pretty early in the install, let's say after "Select Installation
-Class".
-
-1. in install2.pm
-
-add
-
-  selectAlawindows => [ __("A la windows or not"), 0, 1, '' ],
-
-after
-
-  selectInstallClass => [ __("Select installation class"), 1, 1, '' ],
-
-the 0, 1, '' means not "redoable", "skip on error", "don't hide"
-
-2. add your function selectAlawindows in install2.pm
-
-sub selectAlawindows  { $o->selectAlawindows }
-
-3. add your function selectAlawindows in install_steps_interactive.pm
-
-sub selectAlawindows {
-    my ($o) = @_;
-    $o->{alawindows} = $o->ask_yesorno('', _("Throw everything away as windobe does?"), 1);
-}
-
-4. add your function selectAlawindows in install_steps.pm (not needed in that
-case, except for auto_install)
-
-sub selectAlawindows  {}
-
-
-********************************************************************************
 * Miscellaneous ****************************************************************
 ********************************************************************************
 >  o Media access methods: nfs, ftp, http, hd, cdrom
@@ -289,7 +283,7 @@ doesn't contain scsi modules nor ide.
 >  o Text and Graphic mode installers
 >    - Architectural overview of each
 
-have a look at gi/install.fig
+have a look at gi/docs/object_class.fig
 
 
 ********************************************************************************
@@ -304,26 +298,34 @@ have a look at gi/install.fig
 
 many solutions:
 
-- make an install on drive hdb, then either
-   1. dd if=/dev/hdb of=/dev/hdc
-   2. dd if=/dev/hdb of=/dev/hdc count=1 ; kernel_reread /dev/hdc ; 
-      mke2fs /dev/hdc1 ; mount /dev/hdb1 /source ; mount /dev/hdc1 /dest ; cp -a /source /dest
+- make an install on drive hdb, then :
+      dd if=/dev/hdb of=/dev/hdc
+  but you should make sure the hardware is *REALLY* identical.
 
 - try the oem feature
-   3. - burn a cd out of *latest* cooker
+   3. - burn a cd out of *latest* cooker or 8.0 and above.
       - boot on it telling "oem" to syslinux
-      !! it will destroy every data on the harddrive !!
+      !! it will destroy every data on the harddrive or
+         resize (or use free space) if *ONLY* one fat partition is defined !!
       - you now have a very automated install matrix 
       (duplicate it with "dd if=/dev/hdb of=/dev/hdc bs=1M count=730")
 
     put the harddrive in the oem box, the user will now have an *very* automated
-    install, just asking the root password and user password.
+    install, just asking the root password and user password, and some other
+    question according its hardware.
+
+   4. just like 3. but you may have to mount /cdrom after typing rescue on
+      syslinux prompt (oem script do it automatically if a automatic boot nfs
+      network has been done as server is known). under /cdrom may be anything
+      as long as it provides an installation tree of Linux-Mandrake.
+      after that run oem script by typing "/etc/oem -f" for normal installation
+      or "/etc/oem -f server" for server installation (normal with server installed).
 
-   4. (just like 3. without burning a cd, doing the first part by hand)
+   5. (just like 3. without burning a cd, doing the first part by hand)
       have a look at the /etc/oem script on the rescue and do it by hand...
 
 
-cu Pixel.
+cu Pixel, fpons.
 
 
 comments:
diff --git a/docs/README.devel b/docs/README.devel
new file mode 100644
index 000000000..cd0466b35
--- /dev/null
+++ b/docs/README.devel
@@ -0,0 +1,252 @@
+Well here is a little description of how DrakX can be modified or extended.
+Please refer to README file for getting DrakX code source and to known more
+exactly how it works and what it can do.
+
+
+********************************************************************************
+* Execution of DrakX ***********************************************************
+********************************************************************************
+DrakX has originally be written by pixel in perl and C.
+entry point for stage2 is /usr/bin/runinstall2 which is typically a link to
+/usr/bin/install2 which simply load module install2.pm and execute
+install2::main with @ARGV.
+
+install2::main parse command line arguments, prepare installation, find the right
+install_interactive class (take a look at gi/docs/object_class.fig) according to
+command line, memory available and if the interactive chosen is initializing
+correctly, else it will try a less-demanding interactive object.
+Once done, $::o is set to this install & interactive object and main runs the
+various step of install2 defined in $o->{steps}, starting with $o->{steps}{first}
+and iterating with method install_any::getNextStep().
+while running step, it trap any errors that may arise and use perl exception to
+change step.
+
+********************************************************************************
+* DrakX modules descriptions ***************************************************
+********************************************************************************
+Here is a brief description of what each modules of DrakX is doing.
+
+install2: main module of DrakX as described above, main loop execution of DrakX.
+
+install_steps: generic installation module containing steps definition, all steps
+  should always be defined here as some methods may be used on automatic mode.
+  there is no interactivity available. typically are defined base operation for
+  configuring each step according to $o.
+
+install_steps_interactive: generic installation module with generic interative
+  methods. typically are found all interactive code of DrakX for each steps.
+
+install_steps_auto_install: implementation installation module without interactive
+  methods to match auto_install mode. this is the simplest as almost no method are
+  redefined (inherit module install_steps only, compared to other implementation
+  modules described below).
+
+install_steps_stdio: implementation installation module with interactive stdio
+  methods to match stdio mode. inherit modules install_steps_interactive and
+  interative_stdio.
+
+install_steps_newt: implementation installation module with interactive newt
+  methods to match newt mode. inherit modules install_steps_interactive and
+  interactive_newt.
+
+install_steps_gtk: implementation installation module with interactive gtk
+  methods to match gtk mode. inherit modules install_steps_interactive and
+  interactive_gtk.
+
+install_any: contains various methods using generic interactive interface but
+  not used by standalone tools.
+
+install_gtk: contains various methods using gtk interface but not used by
+  standalone tools.
+
+interactive_stdio: implementation methods for interactivity in stdio mode.
+  inherit module interactive.
+
+interactive_newt: implementation methods for interactivity in newt mode.
+  inherit module interactive.
+
+interactive_gtk: implementation methods for interactivity in gtk mode.
+  inherit module interactive.
+
+my_gtk: basic gtk access methods.
+
+any: contains various methods using generic interactive interface. to compare
+  against install_any module as this one is available for standalone tools.
+
+class_discard: simple module that implement every methods undefined to return
+  nothing. this trick is used to ensure no undefined method can arise when using
+  code that reference interactive method which are not defined.
+
+common: contains very simple and very usefull (common) methods to do various task.
+  some methods inspired by functionnal language.
+
+c: contains wrapper to C definition of methods used by DrakX, use of C is necessary
+  for C extern libraries interface (rpmlib, ldetect), kernel interface, XFree
+  interface.
+
+commands: implement some un*x commands, conflicting name with perl contains
+  trailing underscore (_). this module is used by commands perl script that
+  determine which command to run according to $0 (this is used this way when DrakX
+  is running).
+
+run_program: allow running a program with redirection but without using a shell.
+  allow rooted execution.
+
+help: contains all help message displayed by DrakX.
+
+log: log facility methods.
+
+lang: language manipulation methods, get and set sysconfig file, load po.
+
+keyboard: keyboard manipulation methods, get and set sysconfig file, set console
+  keyboard mapping.
+
+mouse: mouse manipulation methods, get and set sysconfig file, change mouse.
+
+timezone: time zone manipulation methods, get and set timezone.
+
+services: services manipulation methods, activate or delete services (see
+  /etc/rc.d/init.d directories).
+
+detect_devices: manage detection of various class of hardware.
+
+devices: manage device file, create device special according device name.
+
+partition_table: base partition table management methods, it manages
+  appriopriate partition_table_XXX object according to what has been read
+  as XXX partition table type.
+
+partition_table_raw: generic class for the following partition_table_XXX.
+
+partition_table_emtpy: matches an empty partition table.
+
+partition_table_dos: matches a DOS partition table.
+
+partition_table_bsd: matches a BSD partition table.
+
+partition_table_mac: matches an Apple partition table.
+
+partition_table_sun: matches a Sun Label partition table.
+
+fs: read and write /etc/fstab file, mount and umount, format.
+
+fsedit: manage (modyfy, edit) mount point associated to partition (like editing
+  /etc/fstab).
+
+swap: swap management methods, format and mount (activation).
+
+raid: raid (software only) management methods.
+
+lvm: lvm (Logical Volume Manager) management methods.
+
+loopback: loopback management methods, used for lnx4win type installation or using
+  a file as a partition.
+
+diskdrake: diskdrake itself, disk graphical (using gtk) manipulation tools.
+
+ftp: ftp mangement methods, used when using ftp install.
+
+http: http management methods, used when using http install.
+
+modparm: kernel modules options management, allow building nice dialog with each
+  module parameter available.
+
+modules: kernel modules management, allow loading or unloading (ala modprobe or
+  insmod).
+
+printer: printer management methods, read and write both LPR or CUPS configuration.
+
+printerdrake: interactive printer management methods.
+
+network: network management methods, get and set sysconfig file.
+
+netconnect: network configuration wizard.
+
+netconnect_const: network configuration wirard data.
+
+Xconfig: X configuration (monitor + already existing config file) management.
+
+Xconfigurator: X configuration wizard.
+
+Xconfigurator_const: X configuration wizard data.
+
+booloader: bootloader (LILO, GRUB, LOADLIN, SILO) configuration management methods.
+
+pkgs: rpm package and hdlist, depslist management methods, allow selecting or
+  unselecting packages, manage rpmsrate file and select group, installation and
+  removal methods of rpm file.
+
+crypto: *obsoleted* module to manage crypto site and rpm file.
+
+standalone: standalone only, allow defining a standalone tools.
+
+bootlook: standalone only, interface with DrakConf to configure bootloader options.
+
+tinyfirewall: standalone only, interface with DrakConf to configure a tiny firewall.
+
+********************************************************************************
+* DrakX FAT resizer module description *****************************************
+********************************************************************************
+here is a fat resizer written in perl and C used by DrakX (diskdrake) to resize
+FAT16/FAT32 partition. it moves clusters to make sure a shrink can be done on the
+limit of the partition itself, if no cluster need to be moved, only boot sector
+partition limit are modified.
+
+any: various methods to flag cluster, compute min size.
+
+boot_sector: boot sector management methods.
+
+c_rewritten: originally resize_fat was only perl, this contains code section that
+  are the most sensible to speed or memory contraints and have been rewritten to C
+  using perl extension.
+
+dir_entry: manage directory structure.
+
+directory: traverse directory recursively, needed to move correctly cluster.
+
+fat: manage fat structure.
+
+info_sector: manage info sector.
+
+io: manage I/O on disk (need to take care of big file as partition size may be
+  larger than 2GB).
+
+main: main resizer algortihm. if needed allocate new clusters, copy files, copy
+  directories. update boot sector info.
+
+********************************************************************************
+* Adding a new step to DrakX ***************************************************
+********************************************************************************
+Say we want to add a question for setting "alawindows" option.
+We put it pretty early in the install, let's say after "Select Installation
+Class".
+
+1. in install2.pm
+
+add
+
+  selectAlawindows => [ __("A la windows or not"), 0, 1, '' ],
+
+after
+
+  selectInstallClass => [ __("Select installation class"), 1, 1, '' ],
+
+the 0, 1, '' means not "redoable", "skip on error", "don't hide"
+
+2. add your function selectAlawindows in install2.pm
+
+sub selectAlawindows  { $o->selectAlawindows }
+
+3. add your function selectAlawindows in install_steps_interactive.pm
+
+sub selectAlawindows {
+    my ($o) = @_;
+    $o->{alawindows} = $o->ask_yesorno('', _("Throw everything away as windobe does?"), 1);
+}
+
+4. add your function selectAlawindows in install_steps.pm (not needed in that
+case, except for auto_install)
+
+sub selectAlawindows  {}
+
+