CSV-to-HTML 2.1

User Documentation

Copyright © 1996 by Jamie Flournoy.

The CSV-to-HTML application, its sample files, and this documentation are copyrighted and may not be distributed except as described in the freeware license at the end of this document.

Check the CSV-to-HTML Home Page for update information.

Contents:



What is it?

The Simple Explanation:

CSV-to-HTML
turns CSV-exported Excel spreadsheets
into complete HTML documents.

See CSV-to-HTML run. Run, CSV-to-HTML, run!

The Detailed Explanation:

CSV-to-HTML converts CSV-format spreadsheet files, which can be exported from Microsoft Excel, into HTML tables wrapped in a complete HTML document. You can convert a single spreadsheet in 30 seconds or less: just Save As... in CSV format from Excel, switch to the Finder and drag the document onto CSV-to-HTML, and you're done.
CSV-to-HTML is a fat binary application (runs on 68K Macs and PowerPC Macs). There are lots of ways I could tweak the code to make it faster, but it's already so darn fast I don't feel like performance-tuning it. It took me about 3 minutes after I finished and tested the PPC version to make the 68K version, test it, and stick the 68K code in the PPC application to make it "fat".

[Top]



Why I created it

I created CSV-to-HTML because I needed it: I had a spreadsheet I wanted to put online. It was a price list, and needed to be updated every couple of days, so manual conversion was out of the question. I wrote version 1.0 because I needed the conversion of the price list to the web page to be automatic. Eventually I started embedding a bunch of link tags in it and it got pretty big, but it was still only one file, about twice a week.

It also was written in MetroWerks CodeWarrrior 5.0 ANSI C, using the CodeWarrior SIOUX enviornment. This environment is character based because ANSI C is character based. Basically the compiler takes care of the menu bar and putting a single window on the screen, and you just print text and read typed input. It looks like DOS, but it's really easy to program, and that's the point of SIOUX - I had a working application in just a few hours. For my personal use this was OK, but it fell far short of what a good Macintosh application should be. Still, once I had it I told a few people about it and they wanted copies, so I sent it to them.

This new version (2.x) is everything the old version wasn't. It is not character based, fussy, non-intuitive, or single-file-oriented. It is user-friendly, AppleEvent aware (and thus can accept dropped files in the Finder), and provides visual feedback and error messages. It's also customizable in that you can change the HTML tags, the filename extensions, the creator and file types, and even the error messages (if you feel like it) from ResEdit. This means that if you're serving the pages from a PC, you can use .HTM instead of .html, or you can change the look of the table by making the TABLE tag different.

If you drop a large number of files (like 50 or more) on CSV-to-HTML, you may find that it hangs or crashes. This is because the big list of file references that the Finder hands to CSV-to-HTML lands in CSV-to-HTML's own memory, not System memory. This means that if it's a big enough list, bad things will happen. The solution is to force-quit CSV-to-HTML (using Command-Option-Esc) and then in the Finder's Get Info window for the CSV-to-HTML application, increase the Preferred Memory size. Of course, your computer has to have some extra unused RAM when you do this or it will have no effect. But that's not CSV-to-HTML's fault.

[Top]



What doesn't it do?

It doesn't convert from Excel's own native spreadsheet format. You have to export from Excel format to CSV format, using Save As... in Excel and changing the file format in the Options dialog box to CSV format.

It doesn't preserve the visual formatting of the spreadsheet, because CSV doesn't allow it. This means that boldface, different fonts, font size, color, and so on are not preserved in the conversion process. Again, this loss of formatting happens in Excel when you save as CSV, not in CSV-to-HTML.

It doesn't let you change things like output file type, HTML tags, and filename extensions in a nice pretty preferences dialog box. However, if you can use ResEdit, you can change the output file type, all the tags, and the filename extensions. Just look in the STR# resources and it'll be obvious which does what - they're labeled and everything. See below for details.

It doesn't convert graphs from Excel to HTML format. You have to save the graph as a GIF or JPEG (copy it to the clipboard, make a new document in GraphicConverter, GIFConverter, or Photoshop, paste, and save as GIF or JPEG), then put the <IMG...> tag in the spreadsheet or HTML file manually. I suggest you put the tag in the spreadsheet so it doesn't get wiped out every time you update the HTML file.

It doesn't carry formulas over to the HTML file. Of course, it wouldn't be useful if it did since Netscape doesn't understand Excel formulas anyway, but I thought I'd mention it.

It doesn't let you open files with the regular "Open..." dialog box, known to Mac developers as Standard File. This is because that was a whole 'nuther can of worms to add on and I really don't think anybody needs to use this program that way. Drag and drop is much easier. Maybe in a future version I'll add it.

[Top]



How does it work?

CSV is a very simple format, which separates each cell in a spreadsheet with commas. Because a cell might have a comma in it, the format takes care of this by wrapping the whole cell in double-quotes (") to say, "Hey, this isn't a cell break, it's an embedded comma." This bings up another problem, which is that of a cell with a quote in it. Well, the format dodges this one by putting two quotes back to back to signify a quote in the original cell. Since you'd never encounter a cell with nothing in it that had to be wrapped in quotes, a double-quote would never naturally occur. So a line with two cells, one saying Hi and the other saying "Hello, good morning" would convert to: Hi,"""Hello, good morning""" in the output file. It's not very complicated.

All CSV-to-HTML has to do is replace the CSV cell and line breaks (comma and carriage return, respectively) with the HTML tags that define table cell and line breaks (TD and TR, and their closing tags) as well as wrapping the the cells with the HTML, HEAD, BODY, and TABLE tags and their closing tags so the output file is a bona fide HTML document all by itself.

Someday, if I can figure out SYLK or one of the other export formats, I might write a utility to convert that format to HTML, but only if it preserves formatting or has some other big advantage. The big work is already done, since all I have to do is rewrite one function (the filter function) to make it convert from a different format. Suggestions in this area are welcome, and it'd be great to get real docs on these formats if anyone has them.

[Top]


Customizing Output

You probably won't need to, but you can change the filename extension, HTML tags, and file types that CSV-to-HTML uses for the output file. You probably won't need change anything unless you are converting a LOT of files and want the output files to be generated differently than the way I decided they would. If you're working with one file, you can do this all manually, but if you're working with 300 files it's a lot faster to have CSV-to-HTML do things the way you want the first time rather than cleaning up after it yourself.

You have to use ResEdit or another resource editor to do this, but it's really really easy. First, make sure you have a clean copy of the application in case you screw everything up.Then, just double-click on the icon for the 'STR#' resources:

...and you will see this, or something very much like it:

Double-click on the appropriate STR# resource, and a window will pop up with all the strings for that purpose in a list. Just change the appropriate string to whatever you want, and save the file.

Customizing Filename Extensions

The idea here is to let you change the extension to ".HTM" or ".shtml" or ".list" or ".nclk" or something. You can make it from 1-31 characters long (if you delete the resource entirely, make it too long, or make it null, the default extension will be used instead). If you're not careful and you decide to change the filename extensions to be very very long (but still no more than 31 characters) then some of your output files may get overwritten by the files converted after them due to name clashes.

For example, if you name three input files filenumber1, filenumber2, and filenumber3, and then make a 21 character extension like excelspreadsheet.html, only the first 10 characters of the output filenames will differ since the last 21 will consist of the extension. Thus, all these files one by one will be converted into filenumberexcelspreadsheet.html which will end up containing the converted version of filenumber3.

Customizing HTML Tags

Do whatever you want, even change the strings to null (delete the text in the boxes) but don't delete any of the resources from the list or all the tags after the one you deleted will be shifted down and it'll really mess up your output files.
Do delete: <HEAD>
Don't delete: 1) *****
NumStrings 10 should be at the top of the window. Of course you can add as many resources as you want, but only the first ten are used.

Note that carriage return characters do carry over to the output file, so if you want to generate nicely formatted output, throw in a few and your HTML file won't all be one huge line of text. The default tags already have some in there, although ResEdit doesn't show them if they're trailing (just use the forward arrow key to reveal them - they're there).

Post-Conversion HTML Editing Tips

If you want to edit the output file after it's done, of course you can do that since it's regular old HTML- I suggest that you use BBEdit simply because it's clean and quick, and has pretty good search and replace capabilities. Of course, I made this document in PageMill, and you may already have an HTML editor, but remember that it has to either support tables or ignore tags it doesn't know about, or it'll screw everything up. Don't worry, most Mac HTML editors either understand or tolerate table tags.

If you always plan to post-edit your files, you might want to look into customizing the creator type to match that application's creator, so you can just double-click your output files and your editor will launch and let you edit them. I didn't do this because there are some really good type changers out there, my personal favorite being FileTyper. Go to the archives if you don't already have it.

[Top]



License

This application is freeware, and can be distributed freely as long as there is no charge. If you use it I would appreciate an e-mail with your comments; I'll be more likely to revise it and create similar applications in the future if you do.

Inclusion on CD-ROMs and disks is encouraged, within reasonable distribution costs. Specifically, I give you my express permission to include it on a shareware or freeware CD without even asking me if the single-unit price for a customer is equivalent to US$25 or less.

In addition, I absolutely require that you include the documentation and sample files with the application when you distribute it. In this way all the people who receive the application will get everything I put into it and will get the most out of it, without having to pay for it. If I wanted people to pay for this I would expect to get some of that payment, but I don't, so it should be free (or as close as possible) to the end user.

Licensing terms of future versions may differ from these, but these terms will continue to apply to this version (2.1) regardless of future releases.

[Top]




Warranty

I tested this application on my machine and it works. I tried to break it in every way I could think of, and then tested for those situations in the software so it wouldn't fail. If it causes you consternation, data loss, profuse bleeding, property or even financial losses, I will not be held responsible for any of that. Swim at your own risk.

Please report any bugs you find to me, but do not assume that this entitles you to an update - it does not.

[Top]




Release Notes / Version History

You're not actually reading this part, are you? I guess you are. Well, here it is, though I don't know why you care. This is mostly for geeks anyway:

2.1:

Fixed the 68K crashing problem caused by a bogus array reference (my mistake). I had it read the HTML tags into an array starting with the second element (duh) which meant that </HTML> overwrote part of the stack and caused the app to quit with a Type 1 error when it tried to return from the "read in the HTML tags" part of the code. Sorry for the frustration for those of you who downloaded it and actually expected it to work on your machine.

2.0

Definitely deserving of a whole-number version increment. It looks like a Mac application and even handles AppleEvents (not like I had to use the object model or anything advanced like that but it is pretty cool)! Definitely a learning experience but there's still a long way to go... now it needs a user interface. Hopefully I can recycle the framework as a starting point for other converters. There are also a lot of buffering things I can do to speed things up, which I may or may not ever get around to.

1.0

Written in MetroWerks CodeWarrior Gold 5.0 using the SIOUX environment. Gross but functional, and acceptable for my own personal use.

[Top]

That's it! Happy converting!