All my products ship with documentation in the form of a compiled HTML (CHM) file. I also provide the same content online. Maintaining the two different HTML projects was always a pain which I could have solved through the use of a third party tool like Help and Manual. But I am cheap and a few years ago I hit on a solution that allows me to maintain a single copy of my documentation and build it to a compiled help file or upload it as HTML to a website.
Tag the HTML
My individual help files (which are all just HTML files) are littered with custom tags encapsulated within HTML comment tags. So, for example when my help files are displayed online I like to display a simple menu at the top of each page, but I do not want this appearing in the CHM version. So the top of the HTML body in all my documentation HTML files looks something like this:
<body>
<table width='100%' border=0 bgcolor=#6699cc>
<tr>
<td width='100%'>
<h1>Help Topic Name Goes Here</h1>
</td>
</tr>
<!--insert php here-->
</table>
Note the “insert php here” tag in the HTML comments.
Search and Replace at Build Time
When I am ready to build a new version of the software (and compile a new CHM file and upload documentation in HTML form) I just need to search and replace the HTML using the free tool FART (Find And Replace Tool). Here’s some of the relevant lines out of my build script (which is just a DOS batch file).
@ECHO BUILDING HELP FILE
"d:\Program Files (x86)\HTML Help Workshop\hhc" "d:\Path\To\HTML\HelpProject\help.hhp"
ECHO Deleting old online help files
delete "d:\Path\To\Online\Help\Files\*.htm"
ECHO Copying help files to online help directory
copy "d:\Path\To\HTML\HelpProject\html" "d:\Path\To\Online\Help\Files\"
ECHO Replacing place holders with PHP
fart -q "d:\Path\To\Online\Help\Files\*.htm" "<!--insert php here-->" "<?php include('inc/header.php');?>"
fart -q "d:\Path\To\Online\Help\Files\*.htm" "</head>" "<?php include('inc/google-tracking.php');?>"
fart -q "d:\Path\To\Online\Help\Files\*.htm" "<script src='scripts/footer.js'></script>" "<?php include('inc/footer.php');?>"
@ECHO FTPing FILES TO WEB SERVER
"d:\Path\To\WinSCP\winscp.exe" /console /script=winscp-ftp-help-file.txt ftp_login:ftp_password@ftp.somesite.com
Line 1 compiles the CHM file. I use good old HTML Help Workshop from Microsoft to do this. It works well and but I maintain all of the project files in a text editor because the GUI is awful.
Line 4 deletes the old temporary copy of the online HTML files.
Line 6 makes a copy of the HTML files into the temporary online HTML location.
Lines 8-10 uses the FART tool to do the search and replaces. Note that I’ve replaced a custom tag with a php_include, replaced the </head> tag with a php include that generates Google Analytics code (and puts the </head> back), and finally replaced a js footer with a PHP equivalent.
Line 12 uses the very neat WINSCP command line SFTP tool to upload the files.
So, there you have it. One set of HTML files can be used to generate a CHM file using HTML Help Workshop and to generate online HTML files. It works very well and automating the process using tools like FART and WINSCP have made my build and release process a snap.