HTMLHelp: Sundry Tips, Trip-Ups & Musings

Helpful script writing tricks and HowTo's
User avatar
lmstearn
Posts: 131
Joined: 11 Aug 2016, 02:32
GitHub: lmstearn

HTMLHelp: Sundry Tips, Trip-Ups & Musings

03 Mar 2017, 08:11

Interested in using HTMLHelp for your own project?
Then read on!
Despite HTMLhelp running remarkably well for it's age in windows 10, can't help wondering why AHK stuck with it when there are good and possibly more user friendly (and free) programs around based on it.
Pity MS never made it open source like they never did with the (possibly superior) original WinHlp32 system.
In reading user comments on HTMLHelp the general consensus appears to be don't bother unless one is not competent in HTML.
TBQH mine own knowledge of HTML isn't great either, which is why using it as the recommended help system presents itself somewhat as a challenge.
The other thing to watch out for is keeping one's code to HTML version 4 or less (edit: unless venturing down this path), and there are not many 3rd party programs today that do it well enough (Bluefish and Dreamweaver come to mind as being useful in that regard). And the dinky (oh so nineties) gui featuring the Notepad-like CTRL-Z undo/redo toggle.

As MS's own riff on how to use HTMLHelp cannot be surpassed, we are not offering a full-blown tutorial,- just a few points on ease of use.

To begin with, download and install it, then run the executable hhw.exe from the install directory- typically Program Files (x86)\HTML Help Workshop.
The in-built help file describes how to start a project and add HTML files to it. It's recommended at some stage decompiling the AHK help file to see how things are setup, so let's do that now.
After decompiling the project to an empty folder, we note there is no hpp file generated so download it from github and copy it to the location where the decompiled AHK chm resides along with the Table of Contents.hhc and index.hhk. Upon closing any current projects in the Help Gui, open the AHK project and double click the windows section in the sidebar pane.
Click the files tab to verify the file layout. Note the settings in the other tabs and that the HTMLHelp WM_Help context question mark doesn't trigger on the controls. Meh. Also note there is no in-house "browser preview" of the content until the project is compiled, which at least has since become an integral part of the Visual Studio environment. Double click on the Options section for the tabbed options dialog- perhaps checking "Support enhanced decompilation" under Compiler generates the above missing hhp?
Click over to the Index tab to view the vast indexed list, then return to the contents tab and double click on Quick Reference. Yep, the layout is as with any other HTML page- the most critical is the following:

Code: [Select all] [Download] GeSHi © Codebox Plus

<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="static/theme.css" rel="stylesheet" type="text/css" />
<script src="static/content.js" type="text/javascript"></script>


The link href points to the theme.css file and the script source points to content.js where various js constructs reside. Note the above content is found on every page in the project!
The following line of code shows how an image in the project is linked:

Code: [Select all] [Download] GeSHi © Codebox Plus

<img src="static/ahk_logo.png" alt="AutoHotkey"></a>

BTW the in-house image editor is still very capable for its age!
Lets now look at the entire stylesheet here with some extra (hopefully explanatory) comments- bearing in mind OP has been using CSS for barely five minutes: :lol:

Code: [Select all] [Expand] [Download] GeSHi © Codebox Plus



So what now? How do we pare down something like the AHK file help for a smaller but fully functional and different help system? A good way is to modify the stylesheet with different font pitch font, colour, padding and so forth, but to aid the beginner with something much less erudite click Tags/Insert from the menu and note the slots are all empty.
Let's populate them! (A SuperUser may be able to expedite the following process)
Clicking Tags/Edit and the first empty slot, paste the following into the title edit box:
Standard link to file

And paste this into the Text block:
<a href="Root/File.htm">Link_to_File.htm_text</a>

Slot 2 title:
Metas (used by AHK)

This into the Text block:
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">

Slot 3 title:
Java Source

Slot 3 Text:
<script src="static/content.js" type="text/javascript"></script>

Slot 4 title:
Tables

Slot 4 Text:
<h3>Table Title</h3>
<table class="info">
<tr id="Something label">
<td>Something</td>
<td>Info on something</td>
</tr>
</table>

Slot 5 title:
Unordered List

Slot 5 Text:
<ul>
<li>Something</li>
<li><a href="htm file">htm filename</a></li>
</ul>

Slot 6 title:
Span for Color

Slot 6 Text:
<span style="color:red">red</span>

Slot 7 title:
Standard paragraph

Slot 7 Text:
<p>Blah...Paragraph can be broken up with <br> no closing tag required</p>

Slot 8 title:
Description List (From W3 schools)

Slot 8 Text:
<dl>
<dt>Coffee</dt>
<dd>Black hot drink</dd>
<dt>Milk</dt>
<dd>White cold drink</dd>
</dl>

And lastly for slot 9 do something fancy like the well-known Select All/Download routine:
Pre Code AHK style

And paste this into the Text block:
<pre>Some Code like Text</pre>

In the CSS
pre, code {
border-right: solid 1px #C8C8C8;
border-bottom: solid 1px #C8C8C8;
background-color: #F6F6E8;
}

In the js file

// Show select and download buttons in lower right corner of a pre box

var divStyle = {fontSize: "11px", float: "right"};
var aStyle = {cursor: "pointer", color: $("a:not([href=])").css("color")};
var selectLink = $('<a id="selectCode"></a>').text(translate.cdSelectBtn).css(aStyle);
var downloadLink = $('<a id="downloadCode"></a>').text(translate.cdDownloadBtn).css(aStyle);

$('pre').each(function(index) {
if ($(this).is(".Syntax")) {
$.extend(divStyle, {marginTop: "-32px", marginRight: "7px"});
$(this).after($('<div>').css(divStyle).prepend(selectLink.clone()));
}
else {
$.extend(divStyle, {marginTop: "-28px", marginRight: "28px"});
$(this).after($('<div>').css(divStyle).prepend(selectLink.clone(), [' | ', downloadLink.clone()]));
}
});

// Select complete code when clicking

$('a#selectCode').each(function(index) {
$(this).on('click', function(e) {
var doc = document
, text = $(this).parent().prev('pre')[0]
, range, selection
;
if (doc.body.createTextRange) {
range = document.body.createTextRange();
range.moveToElementText(text);
range.select();
} else if (window.getSelection) {
selection = window.getSelection();
range = document.createRange();
range.selectNodeContents(text);
selection.removeAllRanges();
selection.addRange(range);
}
});
});

// Download complete code when clicking

$('a#downloadCode').each(function(index) {
$(this).on('click', function(e) {
var textToWrite = '\ufeff' + $(this).parent().prev('pre').text().replace(/\n/g, "\r\n");
var textFileAsBlob = new Blob([textToWrite], {type:'text/csv'});
var fileNameToSaveAs = location.pathname.match(/([^\/]+)(?=\.\w+$)/)[0] + "-Script.ahk";

var downloadLink = document.createElement("a");
downloadLink.download = fileNameToSaveAs;
downloadLink.innerHTML = "Download File";

if (window.webkitURL != null) {
// Chrome
downloadLink.href = window.webkitURL.createObjectURL(textFileAsBlob);
downloadLink.click();
}
else if (navigator.userAgent.indexOf("Trident")>-1) {
// IE 10+
navigator.msSaveBlob(textFileAsBlob, fileNameToSaveAs)
}
else {
// Firefox
downloadLink.href = window.URL.createObjectURL(textFileAsBlob);
downloadLink.style.display = "none";
document.body.appendChild(downloadLink);
downloadLink.click();
}
});
});
}

Well not all that for Slot #9 really, but it's there if you wanted to know how it all works - or want to do something similar. :P

And the spanning tag can also be expanded to the following item via another element: e.g.h2

<li><a href="#Something">Something</a></li>
<span id="Something"></span><h2 id="Description_of_Something">Something</h2>
with
h2 {
color: #A04040; /* red */
in the css file


Take care if updating HHW for any reason as these, and other settings will be reset. To preserve the settings, backup the reg key:
HKEY_CURRENT_USER\SOFTWARE\Microsoft\HTML Help Workshop\Settings

Inserting these blocks into the help pages saves a little bit of extra work:- evidenced when only one project can be loaded in one time. Sure other files from other projects can be loaded, but in doing so leaves one prone to errors or unwanted files in the project as it evolves.

To create a search tab include this line in the hpp file:

Code: [Select all] [Download] GeSHi © Codebox Plus

Full-text search=Yes

Generating an Index is a lot more work, there used to be free tools to assist, and no mean task of writing code to pick up the text in all the tags in the project htm files, retaining the most "relevant" ones and then adding them to the index. Cross references would make it interesting.

For further reading, MSDN still has the Jan 1998 blurb on the then new HTMLHelp, (which show up as info or not secure in Chrome). Also the info at chmspec is very useful.
So there we have it- if there is anything amiss with a project the compiler will let you know. To actually link the files into an application refer to WM_Help Context IDs for GUI Controls and chm invocation. Using Anchors with the hidden attribute for topic section jumps is a good idea as well.
The AHK help file itself has been taken care of over the years by many hands, but some components still remain a mystery. e.g. the Footer. It doesn't use anything like a (floating) footer, yet the CSS definitions remain for it.
Good idea then to only keep the elements & classes that will be actually used in the chm.
:arrow: itros "ylbbub eht tuO kaerB" a ni kcuts m'I pleH

Return to “Tutorials”

Who is online

Users browsing this forum: No registered users and 8 guests