PODify the installer

7 files changed, 493 insertions, 3 deletions

diff --git a/perl-install/install/any.pm b/perl-install/install/any.pm
index fecd03c1b..1176c8e0a 100644
--- a/perl-install/install/any.pm
+++ b/perl-install/install/any.pm
@@ -208,6 +208,12 @@ sub prep_net_suppl_media {
     sleep(3);
 }
 
+=item ask_suppl_media_url($o, $method, $o_url)
+
+Ask which actual server or mirror to use
+
+=cut
+
 sub ask_suppl_media_url {
     my ($o, $method, $o_url) = @_;
 
@@ -707,6 +713,14 @@ sub set_rpmsrate_category_flags {
 }
 
 
+
+=item rpmsrate_always_flags($o)
+
+Set flags for selecting packages in rpmsrate according to available hardware.
+Eg selecting software to burn CD/DVDs if a CD/DVD writer is installed
+
+=cut
+
 sub rpmsrate_always_flags {
     my ($o) = @_;
 
@@ -752,6 +766,13 @@ sub rpmsrate_always_flags {
     $rpmsrate_flags_chosen;
 }
 
+
+=item default_bootloader()
+
+Return the default bootloader to use according to the platform (UEFI, bios, ...)
+
+=cut
+
 sub default_bootloader() {
     require bootloader;
     my (undef, $p) = bootloader::get_grub2_pkg();
@@ -848,6 +869,14 @@ Do you really want to remove these packages?
     }
 }
 
+
+=item addToBeDone($f, $step)
+
+The I<$f> function will be executed if $step has already been completed.
+Else it is stored to be run later when $step is completed.
+
+=cut
+
 sub addToBeDone(&$) {
     my ($f, $step) = @_;
 
@@ -900,6 +929,13 @@ sub log_system_info {
 #-###############################################################################
 sub auto_inst_file() { "$::prefix/root/drakx/auto_inst.cfg.pl" }
 
+=item report_bug()
+
+Write the Drakx report in order to review eg a failed installation.
+See any::report_bug()
+
+=cut
+
 sub report_bug() {
     any::report_bug('auto_inst' => g_auto_install('', 1));
 }
@@ -1028,6 +1064,22 @@ sub selected_leaves_pl {
       $str;
 }
 
+=item loadO($O, $f)
+
+Retrieve the auto installation configuration
+
+=over 4
+
+=item * Retrieveing auto_inst.cfg.pl file, either on a local disk or by downloading it
+
+=item * Adusting $o for the parameters loaded from auto_inst.cfg.pl
+
+=item * Handling any old format parameter
+
+=back
+
+=cut
+
 sub loadO {
     my ($O, $f) = @_; $f ||= auto_inst_file();
     if ($f =~ /^(floppy|patch)$/) {
@@ -1082,6 +1134,12 @@ sub loadO_ {
     $o;
 }
 
+=item sub handle_old_auto_install_format($o)
+
+Convert the auto install parameter for any API change.
+
+=cut
+
 sub handle_old_auto_install_format {
     my ($o) = @_;
 
diff --git a/perl-install/install/install2.pm b/perl-install/install/install2.pm
index a12954d23..5d7c21f27 100644
--- a/perl-install/install/install2.pm
+++ b/perl-install/install/install2.pm
@@ -9,7 +9,30 @@ BEGIN { $::isInstall = 1 }
 
 =head1 SYNOPSYS
 
-The installer stage2 real entry point
+The installer stage2 real entry point.
+This module implements the main loop execution of DrakX:
+
+=over 4
+
+=item * parse command line arguments,
+
+=item * prepare installation,
+
+=item * find the right install/interactive class according to command line,
+
+=item * check memory available and if the interactive chosen is initializing correctly,
+
+=item * else it will try a less-demanding interactive object.
+
+=item * 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,
+
+=item * it trap any errors that may arise and use perl exception to
+change step.
+
+=back
 
 =cut
 
@@ -105,6 +128,10 @@ $o = $::o = {
 
 =over
 
+=item installStepsCall($o, $auto, $fun, @args)
+
+Call the $fun step. It's used by the various step stubs below.
+
 =cut
 
 sub installStepsCall {
@@ -427,10 +454,14 @@ sub stop_udev() {
 
 =back
 
-=head1 Other Functions
+=head1 Other Functions: main() and its helpers
 
 =over
 
+=item init_local_install($o)
+
+Initialize the DrakX installer for a local install (eg: using ../tools/drakx-in-chroot)
+
 =cut
 
 #-######################################################################################
@@ -445,6 +476,13 @@ sub init_local_install {
 	$o->{mouse} = mouse::fullname2mouse('Universal|Any PS/2 & USB mice');
 }
 
+=item pre_init_brltty()
+
+Check for any "brltty=" parameter on the kernel command line and set up the parameters accordingly.
+
+=cut
+
+
 sub pre_init_brltty() {
     if (my ($s) = cat_("/proc/cmdline") =~ /brltty=(\S*)/) {
 	my ($driver, $device, $table) = split(',', $s);
@@ -456,12 +494,27 @@ sub pre_init_brltty() {
     }
 }
 
+=item init_brltty()
+
+Actually starts brltty if needed.
+
+=cut
+
 sub init_brltty() {
     symlink "/tmp/stage2/$_", $_ foreach "/etc/brltty";
     devices::make($_) foreach $o->{brltty}{device};
     run_program::run("brltty");
 }
 
+
+=item init_auto_install()
+
+Set up the auto installation if the proper parameter was passed on the kernel command line.
+That means retrieving the auto install file.
+
+=cut
+
+
 sub init_auto_install() {
     if ($::auto_install =~ /-IP(\.pl)?$/) {
         my ($ip) = cat_('/tmp/stage1.log') =~ /configuring device (?!lo)\S+ ip: (\S+)/;
@@ -487,6 +540,29 @@ sub init_auto_install() {
     }
 }
 
+=item step_init($o)
+
+Initialize the proper steps backend (auto, text or graphical).
+If it fails to initialize, the installer will default to text mode ("ncurses").
+
+The default is "gtk"
+
+The various modes are:
+
+=over 4
+
+=item * "auto" (the automatic mode - but some steps can be specified as interactive)
+
+=item * "gtk" (the default graphical mode unless specified otherwise or unless there's not enough memory)
+
+=item * "interactive" (the text mode, which can be choosen by either the "newt" or "text" options)
+
+=item * "stdio" (an alternative text mode
+
+=back
+
+=cut
+
 sub step_init {
   my ($o) = @_;
   my $o_;
@@ -521,6 +597,13 @@ sub read_product_id() {
     }->{$o->{product_id}{product}} || 'download';
 }
 
+=item sig_segv_handler() {
+
+Handle a segmentation fault in the installer.
+
+=cut
+
+
 sub sig_segv_handler() {
     my $msg = "segmentation fault: install crashed (maybe memory is missing?)\n" . backtrace();
     log::l("$msg\n");
diff --git a/perl-install/install/media.pm b/perl-install/install/media.pm
index 149deffc3..ab62e7230 100644
--- a/perl-install/install/media.pm
+++ b/perl-install/install/media.pm
@@ -833,6 +833,13 @@ sub _get_medium_dir {
     }
 }
 
+
+=item install_urpmi($stage2_method, $packages)
+
+Write the urpmi configuration according to the media that were used to install the OS.
+
+=cut
+
 sub install_urpmi {
     my ($stage2_method, $packages) = @_;
 
diff --git a/perl-install/install/steps.pm b/perl-install/install/steps.pm
index a7394b28c..f62566f4c 100644
--- a/perl-install/install/steps.pm
+++ b/perl-install/install/steps.pm
@@ -26,6 +26,29 @@ use log;
 
 our @ISA = qw(do_pkgs);
 
+
+=head1 SYNOPSYS
+
+Generic installation module containing steps definition.
+Handle the base installer steps.
+
+This 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.
+
+It is inherited by other steps_* modules (who also inherit from the
+proper interactive::* module).
+
+=head1 Functions
+
+=over
+
+=cut
+
+
 @filesToSaveForUpgrade = qw(
 /etc/ld.so.conf /etc/fstab /etc/hosts /etc/conf.modules /etc/modules.conf
 );
@@ -48,13 +71,37 @@ sub charsetChanged {
     my ($_o) = @_;
 }
 
+
+
 #-######################################################################################
 #- In/Out Steps Functions
 #-######################################################################################
+
+=back
+
+=head2 In/Out Steps Functions
+
+=over
+
+=item enteringStep($_o, $step)
+
+Log that a new step has begun.
+
+=cut
+
 sub enteringStep {
     my ($_o, $step) = @_;
     log::l("starting step `$step'");
 }
+
+=item leavingStep($_o, $step)
+
+Log that a new step has finished.
+Refresh the logs in /mnt/root/drakx with the latest installer logs from /tmp.
+Then
+
+=cut
+
 sub leavingStep {
     my ($o, $step) = @_;
     log::l("step `$step' finished");
@@ -88,6 +135,14 @@ Continue at your own risk."), formatError($err) || $err ]);
     }
 }
 
+
+=item errorInStep($_o, $err)
+
+Handle a failing step.
+The base class just exists.
+
+=cut
+
 sub errorInStep { 
     my ($_o, $err) = @_;
     print "error :(\n"; 
@@ -100,6 +155,32 @@ sub kill_action {}
 #- Steps Functions
 #-######################################################################################
 #------------------------------------------------------------------------------
+
+=back
+
+=head2 Steps Functions
+
+Those functions define the base steps.
+They can be overloaded in either:
+
+=over 4
+
+=item * L<steps_auto> for auto install
+
+=item * L<steps_interactive> for interactive text or graphic install
+
+=item * L<steps_gtk> for specialized graphical GUIs
+
+=back
+
+=over
+
+=item selectLanguage($o)
+
+This step enables to select the language
+
+=cut
+
 sub selectLanguage {
     my ($o) = @_;
 
@@ -139,6 +220,14 @@ sub selectLanguage {
     } 'installPackages';
 }
 #------------------------------------------------------------------------------
+
+
+=item selectKeyboard($o)
+
+This step enables to select the keyboard to use during the installation and in the installed system after boot.
+
+=cut
+
 sub selectKeyboard {
     my ($o) = @_;
     keyboard::setup_install($o->{keyboard});
@@ -151,6 +240,12 @@ sub selectKeyboard {
     } 'installPackages' if !$o->{isUpgrade} || !$o->{keyboard}{unsafe};
 }
 #------------------------------------------------------------------------------
+
+=item acceptLicense()
+
+This step enforces accepting the license before continuing
+
+=cut
 sub acceptLicense {}
 
 #------------------------------------------------------------------------------
@@ -287,6 +382,15 @@ sub choosePackages {
     $availableCorrected;
 }
 
+=item live_patch_URPM()
+
+This function is used when upgrading a Red Hat or a Conectiva installation.
+It live patches URPM::Package::compare_pkg() and URPM::Package::compare()
+so that Mageia packages are always preferred over existing packages that came
+from a different vendor.
+
+=cut
+
 sub live_patch_URPM() {
 
     sub prefering_mga {
@@ -321,12 +425,21 @@ sub live_patch_URPM() {
     };
 }
 
+
+
 sub upgrading_redhat() {
     #- remove weird config files that bother Xconfig::* too much
     unlink "$::prefix/etc/X11/XF86Config";
     unlink "$::prefix/etc/X11/XF86Config-4";
 }
 
+=item beforeInstallPackages($o)
+
+It's called just before installing packages.
+If we're upgrading a Red Hat installtion, it'll live patch URPM first.
+
+=cut
+
 sub beforeInstallPackages {
     my ($o) = @_;
 
@@ -402,7 +515,14 @@ sub beforeInstallPackages {
     system("sh", "-c", $o->{preInstallNonRooted}) if $o->{preInstallNonRooted};
 }
 
-#- returns number of packages installed, 0 if none were selected.
+
+=item pkg_install($o, @l)
+
+Select the requested packages (@l) then install them using installPackages() if they're not already installed.
+Returns number of packages installed, 0 if none were selected.
+
+=cut
+
 sub pkg_install {
     my ($o, @l) = @_;
     log::l("selecting packages " . join(" ", @l));
@@ -420,11 +540,24 @@ sub pkg_install {
     }
 }
 
+=item installCallback()
+
+The default package installation callback. It does nothing.
+It's overidden in text & graphicall installations in order to display a nice progress bar.
+
+=cut
+
 sub installCallback {
 #    my (undef, $msg, @para) = @_;
 #    log::l("$msg: " . join(',', @para));
 }
 
+=item installPackages($o, $o_interactive)
+
+Install the selected packages.
+
+=cut
+
 sub installPackages {
     my ($o, $o_interactive) = @_;
 
@@ -586,6 +719,12 @@ EOF
     }
 }
 
+=item install_urpmi($o)
+
+If needed, write the urpmi configuration according to the media that were used to install the OS.
+
+=cut
+
 sub install_urpmi {
     my ($o) = @_;
 
@@ -847,6 +986,23 @@ sub miscellaneousAfter {
 }
 
 #------------------------------------------------------------------------------
+
+=item exitInstall($o)
+
+Cleanly exit the installer:
+
+=over 4
+
+=item * running any post script for auto install ("postInstallNonRooted" and "postInstall")
+
+=item * saving the install report in /root.drakx/report.bug.xz
+
+=item * umounting the installer media
+
+=back
+
+=cut
+
 sub exitInstall { 
     my ($o) = @_;
 
@@ -884,6 +1040,19 @@ risk!
 }
 
 #------------------------------------------------------------------------------
+
+=back
+
+=head2 Network Functions
+
+=over 4
+
+=item hasNetwork($o)
+
+Whether the network is configured for internet.
+
+=cut
+
 sub hasNetwork {
     my ($o) = @_;
     $o->{net}{type} && $o->{net}{network}{NETWORKING} ne 'no' and return 1;
@@ -891,23 +1060,48 @@ sub hasNetwork {
     0;
 }
 
+=item network_is_cheap($o)
+
+Whether the network is fast enough to use (aka not ISDN and the like)
+
+=cut
+
 sub network_is_cheap {
     my ($o) = @_;
     member($o->{net}{type}, qw(adsl lan cable));
 }
 
+=item start_network_interface($o)
+
+Start the network on the specified interface.
+
+=cut
+
 sub start_network_interface {
     my ($o) = @_;
     require network::tools;
     network::tools::start_net_interface($o->{net}, 0);
 }
 
+=item stop_network_interface($o)
+
+Stop the network on the specified interface.
+
+=cut
+
 sub stop_network_interface {
     my ($o) = @_;
     require network::tools;
     network::tools::stop_net_interface($o->{net}, 0);
 }
 
+
+=item upNetwork($o, $b_pppAvoided)
+
+Start the network if configured and fast enough (or if PPP is authorized).
+
+=cut
+
 #------------------------------------------------------------------------------
 sub upNetwork {
     my ($o, $b_pppAvoided) = @_;
@@ -937,6 +1131,13 @@ sub upNetwork {
 }
 
 #------------------------------------------------------------------------------
+
+=item downNetwork($o)
+
+Stop the network if it's no a network installation.
+
+=cut
+
 sub downNetwork {
     my ($o, $costlyOnly) = @_;
 
@@ -957,6 +1158,19 @@ sub downNetwork {
 }
 
 #------------------------------------------------------------------------------
+
+=back
+
+=head2 Misc Functions
+
+=over
+
+=item cleanIfFailedUpgrade($o)
+
+Clean a failed install, saving the important files.
+
+=cut
+
 sub cleanIfFailedUpgrade($) {
     my ($o) = @_;
 
@@ -971,5 +1185,8 @@ sub cleanIfFailedUpgrade($) {
     }
 }
 
+=back
+
+=cut
 
 1;
diff --git a/perl-install/install/steps_auto_install.pm b/perl-install/install/steps_auto_install.pm
index ceaab7ed3..bda7e5218 100644
--- a/perl-install/install/steps_auto_install.pm
+++ b/perl-install/install/steps_auto_install.pm
@@ -12,6 +12,17 @@ use vars qw(@ISA $graphical @graphical_steps);
 use common;
 use install::steps;
 
+=head1 SYNOPSYS
+
+Implement the 'automatic' installation backend.
+Basically messages are ignored, warnings are displayed.
+
+This is the simplest module as almost no method are redefined (inherit
+module L<install::steps> only, compared to other implementation
+modules).
+
+=cut
+
 sub new {
     my ($type, $o) = @_;
 
diff --git a/perl-install/install/steps_gtk.pm b/perl-install/install/steps_gtk.pm
index a9ef359be..e22f12077 100644
--- a/perl-install/install/steps_gtk.pm
+++ b/perl-install/install/steps_gtk.pm
@@ -25,9 +25,38 @@ use mouse;
 use install::help::help;
 use log;
 
+=head1 SYNOPSYS
+
+Implement a cople specialized graphical installer steps.
+
+=head1 Setup Functions
+
+=over
+
+=cut
+
 #-######################################################################################
 #- In/Out Steps Functions
 #-######################################################################################
+
+
+
+=item new($type, $o)
+
+Initialize the graphical installer:
+
+=over 4
+
+=item * Starts a X.org server
+
+=item * Starts the Spice integration if in a qemu VM
+
+=item * Initialize Gtk+, the theme, and the various used windows
+
+=back
+
+=cut
+
 sub new($$) {
     my ($type, $o) = @_;
 
@@ -66,6 +95,14 @@ sub new($$) {
     $o;
 }
 
+=item _setup_and_start_X($o, $wanted_DISPLAY)
+
+Select the proper X.org server & driver to use (either X.org or Xnest server when running a local test).
+In the former case, it will try first the 'fbdev' driver then the 'vesa' driver if 'fbdev' failed or if the computer uses UEFI.
+
+=cut
+
+
 sub _setup_and_start_X {
     my ($o, $wanted_DISPLAY) = @_;
     my $f = "/tmp/Xconf";
@@ -106,6 +143,12 @@ sub _setup_and_start_X {
     return undef;
 }
 
+=item _launchX($o, $f, $server, $Driver, $wanted_DISPLAY)
+
+Actually starts the selected X.org server using /tmp/Xconf configuration file & logging into /var/log/Xorg.0.log.
+
+=cut
+
 sub _launchX {
     my ($o, $f, $server, $Driver, $wanted_DISPLAY) = @_;
 
@@ -208,6 +251,20 @@ sub interactive_help_get_id {
 #-######################################################################################
 #- Steps Functions
 #-######################################################################################
+
+=back
+
+=head1 Steps Functions
+
+=over
+
+=item selectLanguage($o)
+
+Offer to select language and country.
+This graphical version also warn if RAM is insufficient.
+
+=cut
+
 sub selectLanguage {
     my ($o) = @_;
     $o->SUPER::selectLanguage;
@@ -240,6 +297,12 @@ sub selectMouse {
     } 
 }
 
+=item setPackages($o)
+
+Same as install::any::setPackages($o) but updating the step items.
+
+=cut
+
 sub setPackages {
     my ($o) = @_;
     my (undef, $old_title) = get_default_step_items();
@@ -248,6 +311,13 @@ sub setPackages {
     set_default_step_items($old_title);
 }
 
+
+=item reallyChooseDesktop($o, $title, $message, $choices, $choice)
+
+Dedicated dialog in order to choose the desktop (Plasma, GNOME or custom)
+
+=cut
+
 sub reallyChooseDesktop {
     my ($o, $title, $message, $choices, $choice) = @_;
 
@@ -325,6 +395,12 @@ sub reallyChooseDesktop {
     $choice;
 }
 
+=item reallyChooseGroups($o, $size_to_display, $individual, $_compssUsers)
+
+Dedicated dialog in order to choose the package groups to install or individual package selection.
+
+=cut
+
 sub reallyChooseGroups {
     my ($o, $size_to_display, $individual, $_compssUsers) = @_;
 
@@ -688,6 +764,14 @@ sub installPackages {
     $install_result;
 }
 
+
+=item summary_prompt($o, $l, $check_complete)
+
+Display the summary once the package installation is complete.
+This is the graphical version which overloads the function in L<steps_interactive>.
+
+=cut
+
 sub summary_prompt {
     my ($o, $l, $check_complete) = @_;
 
@@ -805,5 +889,8 @@ It will then continue from the hard disk drive and the packages will remain avai
     log::l("keeping media " . join ',', map { $_->{rpmsdir} } grep { !$_->{ignore} } @$hdlists);
 }
 
+=back
+
+=cut
 
 1;
diff --git a/perl-install/install/steps_interactive.pm b/perl-install/install/steps_interactive.pm
index aaacd7fba..3a2586cae 100644
--- a/perl-install/install/steps_interactive.pm
+++ b/perl-install/install/steps_interactive.pm
@@ -31,6 +31,16 @@ use keyboard;
 use any;
 use log;
 
+=head1 SYNOPSYS
+
+Handle the interactive installer steps (text & graphical).
+
+=head1 Functions
+
+=over
+
+=cut
+
 #-######################################################################################
 #- In/Out Steps Functions
 #-######################################################################################
@@ -845,6 +855,16 @@ sub summaryBefore {
     log::l("summaryBefore: network configuration: ", formatError($@)) if $@;
 }
 
+
+
+=item summary_prompt($o, $l, $check_complete)
+
+Display the summary once the package installation is complete.
+This is the text version which is overloaded in L<steps_gtk>.
+
+=cut
+
+
 sub summary_prompt {
     my ($o, $l, $check_complete) = @_;
 
@@ -861,6 +881,13 @@ sub summary_prompt {
 		  }, $l);
 }
 
+
+=item summary($o)
+
+Create the list of categories for the summary that will be displayed by summary_prompt()
+
+=cut
+
 sub summary {
     my ($o) = @_;