readme

excel to html

Welcome to xlhtml.


I. INTRODUCTION
The xlhtml program will take an Excel 95, or 97 file as input and convert 
it to highly optimized  html. The output is via standard out so it can be 
re-directed to files or piped to filters or used as a gateway on the internet.

II. INSTALLATION
If you are upgrading, run the 'make uninstall' target from the original directory
before following these steps.

To build this application, from the top directory type:
 
 ./configure --prefix=/<target installation directory e.g. /usr/local or /opt>
 make
 make install

Then to finish it up, you will need to go into netscape and tell the navigator 
to use the nsxlview script to handle Microsoft Excel files. 

	e.g. <path to executable>/nsxlview %s 

You should be able to then browse to a file and open it. There is a file 
included in the xlhtml directory you can test with: Test.xls.

The shell scripts: nsxlview & nsopen may need modification to correct the 
paths to fit your system. Also, depending on where you install it, you 
may have to modify your PATH environmental variable.


III. UNINSTALLING
You may want to keep this directory around since you can do a make uninstall
later. In the meantime, I suggest doing a make clean after installation to 
minimize disk space useage.


IV. COMMANDLINE OPTIONS
xlhtml now has several command line options that let you tailor its output. The
command is now:  xlhtml [-nc -a -fw -bc -tc -bi -c] file.xls

Where   -nc  tells it not to colorize the output.
        -a   aggressively optimize html by removing </TR> </TD> or VALIGN="bottom"
             Some older browsers may not display properly in this mode.
        -fw  suppress formula warnings about accuracy
        -bc  Override the background color. e.g. -bg808080     for gray
        -tc  Override the text color.       e.g. -tcFF0000     for red
        -bi  Use background image           e.g. -bi/home/httpd/icon/tar.gif
        -c   Centers the tables horizontally
        -te  Trims empty rows & columns at the edges of a worksheet
        -v   Prints program version
	-m   No encoding for multibyte
	-asc Ascii out of -dp and extraction data (-x?)
	-dp  Dump page count and max columns and rows per page
	-xp  Page for extraction (zero based)
	-xc  Columns (separated by a dash) for extraction (zero based)
	-xr  Rows (separated by a dash) to be extracted (zero based)

An example of the extraction command line is:
xlhtml -fw -asc -xp:0 -xr:2-6 -xc:0-1 Test.xls

The extraction output is: 
 Formatted output of cells by column left to right, columns separated 
   by a tab, end of row is: 0x0A, end of file: \n\n
   
   *NOTE: Run the gpdemo file for a demonstration plot in Netscape. Also,
   you MUST specify all 3 -x commands or the results may not be as desired.


V. PERFORMANCE TUNING
There are some user "tunable" parameters in the beginning of the xlhtml.c file.
The program allocates resources in chunks so that it scales efficiently without
wasting memory. The smaller the chunks, the less wasted memory. The trade off,
though, is that it has to allocate memory more often - which slows things down.
Odds are, you should never need to change them from the default.


VI. INTERNATIONAL CHARACTERS
xlhtml uses three different character sets. It tries to use ascii until it
finds a character greater than 127. At this point, it switches to the 
windows-1252 characterset. If the excel file specifies any 2 byte characters,
it switches to utf-8. This handles most situations correctly. If however,
you find yourself with a system that does not support utf-8 (text mode 
browsers & some versions of unix) and you need multi-byte support, 
try using the program lv.It can be downloaded from:

  http://www.ff.iij4u.or.jp/~nrt/lv/

The text only browser, w3m, could be used as follows for Japanese:

  xlhtml file.xls | lv -Iu8 -Oej | w3m -T text/html
  
 (Thanks to Hironori Sakamoto for this suggestion.)


VII. TROUBLESHOOTING
Using Netscape, you may occassionally see a file not found error. This usually 
comes when printing or going back to a previously converted file. This is
the default behavior and it can be changed by commenting out the rm $tmp* 
in nsxlview. I do this so you don't have files hanging around in your tmp
directory where other people might be able to see them.

In general, if you can type xlhtml and get a usage error message, the PATH
is working. If you don't, your PATH environmental variable needs adjusting.
Next try passing the full path to xlhtml of the file you want converted. If it
has problems with it, you may have a file the system can't interpret. To check
your installation, try passing the full path of xlhtml/Test.xls and see what
it does with that.

If you get an error message saying "get another compiler"...this comes from the
cole library. It needs a recent copy of automake, autoconf, or libtool. You
can manually adjust the header files if you know you machine data sizes.


VIII.  CONTRIBUTED SCRIPTS
xlhtml now has a contributed scripts directory. If you look in the xlhtml/contrib
directory you will find what people are giving me. I cannot offer support for
files I didn't create, but there is contact information with the files. If you 
have something to share...send it to me. If you've contributed...THANKS!


Charles N Wyble
[e-mail]