[Lazarus] Building help files: the nitty-gritty

[Mattias Gaertner]

On Sat, 28 Jul 2012 15:01:36 +0200
Kostas Michalopoulos <badsectoracula at gmail.com> wrote:

> I just noticed this (there is a lot of activity in the mailing list and 
> i only browse it occasionally).
> 
> On 10/7/2012 6:39 μμ, Graeme Geldenhuys wrote:
> > Hi,
> > My question still stands though. I don't know what is the
> > recommendation for "application help" with LCL based applications. eg:
> > I create a new project which is a new Programming Editor. I want to
> > supply a end-user help file with my binary - like all good software
> > does. What help file format do I use (as the developer of that
> > product), and how do I create/edit that help file?
> >
> 
> Personally i have written a custom help system:
> 
> http://badsector.github.com/lazhelp/

About the name "lazhelp":
I'm not a great namer myself, and tend to use technical names as well,
so I understand your choice for the name.
But I fear the name "lazhelp" has become confusingly ambiguous.

To avoid name clashes with third parties the Lazarus developers
prefix/postfix all new units, for example with "laz". If third parties
use the same prefixes, we have a problem. ;)
So I ask anyone kindly to be more innovative when creating new projects.

 
> It is made up of a bunch of components that can either provide the help 
> content from inside the program (f.e. from a resource or just a string 
> list) or from an external file. The help can be displayed as a 
> popup/tooltip, inside a panel using a custom control or a separate 
> window with back, forward, home and other optional buttons (like 
> introduction, tutorial, etc). It can also be registered as a help 
> provider for LCL (so you can use HelpContext etc in controls).

Nice.

 
> The viewer is written with LCL so it should be portable (although there 
> are some inconsistencies, especially regarding scrollbars). There aren't 
> many things supported by the language (which has a simple syntax) but it 
> should be enough for simple applications. For larger help sites, it 
> probably needs more stuff (f.e. there is no table support).
> 
> I have used it for Runtime World, my 3D world editor:
> 
> http://chiselapp.com/user/badsector/repository/rtworld/
> 
> and for LILCard, a hypercard-like program:
> 
> https://github.com/badsector/lilcard
> 
> (the latter shows how the help system can become part of the executable 
> itself since lilcard is a single executable in all platforms)
> 
> The reason i made it is, as you have said in other threads, i find 
> Lazarus current help situation to be inadequate at least. Additionally, 
> i don't want to distribute a huge executable for viewing CHM files (in 
> the case the user's computer do not have the ability to view CHM files) 
> and i find the CHM viewer's user interface to be somewhat complex.

Huh?
The chm viewer "lhelp" has only "home", "backward", "forward" and a menu
to open and close chm files. If I understood your above text
correct, this is less than your viewer. 

The reason for a separate executable is that the help viewer should be
usable independent of any modal forms, mdi, hints or docking of the
application.
Of course it would be nice to have a LCL control
to view chm files in applications. It should not be that hard to write.

Mattias