[Lazarus] LazHelp, a help system written in and for Lazarus

[Kostas Michalopoulos]

Hi all,

For those who haven't seen the post in the webpage:
http://forum.lazarus.freepascal.org/index.php/topic,12463.0.html

I've written a help system for Lazarus in LCL called LazHelp. The help
system is written from scratch (it doesn't have any external
dependencies) and uses a custom TeX/RTF/HTML-like language to describe
a tree for the help site. The language looks like:

\page[name]{
\title[Hello]
\p{Hello, world! This is a paragraph.}}

The sources have a package (lazhelppackage) which provide five components:

  1. A central component which does the parsing, book-keeping,
rendering (not in itself but in a provided canvas so that it can be
used with custom controls), etc

  2. A page viewer which displays a single page and provides
navigation, history (with GoBack and GoForward functions), link
handling, etc

  3. A windowed page viewer, which is basically #2 in a form plus some
buttons and context menu for going back/forward/home (the default
page). This also scans the toplevel nodes of the tree for "button"
elements so that a help site can add additional buttons (such as
"Overview", "API", etc).

  4. A popup page viewer, which displays a page in the form of a quick
popup similar to those displayed by hints and goes away once it loses
focus.

  5. A simple component to feed #1 with code from a TStrings so that
the help can be embedded in the program (#1 can also load help files
from an external file using it's FileName property).

The windowed viewer can be registered as a help manager (using a
custom THelpManager descendant) via a property and can handle context
and keyword queries (context queries are converted to "hc<number>"
page names). Also it can be linked with the embedded (#2) and popup
viewers so that links open in the windowed viewer (an event can be
registered which can make the decision for that depending on the link
target). Finally, TLazHelp (#1, where the whole site is stored)
provides an event for processing links before they're handled by
itself, so special link names can be used to initiate host
program-specific actions (for example a link to open a dialog for
options or loading some special tutorial file/project for the host
program).

Additionally a help editor project is provided which is a simple
program with two panels: one where you write the code and another
where a page is displayed and updated automatically while you type the
code below. It also has a "View help site..." option to display the
site in a windowed viewer. The editor also includes it's own help site
with information about LazHelp, the syntax, element reference, etc.

LazHelp can be found here:
http://badsector.github.com/lazhelp/

A windows binary of the help editor (which you can use to see the help
system in action) can be found here:
https://github.com/badsector/lazhelp/downloads

The code is licensed under the zlib license.

In theory it should work wherever LCL works. In practice i tested it
in my iMac and it didn't fully work. The issues were:

1. The thumb of the scrollbar for the viewer was smaller than it
should be. Note that i use a TScrollBar for it.

2. The windowed viewer's position was set to 0,0 causing it to appear
under the menu bar and it was impossible to move it. The form is set
to "default position only". Apparently Mac OS X doesn't provide a
default position so i'll have to manually move it somewhere.

3. The popup viewer crashed. The crash initially was due to myself
taking the RGB values of the clInfoBk and halving them to put an
outline for the popup form. Removing the code didn't fix the crash,
however (although now it displayed the page). GDB backtrace showed
that the crash was in some function about setting the clipping
area/region and no part of the backtrace was in my code. At this point
i'm not sure what the case is, except that a Canvas parameter seemed
to be nil (0x0).

However that in my iMac i'm using a much older nightly build so the
issues might be due to that. I'll need to check with a fresh one (or
do a checkout from the svn).

I haven't tested GTK2 yet (i'm trying to download Ubuntu to put it in
a VM but my connection is terribly slow) but it should work fine,
except probably the borders since the GTK2 widgetset seems to ignore
the bsSingle BorderStyle.

If you have any comments, i'll be glad to hear them.
Kostas "Bad Sector" Michalopoulos