Jump to content

Photo

HTMLHelp: Sundry Tips, Trip-Ups & Musings


  • Please log in to reply
23 replies to this topic

#1
Schtearn

Schtearn

    Mountain Hermit

  • Project Member
  • 1,299 posts
  • Location: Australia
A facsimile (love the word) copy of the blurb at AHK- (Edit: well a few revisions behind as of 5/17 as the BBCcode differs):

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, 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:
 
<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:
<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:
 
Spoiler


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


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.

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.

Edited by Schtearn, 07 May 2017 - 03:24 AM.

I'm Borg! I'm Chairman of the Borg! -Iggy & the Assimilation Pops

#2
AndalayBay

AndalayBay

    #ffc0db Wildebeest under #0000ff Flying Shoes

  • Sys Admin
  • 12,273 posts
  • Location: Ontario, Canada
It really would be a lot easier to just write your own HTML 5 help pages. HTML 5 and CSS 3 are major improvements over the previous versions and I wouldn't be surprised to see modern browsers drop support for the older syntax.
Madam, you have between your legs an instrument capable of giving pleasure to thousands, and all you can do is scratch it!
-- Attributed to Thomas Beecham in reference to the performance of a female cello soloist

#3
The Great Smexy Pumpkin

The Great Smexy Pumpkin

    Magma Golem

  • Administrators
  • 12,603 posts
The beauty of this is that you can embed HTML files into a program instead of calling out to a browser. It makes it easy to look things up in the program without having to constantly switch windows. :)

#4
AndalayBay

AndalayBay

    #ffc0db Wildebeest under #0000ff Flying Shoes

  • Sys Admin
  • 12,273 posts
  • Location: Ontario, Canada
Then why does it have a browser test block? If you use HTML 5 and CSS 3, you can scrap all that because they all support it. :) You can still display the results in your own GUI. And put the appropriate hooks in your program to display the appropriate help section.
Madam, you have between your legs an instrument capable of giving pleasure to thousands, and all you can do is scratch it!
-- Attributed to Thomas Beecham in reference to the performance of a female cello soloist

#5
Schtearn

Schtearn

    Mountain Hermit

  • Project Member
  • 1,299 posts
  • Location: Australia

What's a browser test block? Someone said HTMLHelp can be used to sidestep browser lockout in a malware infected PC. Dunno 'bout that though. :P

It's actually possible to use HTML5 & CSS3 in it anyway, but haven't gone that route yet. :)

But yeah, it's ridiculous using a program so old- 20 years now? Even larger programs like AOO or Libre don't use context help- and what with the advent of WPF it doesn't seem to be called on anyway.

However, it would be nice if the browser developers of today cooked up their own chm utilities based on HTMLHelp. Chms are very portable, and even designing and implementing a web site in a chm_like gui could be quite fun!


I'm Borg! I'm Chairman of the Borg! -Iggy & the Assimilation Pops

#6
AndalayBay

AndalayBay

    #ffc0db Wildebeest under #0000ff Flying Shoes

  • Sys Admin
  • 12,273 posts
  • Location: Ontario, Canada
Browser test block:

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();
}
});
});

I have no idea what the context is or why this code is necessary, but code like that is a major PITA because it's notorious for failing on a regular basis.

I would imagine that you could change to HTML 5 and CSS 3 fairly easily.
Madam, you have between your legs an instrument capable of giving pleasure to thousands, and all you can do is scratch it!
-- Attributed to Thomas Beecham in reference to the performance of a female cello soloist

#7
Schtearn

Schtearn

    Mountain Hermit

  • Project Member
  • 1,299 posts
  • Location: Australia

Oh that's from the AHK content.js. It's used for their website.
Dunno who wrote that script or where it came from. Perhaps based on the old PHPBB setup there? Terrible format, and sparsely commented.


I'm Borg! I'm Chairman of the Borg! -Iggy & the Assimilation Pops

#8
Schtearn

Schtearn

    Mountain Hermit

  • Project Member
  • 1,299 posts
  • Location: Australia

AL pages load very nicely into HTMLHelp. As opposed to others. AHK produces tons of JS errors.

gallery_5078_72_79321.jpg

Don't know what the IPB 4.1 will do. :P

Edit:

Couldn't resist the Droste like effect on this post. :P

gallery_5078_48_23202.jpg


Edited by Schtearn, 15 March 2017 - 11:04 AM.

I'm Borg! I'm Chairman of the Borg! -Iggy & the Assimilation Pops

#9
The Great Smexy Pumpkin

The Great Smexy Pumpkin

    Magma Golem

  • Administrators
  • 12,603 posts
Wouldn't it be better to transfer that into the help file and provide a link to the download page in the help file that can be clicked on for more information? :)

I'm not entirely sure the HTML help system was designed with web browsing in mind. :P

#10
Schtearn

Schtearn

    Mountain Hermit

  • Project Member
  • 1,299 posts
  • Location: Australia

Wouldn't it be better to transfer that into the help file and provide a link to the download page in the help file that can be clicked on for more information? :)

I'm not entirely sure the HTML help system was designed with web browsing in mind. :P

Already done. Was just testing how the page would show. :)

No. Funnier how development of the incredible HTMLHelp system was dropped by M$S in favour of WPF crapware amongst other things.


Edited by Schtearn, 15 March 2017 - 02:53 PM.

I'm Borg! I'm Chairman of the Borg! -Iggy & the Assimilation Pops

#11
The Great Smexy Pumpkin

The Great Smexy Pumpkin

    Magma Golem

  • Administrators
  • 12,603 posts
Ah, okay.

They've been pushing Net for years, they've just started pushing harder lately. I've never been a personal fan of the approach they're trying to transition to with the whole UWP and all. :shrug:

The overall idea of a unified platform is a good one but, in my opinion, they're not going about it the right way.

#12
Schtearn

Schtearn

    Mountain Hermit

  • Project Member
  • 1,299 posts
  • Location: Australia

How's this for a laugh?

 

Here's the html for the welcoming page of HTMLHelp:

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>

<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Microsoft HTML Help Workshop 4.0">
<title>Microsoft HTML Help</title>
<style>@import url(coUA.css);</style>
<link disabled rel="stylesheet" href="htmlhelp.css">

<script language="JavaScript" src="master.js"></script>

</head>

<BODY background="blue.jpg" STYLE="background-repeat:no-repeat;">

<img src="hhwani.gif" align = right border="0" width="60"
height="60">
<h1>Microsoft HTML Help
</h1>

<p><a onclick="doExpand(exp1,ar1)" href="#nowhere">
	<img src="arrowdn.gif" id="ar1" border=0>Overview</a></p>
	<DIV CLASS="expara" ID="exp1" STYLE="display:">	
 
Microsoft&reg; HTML Help consists of an online Help Viewer, related help components, and help authoring tools from Microsoft Corporation. The Help Viewer uses the underlying components of Microsoft Internet Explorer to display help content. It supports HTML, ActiveX&reg;, Java&trade;, scripting languages (JScript&reg;, and Microsoft Visual Basic&reg; Scripting Edition), and HTML image formats (.jpeg, .gif, and .png files). The help authoring tool, HTML Help Workshop, provides an easy-to-use system for creating and managing help projects and their related files.
	</DIV>

<p><a onclick="doExpand(exp2,ar2)" href="#nowhere">
	<img src="arrowrt.gif" id="ar2" border=0>Features</a></p>
	<DIV CLASS="expara" ID="exp2" STYLE="display: none;">	
	<ul>
	<li>The HTML Help components, which consist of an ActiveX control or Java Applet to insert into HTML files, a help authoring tool, an online image editing tool, and an executable program that displays a user's help files.
<a href="whatis.htm" onmouseover="liteGo(go2)" onmouseout="liteOff(go2)">
<span ID="go2" class="endlink">GO</span></a>
	<li>An authoring guide with sections on how to design a help system and how to use HTML Help Workshop. 
<a href="guide.htm" onmouseover="liteGo(go3)" onmouseout="liteOff(go3)">
<span ID="go3" class="endlink">GO</span></a>
	<li>References that contain information about the HTML Help ActiveX control, an HTML Help API reference for developers, a complete HTML tag reference, and reusable help topics that explain how to use the Help Viewer. 
<a href="helpref.htm" onmouseover="liteGo(go4)" onmouseout="liteOff(go4)">
<span ID="go4" class="endlink">GO</span></a>
	</li>
	</ul>

	</DIV> 

<table border="0" cellpadding="0" cellspacing="0">

<tr> <td valign="top"><a href="overauth.htm"><img src="home.gif" alt="Home page link" border="0"></a>
</td><td><a href="overauth.htm">About creating help</A>
</td></tr>
<tr><td>&nbsp;</td></tr>
</table>

</body>
</html>

Here's the coua.css:

 

Spoiler

And the HTMLHelp.css:

Spoiler

Well blimey according to the background-repeat value the background bitmap somehow magically stretches if the window is maximised.

The JS scripts don't do anything:

Spoiler

But see the answers to this page, stretching or scaling didn't happen until around 10 years ago.

How did MS do that I wonder?


I'm Borg! I'm Chairman of the Borg! -Iggy & the Assimilation Pops

#13
The Great Smexy Pumpkin

The Great Smexy Pumpkin

    Magma Golem

  • Administrators
  • 12,603 posts
I think you have some styles inadvertently overriding others, I'll take a closer look tomorrow or the next day. :)

#14
The Great Smexy Pumpkin

The Great Smexy Pumpkin

    Magma Golem

  • Administrators
  • 12,603 posts
Why did you disable your stylesheet with
<link disabled rel="stylesheet" href="htmlhelp.css">
?

And your first stylesheet has
font-family: Verdana, Arial, Helvetica,
which should probably be
font-family: Verdana, Arial, Helvetica;

Edited by Visceral Moonlight, 04 July 2017 - 12:20 PM.


#15
Schtearn

Schtearn

    Mountain Hermit

  • Project Member
  • 1,299 posts
  • Location: Australia

My stylesheet? This is the decompiled original Help file for HTMLHelp ~1998 with revisions up to 2002 -think.

Did you find where MS have scaled the bitmaps? I think it's one of their best kept secrets. :)


I'm Borg! I'm Chairman of the Borg! -Iggy & the Assimilation Pops

#16
The Great Smexy Pumpkin

The Great Smexy Pumpkin

    Magma Golem

  • Administrators
  • 12,603 posts
Ah, then it looks like the generator may have messed some stuff up that's no longer supported by newer web standards. I'll look at fixing some of it up. :)

Does the viewer support HTML 5?

No idea on the bitmaps, sorry.

#17
Schtearn

Schtearn

    Mountain Hermit

  • Project Member
  • 1,299 posts
  • Location: Australia

There's no need to fix it, because it won't be needed. Just to illustrate a point that picture stretching in html was done a different way prior to CSS3  discussed at Stackoverflow,probably with the API. Compiling the above in a user chm will never get anything stretched or scaled unless using CSS3 attributes.


I'm Borg! I'm Chairman of the Borg! -Iggy & the Assimilation Pops

#18
The Great Smexy Pumpkin

The Great Smexy Pumpkin

    Magma Golem

  • Administrators
  • 12,603 posts
Ah, okay. I'll leave it alone then.

#19
Schtearn

Schtearn

    Mountain Hermit

  • Project Member
  • 1,299 posts
  • Location: Australia

Do you know MS still support DCOM95? With that you can view chm files on a 95 machine!


I'm Borg! I'm Chairman of the Borg! -Iggy & the Assimilation Pops

#20
The Great Smexy Pumpkin

The Great Smexy Pumpkin

    Magma Golem

  • Administrators
  • 12,603 posts
That's interesting. Is it compiled as a DOS or win32 executable? I'm curious! 95 and 98 still integrated DOS. I think that was removed around the Windows 2000 release or thereabouts.




0 user(s) are reading this topic

0 members, 0 guests, 0 anonymous users