DOCUMENTATION for XLWrite Version 0.02


XLWrite: A utility for writing CSV files into an XLS spreadsheet.
Version 0.02: January 21st, 2002
Version 0.03: January 24th, 2002
Miles K. Light
----------------------------------------------------------------

Changes since Version 0.02:

1) Better pattern-matching for sheet-names. REGEX matches all word
characters ([0..9] and [A..Z][a..z]) between the last non-word
character and the end of the name. A period "." and trailing
word characters, like ".csv" is matched, but not included in the sheet
name.

2) Formatting: Anything in quotes ("") is now considered to be text,
and is formatted in XL as such. If it's not in quotes, xlwrite.exe
guesses what the field is and invokes the formatting.

3) Less information upon blank invocation.


------------------------------------------------------------------
Bugs:

1) Sorry, Miles, but once again I need to have some syntax output from
xlwrite.exe if it is given a balnk invocation.

	Here's the output I get with a blank invocation of
	xlwrite.exe: 
>>
----------------------------------------------------------------
D:\TEMP>xlwrite.exe

        XLWrite: An executable to create XLS files from .csv source files.
        Miles K. Light -- miles@mileslight.com
        January 2002


        Usage:  xlwrite file1.csv [file2.csv ... ] workbook.xls

        Multiple .csv files will be included into the workbook as worksheets.


D:\TEMP>
---------------------------------------------------------------------

	Please tell me if you don't get the default message next time.. it
	might be a machine-specific problem.

2) If I invoke  xlwrite test1.csv test2.csv test.xls

	I would expect the first and second sheets to be named test1 and test2,
	not test1_csv and test2_csv.
>>
The perl script now looks through the filename array, and tries to
fetter-out a reasonable worksheet name. This isn't trivial because
people have all sorts of names, including periods, slashes, etc.

As currently written, the script looks for the last period in the
argument, then selects the text/numbers between the last
non-word/number character and that last period. 

3) If I want to use the scratch directory to hold a CSV file temporarily,
	XLWRITE should ignore the scratch directory information when naming the
	worksheet.  For example:

	xlwrite 225a\a.scr 225a\b.scr test.xls

	should create a workbook with worksheets named a and b.  (Notice that
	the use of something other than .csv as file name suffix should be
	permitted in order to get GAMS to clean up the scratch directory.)
>>
Done -- as written above.

4) It would be helpful if xlwrite were to squawk a bit if it is unable to
	write the file -- a common error with this program will be trying to
	write to a file which the impatient user has already opened.  We need to
	let him know that something needs to be done / the file is already
	locked, etc.

>>
I put in a special file-checking component which aborts if the file
is not write-able.

5) We also should probably give credit to the Perl script writer?  Does his
	license permit us to distributed this as an EXE?

	I found that ASPACK reduces the .exe from 1.3 MB to 600K.

>>
Definitely compress the .exe if you can...
>>
The TERMS in the module are:

All Rights Reserved. This module is free software. It may be used,
redistributed and/or modified under the same terms as Perl itself. 

I'm fine with giving credit to John McNamara for the
Spreadsheet::WriteExcel module, but if we do this, we should also
give credit to the writers of these modules:

Spreadsheet::WriteExcel.pm
Exporter.pm
Carp.pm
DynaLoader.pm
File::Spec.pm
FileHandle.pm
SelectSaver.pm
IO.pm
strict.pm
base.pm
vars.pm
XSLoader.pm
Symbol.pm
Text::CSV_XS.pm
Fcntl.pm
AutoLoader.pm
Cwd.pm

6) Numeric formatting -- suggest that we insert the number with full
	numeric precision, but then set the XLS display format to 2 decimals by
	default.

>>
DONE -- if the string looks like a number, then it gets a #,##0.00
format. Otherwise it gets a string format.

January 21, 2002
/MKL
--------------------------------------------------------