Added auto-documentation of example programs.

Added a new gen_examples_pod.pl program to autogenerate the
Spreadsheet::WriteExcel::Examples.pm file with embedded examples
generated from the README in the examples dir.

Modified several of the example program for consistent comment
format.

Makefile.PL

@@ -19,3 +19,8 @@ WriteMakefile(
     'EXE_FILES'     => ['bin/chartex'],
     'LICENSE'       => 'perl',
 );
+
+sub MY::postamble {
+    "mydocs:\n" .
+    "\tperl examples/gen_examples_pod.pl examples\n";
+}

examples/README

@@ -1,98 +1,102 @@
-The following is a description of the example files that are provided
-with Spreadsheet::WriteExcel. They are intended to demonstrate the
-different features and options of the module.
-
-
-Getting started
-===============
-bug_report.pl           A template for submitting bug reports.
-demo.pl                 Creates a demo of some of the features.
-formats.pl              Creates a demo of the available formatting.
-regions.pl              Demonstrates multiple worksheets.
-simple.pl               An example of some of the basic features.
-stats.pl                Basic formulas and functions.
-
-Advanced
-========
-autofilter.pl           Examples of worksheet autofilters.
-autofit.pl              Simulate Excel's autofit for column widths.
-bigfile.pl              Write past the 7MB limit with OLE::Storage_Lite.
-cgi.pl                  A simple CGI program.
-chess.pl                An example of formatting using properties.
-colors.pl               Demo of the colour palette and named colours.
-comments1.pl            Add comments to worksheet cells.
-comments2.pl            Add comments with advanced options.
-copyformat.pl           Example of copying a cell format.
-data_validate.pl        An example of data validation and dropdown lists.
-defined_name.pl         Example of how to create defined names.
-diag_border.pl          A simple example of diagonal cell borders.
-easter_egg.pl           Expose the Excel97 flight simulator. A must see.
-filehandle.pl           Examples of working with filehandles.
-formula_result.pl       Formulas with user specified results.
-headers.pl              Examples of worksheet headers and footers.
-hide_sheet.pl           Simple example of hiding a worksheet.
-hyperlink1.pl           Shows how to create web hyperlinks.
-hyperlink2.pl           Examples of internal and external hyperlinks.
-images.pl               Adding bitmap images to worksheets.
-indent.pl               An example of cell indentation.
-merge1.pl               A simple example of cell merging.
-merge2.pl               A simple example of cell merging with formatting.
-merge3.pl               Add hyperlinks to merged cells.
-merge4.pl               An advanced example of merging with formatting.
-merge5.pl               An advanced example of merging with formatting.
-merge6.pl               An example of merging with Unicode strings.
-mod_perl1.pl            A simple mod_perl 1 program.
-mod_perl2.pl            A simple mod_perl 2 program.
-outline.pl              An example of outlines and grouping.
-panes.pl                An examples of how to create panes.
-properties.pl           Add document properties to a workbook.
-protection.pl           Example of cell locking and formula hiding.
-repeat.pl               Example of writing repeated formulas.
-right_to_left.pl        Change default sheet direction to right to left.
-row_wrap.pl             How to wrap data from one worksheet onto another.
-sales.pl                An example of a simple sales spreadsheet.
-sendmail.pl             Send an Excel email attachment using Mail::Sender.
-stats_ext.pl            Same as stats.pl with external references.
-stocks.pl               Demonstrates conditional formatting.
-tab_colors.pl           Example of how to set worksheet tab colours.
-textwrap.pl             Demonstrates text wrapping options.
-win32ole.pl             A sample Win32::OLE example for comparison.
-write_arrays.pl         Example of writing 1D or 2D arrays of data.
-write_handler1.pl       Example of extending the write() method. Step 1.
-write_handler2.pl       Example of extending the write() method. Step 2.
-write_handler3.pl       Example of extending the write() method. Step 3.
-write_handler4.pl       Example of extending the write() method. Step 4.
-write_to_scalar.pl      Example of writing an Excel file to a Perl scalar.
-
-
-Unicode
-=======
-unicode_utf16.pl        Simple example of using Unicode UTF16 strings.
-unicode_utf16_japan.pl  Write Japanese Unicode strings using UTF-16.
-unicode_cyrillic.pl     Write Russian Cyrillic strings using UTF-8.
-unicode_list.pl         List the chars in a Unicode font.
-unicode_2022_jp.pl      Japanese: ISO-2022-JP to utf8 in perl 5.8.
-unicode_8859_11.pl      Thai:     ISO-8859_11 to utf8 in perl 5.8.
-unicode_8859_7.pl       Greek:    ISO-8859_7  to utf8 in perl 5.8.
-unicode_big5.pl         Chinese:  BIG5        to utf8 in perl 5.8.
-unicode_cp1251.pl       Russian:  CP1251      to utf8 in perl 5.8.
-unicode_cp1256.pl       Arabic:   CP1256      to utf8 in perl 5.8.
-unicode_koi8r.pl        Russian:  KOI8-R      to utf8 in perl 5.8.
-unicode_polish_utf8.pl  Polish :  UTF8        to utf8 in perl 5.8.
-unicode_shift_jis.pl    Japanese: Shift JIS   to utf8 in perl 5.8.
-
-
-Utility
-=======
-csv2xls.pl              Program to convert a CSV file to an Excel file.
-datecalc1.pl            Convert Unix/Perl time to Excel time.
-datecalc2.pl            Calculate an Excel date using Date::Calc.
-lecxe.pl                Convert Excel to WriteExcel using Win32::OLE.
-tab2xls.pl              Program to convert a tab separated file to xls.
-
-
-Developer
-=========
-convertA1.pl            Helper functions for dealing with A1 notation.
-function_locale.pl      Add non-English function names to Formula.pm.
-writeA1.pl              Example of how to extend the module.
+The following is a description of the example files that are provided
+with Spreadsheet::WriteExcel. They are intended to demonstrate the
+different features and options of the module.
+
+
+Getting started
+===============
+a_simple.pl             A get started example with some basic features.
+demo.pl                 A demo of some of the available features.
+regions.pl              A simple example of multiple worksheets.
+stats.pl                Basic formulas and functions.
+formats.pl              All the available formatting on several worksheets.
+bug_report.pl           A template for submitting bug reports.
+
+
+Advanced
+========
+autofilter.pl           Examples of worksheet autofilters.
+autofit.pl              Simulate Excel's autofit for column widths.
+bigfile.pl              Write past the 7MB limit with OLE::Storage_Lite.
+cgi.pl                  A simple CGI program.
+chess.pl                An example of reusing formatting via properties.
+colors.pl               A demo of the colour palette and named colours.
+comments1.pl            Add comments to worksheet cells.
+comments2.pl            Add comments with advanced options.
+copyformat.pl           Example of copying a cell format.
+data_validate.pl        An example of data validation and dropdown lists.
+date_time.pl            Write dates and times with write_date_time().
+defined_name.pl         Example of how to create defined names.
+diag_border.pl          A simple example of diagonal cell borders.
+easter_egg.pl           Expose the Excel97 flight simulator.
+filehandle.pl           Examples of working with filehandles.
+formula_result.pl       Formulas with user specified results.
+headers.pl              Examples of worksheet headers and footers.
+hide_sheet.pl           Simple example of hiding a worksheet.
+hyperlink1.pl           Shows how to create web hyperlinks.
+hyperlink2.pl           Examples of internal and external hyperlinks.
+images.pl               Adding images to worksheets.
+indent.pl               An example of cell indentation.
+merge1.pl               A simple example of cell merging.
+merge2.pl               A simple example of cell merging with formatting.
+merge3.pl               Add hyperlinks to merged cells.
+merge4.pl               An advanced example of merging with formatting.
+merge5.pl               An advanced example of merging with formatting.
+merge6.pl               An example of merging with Unicode strings.
+mod_perl1.pl            A simple mod_perl 1 program.
+mod_perl2.pl            A simple mod_perl 2 program.
+outline.pl              An example of outlines and grouping.
+outline_collapsed.pl    An example of collapsed outlines.
+panes.pl                An examples of how to create panes.
+properties.pl           Add document properties to a workbook.
+protection.pl           Example of cell locking and formula hiding.
+repeat.pl               Example of writing repeated formulas.
+right_to_left.pl        Change default sheet direction to right to left.
+row_wrap.pl             How to wrap data from one worksheet onto another.
+sales.pl                An example of a simple sales spreadsheet.
+sendmail.pl             Send an Excel email attachment using Mail::Sender.
+stats_ext.pl            Same as stats.pl with external references.
+stocks.pl               Demonstrates conditional formatting.
+tab_colors.pl           Example of how to set worksheet tab colours.
+textwrap.pl             Demonstrates text wrapping options.
+win32ole.pl             A sample Win32::OLE example for comparison.
+write_arrays.pl         Example of writing 1D or 2D arrays of data.
+write_handler1.pl       Example of extending the write() method. Step 1.
+write_handler2.pl       Example of extending the write() method. Step 2.
+write_handler3.pl       Example of extending the write() method. Step 3.
+write_handler4.pl       Example of extending the write() method. Step 4.
+write_to_scalar.pl      Example of writing an Excel file to a Perl scalar.
+
+
+Unicode
+=======
+unicode_utf16.pl        Simple example of using Unicode UTF16 strings.
+unicode_utf16_japan.pl  Write Japanese Unicode strings using UTF-16.
+unicode_cyrillic.pl     Write Russian Cyrillic strings using UTF-8.
+unicode_list.pl         List the chars in a Unicode font.
+unicode_2022_jp.pl      Japanese: ISO-2022-JP to utf8 in perl 5.8.
+unicode_8859_11.pl      Thai:     ISO-8859_11 to utf8 in perl 5.8.
+unicode_8859_7.pl       Greek:    ISO-8859_7  to utf8 in perl 5.8.
+unicode_big5.pl         Chinese:  BIG5        to utf8 in perl 5.8.
+unicode_cp1251.pl       Russian:  CP1251      to utf8 in perl 5.8.
+unicode_cp1256.pl       Arabic:   CP1256      to utf8 in perl 5.8.
+unicode_koi8r.pl        Russian:  KOI8-R      to utf8 in perl 5.8.
+unicode_polish_utf8.pl  Polish :  UTF8        to utf8 in perl 5.8.
+unicode_shift_jis.pl    Japanese: Shift JIS   to utf8 in perl 5.8.
+
+
+Utility
+=======
+csv2xls.pl              Program to convert a CSV file to an Excel file.
+tab2xls.pl              Program to convert a tab separated file to xls.
+datecalc1.pl            Convert Unix/Perl time to Excel time.
+datecalc2.pl            Calculate an Excel date using Date::Calc.
+lecxe.pl                Convert Excel to WriteExcel using Win32::OLE.
+
+
+Developer
+=========
+convertA1.pl            Helper functions for dealing with A1 notation.
+function_locale.pl      Add non-English function names to Formula.pm.
+writeA1.pl              Example of how to extend the module.
+gen_examples_pod.pl     Generate the S::WE::Examples.pm doc.

examples/a_simple.pl

@@ -1,9 +1,9 @@
 #!/usr/bin/perl -w
 
-#######################################################################
+###############################################################################
 #
-# Example of how to use the WriteExcel module to write text and numbers
-# to an Excel binary file.
+# A simple example of how to use the Spreadsheet::WriteExcel module to write
+# some  text and numbers to an Excel binary file.
 #
 # reverse('©'), March 2001, John McNamara, jmcnamara@cpan.org
 #
@@ -36,4 +36,6 @@
 
 
 # Write a hyperlink
-$worksheet->write(10, 0, 'http://www.perl.com/');
+$worksheet->write(10, 0, 'http://www.perl.com/');
+
+__END__

examples/autofilter.pl

@@ -1,8 +1,12 @@
 #!/usr/bin/perl -w
 
-#######################################################################
+###############################################################################
+#
+# An example of how to create autofilters with Spreadsheet::WriteExcel.
 #
-# Example of how to create autofilters with Spreadsheet::WriteExcel.
+# An autofilter is a way of adding drop down lists to the headers of a 2D range
+# of worksheet data. This is turn allow users to filter the data based on
+# simple criteria so that some data is shown and some is hidden.
 #
 # reverse('©'), September 2007, John McNamara, jmcnamara@cpan.org
 #

examples/autofit.pl

@@ -2,8 +2,7 @@
 
 ##############################################################################
 #
-# Simuluate Excel's autofit for colums widths.
-#
+# Simulate Excel's autofit for column widths.
 #
 # Excel provides a function called Autofit (Format->Columns->Autofit) that
 # adjusts column widths to match the length of the longest string in a column.
@@ -20,8 +19,8 @@
 #
 # The main problem with trying to simulate Autofit lies in defining a
 # relationship between a string length and its width in a arbitrary font and
-# size. We use two aproaches below. The first is a simple direct relationship
-# obtrained by trial and error. The second is a slightly more sophisticated
+# size. We use two approaches below. The first is a simple direct relationship
+# obtained by trial and error. The second is a slightly more sophisticated
 # method using an external module. For more complicated applications you will
 # probably have to work out your own methods.
 #
@@ -56,11 +55,11 @@
 
 
 
-###############################################################################
 ###############################################################################
 #
 # Functions used for Autofit.
 #
+###############################################################################
 
 ###############################################################################
 #
@@ -148,8 +147,8 @@ sub string_width {
 # "require"-ing it and you could make the Font object global to avoid repeated
 # initialisation.
 #
-# Note also that the $pixel_width to $cell_width is specific to arial. For
-# other fonts you should calculate appropriate relationships. A future verison
+# Note also that the $pixel_width to $cell_width is specific to Arial. For
+# other fonts you should calculate appropriate relationships. A future version
 # of S::WE will provide a way of specifying column widths in pixels instead of
 # cell units in order to simplify this conversion.
 #

examples/bigfile.pl

@@ -26,3 +26,4 @@
     }
 }
 
+__END__

examples/cgi.pl

@@ -6,7 +6,12 @@
 # file to a browser in a CGI program.
 #
 # On Windows the hash-bang line should be something like:
-# #!C:\Perl\bin\perl.exe
+#
+#     #!C:\Perl\bin\perl.exe
+#
+# The "Content-Disposition" line will cause a prompt to be generated to save
+# the file. If you want to stream the file to the browser instead, comment out
+# that line as shown below.
 #
 # reverse('©'), March 2001, John McNamara, jmcnamara@cpan.org
 #
@@ -20,7 +25,7 @@
 print "Content-type: application/vnd.ms-excel\n";
 # The Content-Disposition will generate a prompt to save the file. If you want
 # to stream the file to the browser, comment out the following line.
-print "Content-Disposition: attachment; filename=$filename\n";
+Print "Content-Disposition: attachment; filename=$filename\n";
 print "\n";
 
 # Create a new workbook and add a worksheet. The special Perl filehandle - will
@@ -43,3 +48,5 @@
 
 # Write to the workbook
 $worksheet->write(0, 0, "Hi Excel!", $format);
+
+__END__

examples/chess.pl

@@ -8,14 +8,16 @@
 # Setting format properties via hashes of values is useful when you have
 # to deal with a large number of similar formats. Consider for example a
 # chess board pattern with black squares, white unformatted squares and
-# a border. This relatively simple example requires 14 separate Format
+# a border.
+#
+# This relatively simple example requires 14 separate Format
 # objects although there are only 5 different properties: black
 # background, top border, bottom border, left border and right border.
+#
 # Using property hashes it is possible to define these 5 sets of
 # properties and then add them together to create the 14 Format
 # configurations.
 #
-#
 # reverse('©'), July 2001, John McNamara, jmcnamara@cpan.org
 #
 

examples/colors.pl

@@ -1,9 +1,12 @@
 #!/usr/bin/perl -w
 
-######################################################################
+################################################################################
+#
+# Demonstrates Spreadsheet::WriteExcel's named colors and the Excel color
+# palette.
 #
-# Demonstrates Spreadsheet::WriteExcel's named colors and the Excel
-# color palette.
+# The set_custom_color() Worksheet method can be used to override one of the
+# built-in palette values with a more suitable colour. See the main docs.
 #
 # reverse('©'), March 2002, John McNamara, jmcnamara@cpan.org
 #
@@ -100,3 +103,5 @@
     }
 }
 
+__END__
+

examples/comments1.pl

@@ -2,8 +2,10 @@
 
 ###############################################################################
 #
-# This example demonstrates writing cell comments. A cell comment is indicated
-# in Excel by a small red triangle in the upper right-hand corner of the cell.
+# This example demonstrates writing cell comments.
+#
+# A cell comment is indicated in Excel by a small red triangle in the upper
+# right-hand corner of the cell.
 #
 # For more advanced comment options see comments2.pl.
 #
@@ -20,3 +22,5 @@
 
 $worksheet->write        ('A1', 'Hello'            );
 $worksheet->write_comment('A1', 'This is a comment');
+
+__END__