Create an HTML frameset from Word, using PowerShell

I just posted this Windows PowerShell script to GitHub and thought I'd share it and some background about why it got created (and created the way it did).

First, you kind find it in my PowerShell repository on GitHub: https://github.com/JasonHershey/Powershell

The client requirements:

Not all client projects are big. In fact, many are small. This script resulted from a pretty simple request by a client. The clients asked for help in updating a single-page HTML 'help' file for a web-based tool. The clients are content and training experts, not experts at HTML. Their main need was to help them come up with a design that was more usable by the users of the tool, and also looked nicer. Oh, and they wanted to make improvements as quickly, and cheaply, as possible. At first, they thought they wanted me to create an HTML 'template' and teach someone on their team to author in HTML. But, we soon agreed that doing that, and the need for 'quick and cheap' didn't go together. For one thing, their author didn't know anything about HTML markup. After some discussion and investigation, I recommended something close to a 'do nothing' answer. The current page was simply a Word document saved-as an HTML page. And, since they had no requirements, like a need for localization, that suggested a need to do anything different, I recommended we stick with that. Their writer knows how to use Word and their own team could then handle figuring out the best 'design' for the content. Saving as HTML would result in a web page that looked like the Word document.

Great, but then they threw a wrench in the works. 

The clients decided the page itself would look fine, but it would still have a couple of usability problems. What they would really like to have is a left-hand TOC on the page that would help with navigation. OK. Not so easy to produce with save-as-html. I investigated a couple of other options for them. One that looked promising was simply opening a PDF version of the content with bookmarks open. Check this Adobe topic out for details: http://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/pdfs/pdf_open_parameters.pdf . Ulitmately, we had to forego that option because it doesn't work in all browsers.

Enter Frameset

But, what about a frameset? That used to be the classic way to create a a help website using MS HTML Help 1.4x (https://msdn.microsoft.com/en-us/library/windows/desktop/ms524245(v=vs.85).aspx). But, I did not want to generate HTML Help files. CHMs? Yuck! Plus, remember that my clients don't know HTML. The idea was to avoid having their writer learn something new.

But, its not hard to create a standard frameset, and its better to use iframes instead of the old frames. The main challenge was in creating the contents of the TOC frame. Happily, I've got some experience working with Word automation and WordML (Word's XML file format). And since I'm somewhat addicted to PowerShell, that was a natural choice for me.

It turned out to be surprisingly easy to script a solution. I did end up spending a lot more time on it than planned. That was mostly because I was having fun... and once I started scripting it, I wanted to make it easily maintainable. Happily, my clients agreed with me that this was not 'work for hire' and I could keep (and share) the code I was creating. So, I made sure to add a config file that would contain things like heading styles (which is how the script finds the headings in the Word document, and which would likely change depending on who's Word document we were converting) and some of the HTML markup (so it could be easily modified later). I even made sure the main frameset page looked like the webpage for the actual tool (matching header, footer, CSS). Most of that work isn't in the GitHub example, since its client-specific. But, I did leave the overall layout pieces there for others to play with. For example, you can do what we did and simply copy the HTML from an existing page into the appropriate sections of the frameset page to match your overall site design.... assuming it has that common header/footer/right/left/middle layout.

Results

The end result was a pretty flexible, and easy-to-use solution to the problem.

•  The writer still writes in Word, using the format of their choice. As long as their headings are identifiable with Word styles (even if its the default Word styles, like those used in the sample document).
• The users get a nice TOC to help navigate a fairly long web-page.
• The look-and-feel of the final results is pretty consistent with the original tool, which is 'just nice'.
• The process to create output is easy to perform by almost anyone, and easily to update in the future. The clients won't be totally dependent on me for updates.

If you get a chance, try it out for yourself and let me know what you think. And it is on GitHub, so feel free to branch it and add some features.