Introduction

Owenhelp is a standalone Delphi 7 program and a pure-HTML solution, both intended to provide HTML help for your project. Source is provided under a BSD License, which pretty much means you can do whatever you want with it so long as you credit me: j.g. owen, http://owenlabs.org/, owenlabs@aol.com.

The owenhelp Delphi source should also be usable with a Delphi 7 project, or maybe later versions of Delphi — i.e. compiled with your Delphi program¹. Probably more usefully (?) it can be used as a stand-alone program that you WinExec from your program, and your program communicates with Owenhelp via a simple-minded file-based system. ... And then, perhaps most amusingly, there’s my rendition of pure HTML help.

Contents versus Index

I see I’ve done my best to continue an illiterate confusion that predates my birth: my indexhlp program produces an “.idx” file which, nevertheless, contains a Table of Contents — a list of selected topics in the order in which they appear in the HTML help. An index would, of course, be an alphabetical list. ... So in the following text, if I refer to “index” just assume I’m senile and mean “contents table”....

Dire Warnings

Owenhelp is distributed in owenhelp.zip, and should be unzipped in an empty directory, like (using the sometimes-flaky but handy Info-Zip unzip) “unzip owenhelp.zip”; if you use winzip, you must tell it where to unzip, and click the “use folders” thing.

Once you unzip owenhelp.zip, your home, your pets, your loved ones, and your entire earthly existence will come immediately to a complete halt. EVERYTHING WILL BE OVER! ... I am giving away this stuff, and everything wrong with it is YOUR FAULT! ... YOU HAVE BEEN WARNED!

The Winexec Version

The basic idea is that your program “winexecs” owenhelp — programmatically runs owenhelp.exe — with one or two arguments. There should be a Visual Basic 5 demo project1.exe (I like to keep up with the latest compsci revelations) that does just that. ... Before that of course you would’ve composed an appropriately massaged HTML help file. Subsequently, your program would communicate with owenhelp by writing a specially-named file which owenhelp will read and delete. That’s the idea. The general idea of an owenhelp-based project is:

1. You have a wonderful program or an idea.
2. You write the help, using the free Kompozer HTML composition program, or some other HTML composition program. I recommend writing the help as early as possible, maybe even before you write your program; Kompozer, at least, is fairly expressive, and you can get all kinds of ideas down that could be helpful.
3. You go something like “indexhlp yourhelp.htm yourhelp.idx -nyourhelp.num >to_fix” to create the idx file owenhelp is looking for.
4. When you want to show the help for your program, you write code that (1.) writes a special file and (2.) somehow execute owenhelp with some arguments.

And that’s it! EZ does it!

Things Wrong With IWebBrowser

Of course, nothing is wrong with owenhelp itself! ... But the TWebBrower gadget used by the program is based on Microsoft’s IWebBrower and it’s not perfect:

• No way to copy. You can right-click on the stuff and there’s a “copy” item — but it doesn’t do anything. Oddly, “print” on the same menu does work; I could even check “selection” in the print dialog and just print the selection.

I’m sure this list will gather more items.

Winexecing Owenhelp

Probably the hardest part of using the stand-alone version of owenhelp is figuring-out how your favorite language can execute another program. From a batch file you can sometimes just say “owenhelp” or depending on your version of Windows and phase of moon, you might have to do something else. In form1.frm in the visual basic demo project (see the source) it’s like

and I just found that by googling². This apparently executes owenhelp in the current directory where your program is executing (or actually in this case the demo, project1.exe); if you want it to be executed from somewhere else, you would specify that path somehow in the WinExec, or some other execution environment / program might require you to explicitly set the current directory as appropriate and/or specify a directory in the WinExec.

Owenhelp expects none, one, or two arguments:

1. The caption for your help. This is what appears on the top of the help, and it is also used by owenhelp to off any extra copies of itself that you might’ve accidentally set-off. If you don’t supply a caption it won’t do that. As depicted in the example, BLRs “_” will be translated into spaces for the caption.
2. The second optional argument is the name of the file you want to use to send owenhelp commands. It can be any arbitrary name; doesn’t have to have an ini extension — although it uses the well-known and antique Windows .ini format. If you want to specify the command file but not the caption, just use a 1-character caption, which owenhelp will ignore.

Helphtm Subdirectory and Other Default Values

The owenhelp program has various assumed values that will be used if you don’t specify otherwise, either at invocation ...

• “owenhelp” is the default caption.
• “owenhelp.ini” is the assumed ini file name.

or in the ini file

• “helphtm” is the subdirectory where owenhelp expects to find ...
• “owenhelp.htm” is the default help file.
• “owenhelp.idx” is the default content file.
• “owenhelp.num” is the default and optional numbers file.

Owenhelp assumes your HTML help and any beautiful pictures you want to include are in an “helphtm” subdirectory of the directory from which owenhelp executes. I would assume owenhelp would execute in the same directory as your program — generally a good idea — and having the help in its own subdirectory is also generally a good plan. Most install programs are quite capable of installing a subdirectory filled with stuff — I use and actually paid-for “InstallMaker” by “ClickTeam”, which may even still exist — but a zip file can do that with ease.

If it’s a small help with only a few pictures and you just want everything stuffed in one directory — and I can certainly sympathize with that — set “helpdir=.” in your ini file.

Owenhelp.ini and its Commands

If you want to change any of the default ini values the ini file should probably exist before you start owenhelp. And as noted above, if you didn’t specify an ini file when you started owenhelp, it will expect owenhelp.ini. Writing the ini command file is probably easier than execing owenhelp, but still is in the computer science mysteries department. In the project1 Visual Basic 5 source it’s like

when the program demonstrates the “find” function. As shown, the first line of the ini file should always be “[options]”; that’s the way ini files work.

The Ini File is Deleted

After owenhelp reads the ini file, it deletes it ... so it won’t read it again. ... That’s how it works. If your program were really interested, it could check for the existence of the file as an acknowledge mechanism.

The other stuff in the ini file can consist of various commands that alter owenhelp behavior / change defaults.

• helpdir: To change the default subdirectory for owenhelp; “helpdir=.” — setting it to a single period — sets it to nothing. The default is “helphtm\”.
• helpname: The name of the htm file. Default: “owenhelp.htm”.
• indexhlp: The name of the index/contents file. Default is “owenhelp.idx”.
• helpnumb: The name of the optional numbers file; default “owenhelp.num”.
• top, left: The position of the help; both default to 0.
• height, width: Etc. Both default to “no change” — i.e., leave the distribution size.
• pleasefind: Default is empty. If you want to instruct owenhelp to goto a particular topic, you set pleasefind to the topic name, as in the example. Alternately, you could set pleasefind to a number, and owenhelp might show the topic based on the info in the owenhelp.num file.
• timer_interval: Default is 1000 aka 1 second — the rate at which owenhelp checks for an ini command file, and a few other things. If that’s too leisurely, you might want to speed it up which, of course, makes owenhelp use more CPU.
• close: Default is 0. Writing an owenhelp command file with “close=1” would close owenhelp. Normally your program when it closes would first emit an ini file with this command — which could cause a problem if for whatever reason owenhelp wasn’t running then — like the user already closed it — since the ini file would linger-on and close owenhelp the next time it started. So if you do that, it might be wise to delete the owenhelp ini file when your program starts; or make sure you emit the ini file (clobbering any existing one) whenever you start the help. ... Like project1 didn’t do, until I noticed owenhelp closing erratically....

The HTML Frames Alternative: No Stinking Executable!

And then of course, pondering the defects of the T/IWebBrowser, I realized the simplest solution is to just use an HTML browser, and so I did! ... See various excuses and explanations of how to use the supplied indexhlp program to concoct two additional HTML files; it’s EZ!

The Owenhelp programmed solution might be more appropriate — particularly the Delphi built-in route¹ — when you want to create a more “professional” look. The straight-browser strategy works much better — well starting the browser is much slower, but otherwise. ... But I didn’t know how to force the browser to open/goto a particular topic, i.e. I couldn’t implement context-sensitive help — oh wait a moment, of course I can, see Context-Sensitive HTML Help. ... And, of course there’re ...

Context-Sensitive HTML Quirks

• Once you’re in the browser at your context heading, you might want to make the print bigger with control-+; when you do that, your place is of course immediately lost — but you can get it back just by clicking the reload button.
• If your program shells to the help a second time, and the browser hasn’t been closed, today’s browsers will probably stick the thing in another tab or something — which I think is kind of cool. ... But then, if you go back to the first tab and reload, it’ll goto the help on the 2nd tab, because the context mechanism I concocted uses a global javascript file.

You understand, I don’t consider these significant problems. ... Anything is better than standard Microsoft help; the worst thing about HTML help is, on many computers, it’s so slow to start....

ShellExecuting the HTML version

The project1 Visual Basic Version 5 source demonstrates this approach:

Dim Owner As Long
Dim Result As Long
Owner = 0
Result = ShellExecute(Owner, "open", "helphtm\owenfrm.htm", "", "", essSW_SHOWDEFAULT)

Who knew Visual Basic could do these things? ... Not me, certainly....

Linux

The owenhelp program only works in Windows, so if you want to utilize this wonderful pile of confused software in Linux, you got to use pure HTML help. Indeed I do exactly that in the Linux version of my beautiful OwenShow, perhaps around here on the internet. To utilize this stuff, you’d have to figure how your software can do the various things the “project1” basic program does for the HTML help; also, of course, compile indexhlp with your copy of Gnu g++ — and I just did that, in Unbutu 7.04! — see “__GNUC__” conditional in indexhlp.cpp source — and I saw this help with Firefox in Unbutu! ... In a VirtualBox, incidentally. ... I, of course, cheat, and create my OwenShow help in Windows. ... (The conversion of the rest of the rollicking OwenHelp utilities is left as an exercise for the user....)

No Linux ShellExec

And of course, in Linux there is no ShellExec — well there is, probably, but it varies by KDE versus Gnome etc., and probably the likeliest thing is what I did in OwenShow: run your favorite browser (aka “firefox”) on the appropriate file, but allow the user to configure which browser.

Direct Execution Anyway?

And even in Windows, the direct execution route seems a little faster. In my OwenShow, since I am actually the only one who ever uses it, I default the Windows version to executing “c:\Program Files\Mozilla Firefox\firefox.exe” on the htm file — but first checking if the Firefox path exists, and if not, falling-back to ShellExec.

Context-Sensitive HTML Help

The sweet beauty of it all! ... Just a little dash of javascript, like (from the supplied “owenhelp.htm”, this help)

<!DOCTYPE HTML PUBLIC “-//W3C//DTD HTML 4.01 Transitional//EN”>
<html><head>
<script language="JavaScript" src="owenhelp.js"></script>
<title>Owenhelp help</title></head>
<body onload="owenhelp()"><h1> [...]

— with the blue-colored stuff added into an average HTML form as shown. ... Then “owenhelp.js” would look like

function owenhelp() {
window.location='#Context-Sensitive_HTML_Help';
}

if you wanted to load the help starting at “Context-Sensitive_HTML_Help” — you can just look at the “.idx” file indexhlp creates for these names, but substituting underlines “_” for spaces. ... Of course, your wretched program would have to somehow create “owenhelp.js” in the HTML directory, before shooting-off the help. ... Like this (from the supplied Form1.frm / Project1.vbp source):

Balks In Internet Explorer 7

I mean who knows why — or cares? — but I just tried it, and the famous Microsoft Security prevents it from executing something; on a local file. Right. ... So use Firefox. ... Oh I just had to click “allow blocked content”! But you’d have to do that every time. ... So “script” was apparently already enabled — but I guess that doesn’t really enable something mumbo - jumbo - gobbledygook- conspiracy - in - restraint - of - trade. ... Oh all right, I could make it stop demanding confirmation, in Internet Explorer 7 at least, with

• “internet options / advanced / security section”
• check “Allow active content to run in files on My Computer”

What fooled me was instead of “internet options / security / advanced” — no no no you silly boy — it’s “internet options / advanced / security” — see? ... Sometimes I think everybody at Microsoft is on drugs. ... I thank a genealogy site for this useful information.

... Of course checking the item does sound dangerous — but running Internet Explorer is dangerous! ... I normally set my firewall to block it entirely, although I confess I may have exposed my machine for a while doing this reckless research....

Composing the Help with Kompozer

I recommend the free “Kompozer” HTML tool (google for it); it’s more than a little quirky and crashes now and then, but is capable of producing perfectly fine help files for owenhelp; just be sure to save often!...

Kompozing the Beautiful Contents

The idea is that every H1, H2, or H3-style headline in the file that includes an “anchor” will turn-up in the help contents that owenhelp automatically displays on the left, after my “indexhlp” program processes your HTML file — assuming you’ve followed my esoteric style rules for the anchor, which are: no spaces, use BLRs aka underlines aka ’_’ instead — which, I just noticed, Kompozer enforces itself the clever devil! ... Some random punctuation will probably cause trouble too, I really haven’t done exhaustive tests; I think Kompozer’ll just toss it if so. ... The H1-H3 headlines are shown appropriately indented, and if you create the index with the indexhlp “-a” option, all anchors will be included, with non-H1-H3 anchors shown a little-more indented. You use the included “indexhlp” program to create these wonderful contents; also I like to process the HTML file with the included jgwrap.

Anchors beginning with a BLR “_” will not be used for the contents, unless “indexhlp -d-”, so you can have useful references in the file without cluttering the contents.

Also best of all, you can make the type bigger in Kompozer with control-+ (and smaller with control-minus) — just like Firefox!

Disruptive Innovations Bug: Pasting is Dangerous

Well really, I do like Kompozer, and I am amused by its checkered open-source history. Originally written by one fellow, it was then forked by a second who fixed numbers of bugs. The first guy was deeply offended or so he claimed, but I’m persuaded the second guy has the moral high ground; the first guy admits he’s no longer developing the product, and claims it’s because some day he will create a new incredibly better tool — of which, of course, there is not the slightest trace. But I suspect it’s because after hacking the mozilla composer (?) source for a while, he could couldn’t fix it anymore....

Whatever, neither author got rid of Kompozer’s tendency to insert garbage when you paste. This is a major annoyance, and in fact I was bitten writing this help, and went through major conniptions whacking it back. Amusingly the garbage it inserts often includes

http://disruptive-innovations.com/zoo/nvu

which is apparently a web-site associated with the first author!

So the defensive practices I should’ve followed while I was screwing-up my help are

• save often, and archive various copies as you go.
• write and use a batch file or something that checks for “disruptive-innovations” and “chrome” (something else that shows-up in the paste garbage) and use it frequently on your *.htm every time you save.

which, in the general outline (save ’n’ check), are good ideas in any text-editing / coding project. ... As far as I’ve noticed so far, the bug shows-up mostly when one pastes formatted text in Kompozer — which one does a lot when one is re-arranging one’s sprawling and disorganized help file....

Indexhlp program

For the contents on the left, owenhelp (the program) wants an index file; a text file filled with the headlined-anchors etc. You create this with the included program “indexhlp” like

indexhlp owenhelp.htm owenhelp.idx -nowenhelp.num >to_fix

The optional “owenhelp.num” is an ASCII file that would be created by you if you want to associate Delphi-style help numbers with help topics; see owenhelp.num for desired format. If you use the -n option with such a file, any topics missing from the file are output to stdout, which you can redirect as shown above.

For pure HTML help, in addition to your HTML help file, you need a frame and contents HTML file, which will be created by indexhlp if you modify the command-line to be

indexhlp owenhelp.htm owenhelp.idx -nowenhelp.num >to_fix -h -t"Owenhelp Help"

Entering indexhlp without any arguments will print a supposedly-informative message like

indexhlp in_file out_file Copyright 2001-2007 j.g. owen (tkc)
Tries to make an adorable list of the H1,H2,H3 referenced targets like <H1><a name="Main Screen">. Note that it translates _ to space, and *indents* the list as per H2, H3.
-a Use *any* anchor.
-i- Don’t indent index items (i.e. indicating H level).
-nfile Check that anchors are present in the file; emit errors to stdout (case sensitive!).
-h[owen] Produce browser/frame version of the help; [default] root; the program might produce two files "owenfrm.htm" and "owenidx.htm", i.e. with the supplied root. "owenfrm" is the help file.
-t"Help" Provide a title for -h. BLRs converted to spaces, and/or quote.

which provides the excuses for the HTML “-t” and “-h” options; see the included makeindex.bat file for an example of this almost-unbearable excitement....

Demo Project1 Operation

Project1.exe and its source is included with owenhelp. It is supplied and should be run in the same directory as the owenhelp program, with the owenhelp HTM file & etc. in the subdirectory “helphtm” — which should be the default layout of the owenhelp.zip distribution file.

Clicking the left “help?” button is supposed to load this help; clicking the “find” button is supposed to locate this topic section. If you check “Find+Load”, it’ll try to load before finding when you click Find? ... If it doesn’t do these things, it’s entirely your fault....

And then the first big button on the bottom is supposed to set-off the frames alternative version. And the button below that, “HTML shell + context”, will infallibly launch this help in a browser with that topic showing....

Various Included Programs and Files

Owenhelp is distributed in owenhelp.zip; the version of the owenhelp program is ascertained by running owenhelp by itself from the command line; the caption should show some cryptic letters and a date — or, if that doesn’t work, you could examine the source file TLA.I. Then again I haven’t updated that for a while, but this help should be time-stamped, and the indexhlp program prints its own cryptic letters....

In the root of the zip file:

• owenhelp.exe: the program that shows help.
• project1.exe: a Visual Basic 5 demo of the owenhelp program.
• msvbvm50.dll: Visual Basic 5 brains.

The helphtm subdirectory of owenhelp.zip contains various functional material, source zips, and other junk probably:

• jgwrap.exe: processes HTML files to make “cute” quotes, and various other activities. makeindex.bat demonstrates usage.
• jgwrap.zip: C (Builder 5) source for jgwrap.exe.
• ch.exe: a program I run while using Kompozer; it copies to the clipboard cute quotes and an apostrophe — which I don’t use, since jgwrap takes care of those — the dash, and three pieces of HTML junk I insert using Kompozer’s “Insert HTML” feature:: (1., 2.) curly and uncurly, which defeat jgwrap’s cute quotes, and also jgwrap’s destruction of the “&nbsp;” nonbreaking spaces Kompozer habitually and inappropriately strews through the HTML, and (3.) date/time, which causes date/time to be inserted as below.
• ch.zip: Delphi 5 source for ch.exe.
• owenhelp.htm: this file. Also gregor.gif, ureplig.gif, and type.jpg, my beautiful pictures in here. And probably ...
• owenfrm.htm — a frames version of the help — and owenidx.htm, the contents file used by owenfrm.htm.
• Owenhelp.num is manually created to provide numerical equivalents for the help, and should be used as an example if you want to compose such a file.
• indexhlp.exe: used to create owenhelp.idx, like “indexhlp owenhelp.htm owenhelp.idx -nowenhelp.num >to_fix”. The “to_fix” file would wind-up with topics missing from owenhelp.num, which you would correct manually. Or, as noted above, you can use the program to also create straight HTML help.
• makeindex.bat shows a typical invocation of indexhlp — and so much more....
• indexhlp.zip: C source to indexhlp (Builder 5).
• project1.zip: the VB5 source for project.exe.
• linkoid.exe: running this in the same directory as your HTM file might tell you of missing links; at least, that’s what I use. You should ignore the upper-case complaints. Or run it as shown in the makeindex.bat, “linkoid -r”.
• jgo_loid.zip: C source to linkoid.exe (Builder 5).
• owensrc.zip: and finally, the Delphi 7 source to the owenhelp program itself.
• owenhelp.js and empty_owenhelp.js. Makeindex.bat copies empty_owenhelp.js to owenhelp.js. Owenhelp.htm includes the ingenious pure-HTML context help mechanism, so it tries to load owenhelp.js and execute the owenhelp() function when it starts — and if there is nonesuch when the program version runs, the program complains! The browser from which this component is supposedly derived doesn’t do that. ... When you contrive your own help, just don’t put the javascript in if you’re using the program version. I include the “.js” files in the zip so the demo of both systems in project1.exe will perform flawlessly without requiring different helps. ... Actually if you click the HTML button first in the demo, and then click the little “help” button to start the program help, the program help will open starting at the “Context-Sensitive HTML Help” — because the browser component is still seeing and loading owenhelp.js!

Philosophical Issues: Not Microsoft CHM Help

Note that this is not the CHM help Microsoft promulgated a few weary years ago. The genesis of owenhelp was the discovery that the even-older Microsoft “.hlp”-style help was verboten in the exciting new Vista operating system. ... I tried somebody’s free CHM composer and it was simply awful; took forever, weird, broken. And then it turned-out CHM itself is already in the ash-heap of history — Microsoft disowns it!

Owenhelp — the Winexec, or Delphi form version — is tied to Microsoft’s snares in that the Delphi HTML component used is based on Microsoft’s, and so you have to have Internet Explorer 4 or better installed. All I really know in this department is that project1.exe and owenhelp seemed to work on my Windows 98 system, as well as XP and Vista. ... Who can say more? Of course the beautiful pure HTML help works fine even on Linux....

A Single Help File

Owenhelp assumes a single HTML help file because I can’t stand those stupid help systems where each screen is like three words and a stupid graphic. I believe they are totally counterproductive. I’ve used this kind of one-file help for a mildly sizable commercial project with 47 topics and an 86K HTML file, and it works OK. ... And of course the HTML-only 300k-or-so OwenShow help. ... It probably wouldn’t be that bad to modify various parts of the owenhelp package to use multiple files — feel free!

... Which brings us to efficiency — which I make absolutely no effort to achieve. ... I mean, we’re using Windows here folks; it’s silly to even think about it....

And then there’s transparency: I want my users to be able to run my help in a browser if they feel like it, modify it if etc, do whatever. ... I assume you do too; you could probably somehow make owenhelp secret i.e. like the gracious and lovely but doddering HLP and CHM files — but I certainly wouldn’t spend any effort on it....

BSD License

Owenhelp is copyrighted under a BSD-style license as follows.

Copyright (c) 2007, James Gregor Owen
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

* Neither the name of the author nor the names of any associates may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

1. Compiling the delphi code into a delphi program is not actually so simple. In jhelp.pas you have to do “{.$define STAND_ALONE}” i.e. stick the period in to make it undefined, and include the jhelp.pas and sbrs.pas files in your project. ... But then you have to (1.) divert help to your code by setting Application.onhelp to your subroutine, which should handle all help by using those Delphi numeric help codes, presumably calling the provided routine in jhelp, and (2.) get hold of “D6OnHelpFix.pas” (by the admirable Robert Chandler) somewhere on the web and add the unit to your project — since Borland apparently broke onHelp in Delphi 6 and 7.

or something to invoke another program in Visual Basic 5 — so what do I know?

Friday 5/18/12 4:38 pm