convert comments to POD

2 files changed, 335 insertions, 120 deletions

diff --git a/perl-install/interactive.pm b/perl-install/interactive.pm
index 34ae7a4de..b24c67e7f 100644
--- a/perl-install/interactive.pm
+++ b/perl-install/interactive.pm
@@ -9,83 +9,68 @@ use strict;
 use common;
 use do_pkgs;
 
-#- minimal example using interactive:
-#
-#- > use lib qw(/usr/lib/libDrakX);
-#- > use interactive;
-#- > my $in = interactive->vnew;
-#- > $in->ask_okcancel('title', 'question');
-#- > $in->exit;
-
-#- ask_from_ takes global options ($common):
-#-  title                => window title
-#-  messages             => message displayed in the upper part of the window
-#-  ok                   => force the name of the "Ok"/"Next" button
-#-  cancel               => force the name of the "Cancel"/"Previous" button
-#-  focus_cancel         => force focus on the "Cancel" button
-#-  focus_first          => (deprecated) force focus on the first entry
-#-  ok_disabled          => function returning wether {ok} should be disabled (grayed)
-#-  validate             => function called when {ok} is pressed. If it returns false, the first entry is focused, otherwise it quits
-#-  advanced             => (deprecated) function called when the "advanced" expander is toggled
-#-  advanced_messages    => (deprecated) message displayed when "Advanced" is pressed
-#-  advanced_label       => (deprecated) force the name of the "Advanced" button
-#-  advanced_label_close => (deprecated) force the name of the "Basic" button
-#-  advanced_state       => (deprecated) if set to 1, force the "Advanced" part of the dialog to be opened initially
-#-  advanced_title       => (deprecated) title of the advanced item popup dialog (else reusing main title)
-#-  callbacks            => (deprecated) functions called when something happen: complete advanced ok_disabled
-
-#- ask_from_ takes a list of entries with fields:
-#-  val      => reference to the value
-#-  label    => description
-#-  title    => a boolean: whether the label should be displayed as a title (see GNOME's HIG)
-#-  icon     => icon to put before the description
-#-  help     => tooltip
-#-  advanced => (deprecated) wether it is shown in by default or only in advanced mode
-#-  focus_out => function called when the entry is focused out
-#-  changed  => function called when the entry is modified
-#-  validate => function called when "Ok" is pressed. If it returns false, this entry is focused, otherwise it quits
-#-  disabled => function returning wether it should be disabled (grayed)
-#-  focus    => function returning wether it should be focused
-#-  alignment => preferred alignment
-#-  do_not_expand => do not eat all horizontal space
-#-  install_button => if possible, use improved graphical style
-#-  gtk      => gtk preferences
-#-  type     => 
-#-     button => (with clicked or clicked_may_quit)
-#-               (type defaults to button if clicked or clicked_may_quit is there)
-#-               (val need not be a reference) (if clicked_may_quit return true, it's as if "Ok" was pressed)
-#-     label => (val need not be a reference) (type defaults to label if val is not a reference) 
-#-     bool (with "text" or "image" (which overrides text) giving an image filename)
-#-     range (with min, max, SpinButton)
-#-     combo (with list, not_edit, format)
-#-     list (with list, icon2f (aka icon), separator (aka tree), format (aka pre_format function),
-#-           help can be a hash or a function,
-#-           tree_expanded boolean telling wether the tree should be wide open by default
-#-           quit_if_double_click boolean
-#-           allow_empty_list disables the special cases for 0 and 1 element lists
-#-           image2f is a subroutine which takes a value of the list as parameter, and returns image_file_name
-#-     entry (the default) (with hidden)
-#-     expander (with text, expanded, message, children(a list of sub entries))
-#
-#- heritate from this class and you'll get all made interactivity for same steps.
-#- for this you need to provide
-#- - ask_from_listW(o, title, messages, arrayref, default) returns one string of arrayref
-#-
-#- where
-#- - o is the object
-#- - title is a string
-#- - messages is an refarray of strings
-#- - default is an optional string (default is in arrayref)
-#- - arrayref is an arrayref of strings
-#- - arrayref2 contains booleans telling the default state,
-#-
-#- ask_from_list and ask_from_list_ are wrappers around ask_from_biglist and ask_from_smalllist
-#-
-#- ask_from_list_ just translate arrayref before calling ask_from_list and untranslate the result
-#-
-#- ask_from_listW should handle differently small lists and big ones.
-#-
+=head1 NAME
 
+interactive - a GUI layer with multiple backend (text console, Gtk+ GUI, web)
+
+=head1 SYNOPSYS
+
+B<interactive> enables to write GUIes that will work everywhere:
+
+=over 4
+
+=item * text console
+
+implemented by L<interactive::stdio> & L<interactive::curses>
+
+=item * web browser
+
+implemented by L<interactive::http>
+
+=item * GUI
+
+implemented by L<interactive::gtk>
+
+=back
+
+=head1 Minimal example using interactive
+
+ use lib qw(/usr/lib/libDrakX);
+ use interactive;
+ my $in = interactive->vnew;
+ $in->ask_okcancel('title', 'question');
+ $in->exit;
+
+=head1 Backends
+
+heritate from this class and you'll get all made interactivity for same steps.
+for this you need to provide
+
+C<ask_from_listW(o, title, messages, arrayref, default)> which returns one string of arrayref
+
+where:
+
+=over 4
+
+=item * B<o> is the object
+
+=item * B<title> is a string
+
+=item * B<messages> is an refarray of strings
+
+=item * B<default> is an optional string (default is in arrayref)
+
+=item * B<arrayref> is an arrayref of strings
+
+=item * B<arrayref>2 contains booleans telling the default state,
+
+=back
+
+=head1 Functions
+
+=over
+
+=cut
 
 #-######################################################################################
 #- OO Stuff
@@ -263,6 +248,18 @@ sub ask_fileW {
     $o->ask_from_entry($common->{title}, $common->{message} || N("Choose a file"));
 }
 
+=item ask_from_list($o, $title, $message, $l, $o_def)
+
+=item ask_from_list_($o, $title, $message, $l, $o_def)
+
+ask_from_list() and ask_from_list_() are wrappers around ask_from_biglist and ask_from_smalllist
+
+ask_from_list_() just translate arrayref before calling ask_from_list and untranslate the result
+
+ask_from_listW() should handle differently small lists and big ones.
+
+=cut
+
 sub ask_from_list {
     my ($o, $title, $message, $l, $o_def) = @_;
     ask_from_listf($o, $title, $message, undef, $l, $o_def);
@@ -514,6 +511,128 @@ sub migrate_advanced {
 		    }) ];
 }
 
+
+=item ask_from_($o, $common, $l)
+
+ask_from_() takes global options ($common):
+
+=over 4
+
+=item * B<title>: window title
+
+=item * B<messages>: message displayed in the upper part of the window
+
+=item * B<ok>: force the name of the "Ok"/"Next" button
+
+=item * B<cancel>: force the name of the "Cancel"/"Previous" button
+
+=item * B<focus_cancel>: force focus on the "Cancel" button
+
+=item * I<focus_first>: (deprecated) force focus on the first entry
+
+=item * B<ok_disabled>: function returning wether {ok} should be disabled (grayed)
+
+=item * B<validate>: function called when {ok} is pressed. If it returns false, the first entry is focused, otherwise it quits
+
+=item * I<advanced>: (deprecated) function called when the "advanced" expander is toggled
+
+=item * I<advanced_messages>: (deprecated) message displayed when "Advanced" is pressed
+
+=item * I<advanced_label>: (deprecated) force the name of the "Advanced" button
+
+=item * I<advanced_label_close>: (deprecated) force the name of the "Basic" button
+
+=item * I<advanced_state>: (deprecated) if set to 1, force the "Advanced" part of the dialog to be opened initially
+
+=item * I<advanced_title>: (deprecated) title of the advanced item popup dialog (else reusing main title)
+
+=item * I<callbacks>: (deprecated) functions called when something happen: complete advanced ok_disabled
+
+=back
+
+ask_from_ takes a list of entries with fields:
+
+=over 4
+
+=item * B<val>: reference to the value
+
+=item * B<label>: description
+
+=item * B<title>: a boolean: whether the label should be displayed as a title (see GNOME's HIG)
+
+=item * B<icon>: icon to put before the description
+
+=item * B<help>: tooltip
+
+=item * I<advanced>: (deprecated) wether it is shown in by default or only in advanced mode
+
+=item * B<focus_out>: function called when the entry is focused out
+
+=item * B<changed>: function called when the entry is modified
+
+=item * B<validate>: function called when "Ok" is pressed. If it returns false, this entry is focused, otherwise it quits
+
+=item * B<disabled>: function returning wether it should be disabled (grayed)
+
+=item * B<focus>: function returning wether it should be focused
+
+=item * B<alignment>: preferred alignment
+
+=item * B<do_not_expand>: do not eat all horizontal space
+
+=item * B<install_button>: if possible, use improved graphical style
+
+=item * B<gtk>: gtk preferences
+
+=item * B<type>:
+
+=over 4
+
+=item * B<button>: (with clicked or clicked_may_quit)
+
+I<type> defaults to button if clicked or clicked_may_quit is there.
+I<val> need not be a reference.
+If I<clicked_may_quit> return true, it's as if "Ok" was pressed.
+
+=item * B<label>:
+I<val> need not be a reference.
+I<type> defaults to label if val is not a reference.
+
+=item * B<bool>: (with "text" or "image" (which overrides text) giving an image filename)
+
+=item * B<range>: (with min, max, SpinButton)
+
+=item * B<combo>: (with list, not_edit, format)
+
+=item * B<list>: (with list, icon2f (aka icon), separator (aka tree), format (aka pre_format function),
+
+It has these optional parameters:
+
+=over 4
+
+=item * B<help>: can be a hash or a function,
+
+=item * B<tree_expanded>: boolean telling wether the tree should be wide open by default
+
+=item * B<quit_if_double_click>: boolean
+
+=item * B<allow_empty_list>: disables the special cases for 0 and 1 element lists
+
+=item * B<image2f>: a subroutine which takes a value of the list as parameter, and returns image_file_name
+
+=back
+
+=item * B<entry>: (the default) (with hidden)
+
+=item * B<expander>: (with text, expanded, message, children(a list of sub entries))
+
+=back
+
+=back
+
+=cut
+
+
 sub ask_from_ {
     my ($o, $common, $l) = @_;
     ask_from_normalize($o, $common, $l);
@@ -654,4 +773,8 @@ sub interactive_help_sub_display_id {
       && sub { $o->ask_warn(N("Help"), $o->interactive_help_get_id($id)) };
 }
 
+=back
+
+=cut
+
 1;
diff --git a/perl-install/ugtk3.pm b/perl-install/ugtk3.pm
index d2bcc18ed..b16e0a46b 100644
--- a/perl-install/ugtk3.pm
+++ b/perl-install/ugtk3.pm
@@ -40,18 +40,27 @@ use mygtk3 qw(gtknew); #- do not import gtkadd which conflicts with ugtk3 versio
 
 use Gtk3;
 
+=head1 SYNOPSYS
+
+B<ugtk3> enables to write GUIes using Gtk+3. It adds nice wrappers on top of
+L<Gtk3>, notably gtkpowerpack() and its children gtkpack*()
+
+=cut
 
 $border = 5;
 
 sub wm_icon() { $wm_icon || $::Wizard_pix_up || "wiz_default_up.png" }
 
-# -=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---
-#                 wrappers
-#
-# Functional-style wrappers to existing Gtk functions; allows to program in
-# a more functional way, and especially, first, to avoid using temp
-# variables, and second, to "see" directly in the code the user interface
-# you're building.
+=head1 Wrappers
+
+Functional-style wrappers to existing Gtk functions; allows to program in
+a more functional way, and especially, first, to avoid using temp
+variables, and second, to "see" directly in the code the user interface
+you're building.
+
+=over
+
+=cut
 
 sub gtkdestroy                { mygtk3::may_destroy($_[0]) }
 sub gtkflush()                { mygtk3::flush() }
@@ -122,7 +131,12 @@ sub gtkappenditems {
     $w;
 }
 
-# append page to a notebook
+=item gtkappend_page($notebook, $page, $o_title)
+
+append page to a notebook
+
+=cut
+
 sub gtkappend_page {
     my ($notebook, $page, $o_title) = @_;
     $notebook->append_page($page, $o_title);
@@ -249,13 +263,16 @@ sub gtktreeview_children {
     @l;
 }
 
+=back
 
+=head1 Create functions
 
-# -=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---
-#                 create
-#
-# Helpers that allow omitting common operations on common widgets
-# (e.g. create widgets with good default properties)
+Helpers that allow omitting common operations on common widgets
+(e.g. create widgets with good default properties)
+
+=over
+
+=cut
 
 sub create_pixbutton {
     my ($label, $pix, $reverse_order) = @_;
@@ -286,11 +303,15 @@ sub n_line_size {
     round($nbline * ($fontinfo{ascent} + $fontinfo{descent} + $spacing) + 8);
 }
 
-# Glib::Markup::escape_text() if no use for us because it'll do extra
-# s/X/&foobar;/ (such as s/'/&apos;/) that are suitable for
-# Gtk3::Labels but are not for Gtk3::TextViews, resulting in
-# displaying the raw enriched text instead...
-#
+=item escape_text_for_TextView_markup_format($str)
+
+Glib::Markup::escape_text() if no use for us because it'll do extra
+s/X/&foobar;/ (such as s/'/&apos;/) that are suitable for
+Gtk3::Labels but are not for Gtk3::TextViews, resulting in
+displaying the raw enriched text instead...
+
+=cut
+
 sub escape_text_for_TextView_markup_format {
     my ($str) = @_;
     my %rules = ('&' => '&amp;',
@@ -582,12 +603,16 @@ sub gtkcreate_frame {
     gtknew('Frame', text => $label, border_width => 5);
 }
 
+=back
+
+=head1 Helpers
+
+Functions that do typical operations on widgets, that you may need in
+several places of your programs.
 
-# -=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---
-#                 helpers
-#
-# Functions that do typical operations on widgets, that you may need in
-# several places of your programs.
+=over
+
+=cut
 
 sub _find_imgfile {
     my ($name) = @_;
@@ -604,13 +629,23 @@ sub _find_imgfile {
     }
 }
 
-# use it if you want to display an icon/image in your app
+=item gtkcreate_img($file, $o_size)
+
+use it if you want to display an icon/image in your app
+
+=cut
+
 sub gtkcreate_img {
     my ($file, $o_size) = @_;
     gtknew('Image', file => $file, if_($o_size, size => $o_size));
 }
 
-# use it if you want to draw an image onto a drawingarea
+=item gtkcreate_pixbuf($file, $o_size)
+
+use it if you want to draw an image onto a drawingarea
+
+=cut
+
 sub gtkcreate_pixbuf {
     my ($file, $o_size) = @_;
     gtknew('Pixbuf', file => $file, if_($o_size, size => $o_size));
@@ -634,7 +669,12 @@ sub set_main_window_size {
     mygtk3::set_main_window_size($o->{rwindow});
 }
 
-# extracts interesting font metrics for a given widget
+=item gtkfontinfo($widget)
+
+extracts interesting font metrics for a given widget
+
+=cut
+
 sub gtkfontinfo {
     my ($widget) = @_;
     my $context = $widget->get_pango_context;
@@ -699,14 +739,21 @@ sub set_default_step_items {
 
 sub get_default_step_items { ($def_step_title) }
 
-# -=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---
-#                 toplevel window creation helper
-#
-# Use the 'new' function as a method constructor and then 'main' on it to
-# launch the main loop. Use $o->{retval} to indicate that the window needs
-# to terminate.
-# Set $::isWizard to have a wizard appearance.
-# Set $::isEmbedded and $::XID so that the window will plug.
+=back
+
+=head1 Toplevel window creation helper
+
+=over
+
+=item new($type, $title, %opts)
+
+Use the 'new' function as a method constructor and then 'main' on it to
+launch the main loop. Use $o->{retval} to indicate that the window needs
+to terminate.
+Set $::isWizard to have a wizard appearance.
+Set $::isEmbedded and $::XID so that the window will plug.
+
+=cut
 
 sub new {
     my ($type, $title, %opts) = @_;
@@ -782,11 +829,16 @@ sub exit {
 #- in case "exit" above was not called by the program
 END { &exit() }
 
-# -=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---=-=---
-#                 ask
-#
-# Full UI managed functions that will return to you the value that the
-# user chose.
+=back
+
+=head1 Ask functions
+
+Full UI managed functions that will return to you the value that the
+user chose.
+
+=over
+
+=cut
 
 sub ask_warn       { my $w = ugtk3->new(shift @_, grab => 1); $w->_ask_warn(@_); main($w) }
 sub ask_yesorno    { my $w = ugtk3->new(shift @_, grab => 1); $w->_ask_okcancel(@_, N("Yes"), N("No")); main($w) }
@@ -1217,7 +1269,13 @@ sub gtk_new_TextView_get_log {
     $log_scroll, $pid;
 }
 
-# misc helpers:
+=back
+
+=head1 Misc helpers & widgets
+
+=over
+
+=cut
 
 package Gtk3::TreeStore;
 sub append_set {
@@ -1231,7 +1289,13 @@ sub append_set {
 
 
 package Gtk3::ListStore;
-# Append a new row, set the values, return the TreeIter
+
+=item Gtk3::ListStore::append_set($model, @values)
+
+Append a new row, set the values, return the TreeIter
+
+=cut
+
 sub append_set {
     my ($model, @values) = @_;
     # compatibility:
@@ -1243,7 +1307,13 @@ sub append_set {
 
 
 package Gtk3::TreeModel;
-# gets the string representation of a TreeIter
+
+=item Gtk3::TreeModel::get_path_str($self, $iter)
+
+gets the string representation of a TreeIter
+
+=cut
+
 sub get_path_str {
     my ($self, $iter) = @_;
     my $path = $self->get_path($iter);
@@ -1260,7 +1330,13 @@ sub iter_each_children {
 }
 
 package Gtk3::TreeView;
-# likewise gtk-1.2 function
+
+=item Gtk3::TreeView;::toggle_expansion($self, $path, $b_open_all)
+
+gtk-1.2 compatibility function
+
+=cut
+
 sub toggle_expansion {
     my ($self, $path, $b_open_all) = @_;
     if ($self->row_expanded($path)) {
@@ -1273,7 +1349,12 @@ sub toggle_expansion {
 package Gtk3::ComboBox;
 use MDK::Common;
 
-# try to get combox <==> option menu mapping
+=item Gtk3::ComboBox::set_popdown_strings($w, @strs)
+
+try to get combox <==> option menu mapping
+
+=cut
+
 sub set_popdown_strings {
     my ($w, @strs) = @_;
     my $model = $w->get_model;
@@ -1345,6 +1426,13 @@ sub new_with_text {
 
 package Gtk3::Banner;
 
+=item Gtk3::Banner widget
+
+Used in tools & installer banner bars
+
+=cut
+
+
 use MDK::Common;
 use mygtk3 qw(gtknew);
 use ugtk3 qw(:helpers :wrappers);
@@ -1481,4 +1569,8 @@ sub new {
     };
 }
 
+=back
+
+=cut
+
 1;