Today I’ve been playing with the idea of creating a set of help pages suitable for display in a website I am creating, but also to enable the same information to be used to create a compiled help file, such as you might find installed with any Windows application.
In the past, I have created web help pages, FAQs and so on, and also virtual websites that have been used as the source for HTML Help Workshop (I’ll call this ‘Workshop’ from now on) to create a compiled help file (*.chm)… the Microsoft technology that merges the benefits of html with the power of the ‘Help’ architecture. But so far, they have remained separate entities; either entirely separate, or in one case I had to quit before even dealing with the issues, so the compiled help just pointed the user to the application’s website for certain types of information.
Well, obviously that’s a bit lame… but let’s take a moment to consider some of the differences between a web server, and the Workshop (that creates the compiled help).
HTML Workshop is Yet Another Browser
What I mean by this is that Workshop software can be considered yet another browser, that will interpret your html and css differently from any other browser. I’ve been cheating recently and taking some shortcuts that mean that some of the differences are not fresh in my mind… however, a couple of differences I recall are:
- Positioning (float-type) elements do not work very well / at all in HTML workshop;
- Workshop will not allow css-specified bullet images on unordered lists.
That doesn’t sound like a massive list (it isn’t really) but they’re the two that spring to mind. The problem is that the first issue can play havoc with a site layout designed for the web, and while the latter may not have dramatic layout effects, if you try to specify bullet images in your CSS for Workshop, you get no bullets at all. In other words, Workshop not only seems not to understand the list-style css element, if it encounters it, it does not display any bullet at all. That does effect readability.
The good news is that we do not necessarily need to force Workshop’s needs into our existing css… we can create an entirely separate ‘development site’ for Workshop, and tweak the css for it specifically.
The Development Environment
Before I explain what my first hopes for sharing web pages were, I probably need to explain a little bit about my ‘development environment’ is for web pages and HTML Help.
Firstly, it is that I use Macromedia Dreamweaver (now owned by Adobe I believe). Sites are developed on local servers, and as Workshop can understand html and css, it makes sense to use Dreamweaver to develop help ‘sites’ too.
Secondly, a page of compiled help is likely to have different requirements from a page on a website. On the website, you will want all sorts of header code, possibly some sort of menu along the top of the screen, and possibly also down the left of the screen. You may want areas for adverts, and so on.
On the compiled help, in contrast, it is likely that you will not want much of this navigational fluff; the Help Reader application will provide much of the navigational material – for example Contents, Index and Search. You may want to show a large logo, as in the screenshot of the Dreamweaver help, but this is not something that you will want to have on every page.
Attempt 1 – Using Directory Shortcuts
I’ll refer to two ‘sites’ – one real website and the virtual site for the compiled help development. The pages were developed in a subdirectory of the main website. Then, in the compiled-help site, I created a link to the original directory. As the real directory and the link to it had the same name, and were located in the root directory of the relevant ‘site’, I hoped that links within the manual pages could successfully leverage relative or absolute links to other manual pages.
I quickly gave up on this idea, as I realised that Dreamweaver did not recognise the directory link as being a real directory; it recognised it as a ‘lnk’ file that it did not know what to do with. Similarly, Help Workshop failed to be able to follow the linked directory.
I guess that the whole idea of shortcuts to directories in Windows is intended as a user-oriented feature, not a feature for software.
Attempt 2 – Dreamweaver Templates
So, assuming that directory shortcuts were not going to work, I would have to rely on manual copying of files between the two directories. This was a frustration, but ultimately was just a procedural annoyance. Maybe I’d be able to improve on it in future.
I still had to address the issue of the differing formats required for the website and the compiled help. At least this was relatively easy; the two site structures allowed for different css files (so no major work-arounds required to embed support for both types of use in just one file). Still, css will only get you so far in page reorganisation… time to consider the wonders of Dreamweaver templates.
Just as a site-wide css file allows control of the appearance of a website across-the-board, so do templates. You can set up Dreamweaver templates to repeat content across many pages that doesn’t change, yet still allow each page to have different content. Change the template, and you can set it to update all the pages that use that template. This gave me a two-pronged approach to resolving the problem.
Fortunately, Dreamweaver maintains links to the template files in a relative form too… that meant that once the pages were copied across to the new site, Dreamweaver would pick up the new template file, and essentially reformat all the content to a new html layout… the local css file would also change the detail of the formatting.
There are some tweaks that were required to get this procedure to work. After copying the files across to the new site, they retained the original template format (though correctly picked up the new css file immediately). Fortunately, Dreamweaver also supplies a mechanism to update pages from the respective template. So, after selecting the newly copied files in Dreamweaver, and Updating them from the templates… problem sorted!
The Procedure to Create the Compiled Help
When I want to create a new version of the online help, I simply change the website files. To create an updated compiled help file, I have to:
- Copy the ‘manuals’ directory from the website to the compiled-help site. The manuals directory also has a sub-directory for the associated images, so they are moved across at the same time;
- Open Dreamweaver and the compiled-help site. I select the menu Modify | Templates | Update Pages…, and set the options to update all the files that use a particular template related to the manual pages. This updates the pages to use the template specific for the compiled help;
- Open the HTML Help Workshop files which reside in the root directory of the compiled-help site, and generate a new chm file;
- To help prevent confusion in the future, I then delete the contents of the manual directory in the compiled-help site, to ensure that I do not accidentally start making changes to the ‘wrong’ version of the manual.
Summary
Although the procedure to share these files is not automatic, it is preferable to work from the same core data, and put a little effort in for occasional ‘translations’ that are required to generate the compiled help. It makes sense to have the original files for the website, as the compiled help only needs to be created occasionally with new software releases.
Are there alternative mechanisms? Almost certainly – any number of them. But I feel that this was an appropriate solution given the design and structure of the source website. Perhaps sites that had started life in different formats might have required new PHP format files to change the site generation, or perhaps alternative xsl transformations to convert source xml into html. I wrote about using xslt before, though on that occasion I used xslt to convert html into an xml format.
Dreamweaver sometimes doesn’t have a good reputation among ‘real’ web designers (I’ve seen job adverts that specifically exclude applications from ‘Dreamweaver jockeys’) but I really like the way that it lets you see the site content at all times, and always leaves your files as usable html – no pre-processing required (unless, of course, they are php and other ‘programmatic’ file types. Having websites that need no pre-processing also makes them faster on shared servers!