PODify the installer

1 files changed, 218 insertions, 1 deletions

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;