[Lazarus] Building help files: the nitty-gritty

[Graeme Geldenhuys]

Hi Marco,

Nice chatting to an old friend again. ;-)

On 16 July 2012 20:14, Marco van de Voort <marcov at stack.nl> wrote:
>
> Since linux doesn't guarantee any helpsystem, any solution is going to be a
> compromise.

It's not about Linux not having a dedicated help system, it is about
what works with LCL-based applications. And more specifically about
context sensitive help in those applications. eg: I don't want my
users to press F1 and then be taken to the start page of the help
(this is how most Linux Gnome/KDE apps currently work, and that is
totally braindead!). I mean like the focus is in an edit field, and F1
will give help about that specific edit field, or fall-back to help
about that specific dialog. That is context sensitive help in
applications, and how help is supposed to work.

Incidentally, this is how all my fpGUI based apps work too, but I
simply couldn't find similar information or solutions for LCL-based
applications, hence my question here.


>> Now if you tell me CHM, that means I need to ship LHelp with my
>> product because Linux & Mac users don't have CHM help viewers out of
>> the box.
>
> Both have several chm viewers available (kchmviewer, gnochm, xchm). If you

As I told somebody in a earlier reply, I don't mind shipping the help
viewer - that is not a problem at all. I just don't want to leave it
up to chance... eg: maybe no CHM help viewer is installed, so then
application help doesn't work. Or, as is currently the case under
Linux, each CHM help viewer has vastly different features and
performance. I'd much rather use a specific help viewer, and know what
experience my end-users will have.


> The last time this came up, Michael said there was support in fpdoc for
> general helpfiles. But afaik there are no examples.

And I'll say that that is absolute rubbish. fpdoc was designed as a
source code documentation tool, and that is what it is good at. It
definitely doesn't have the design or features required for
application help.


> In theory CHM files can be created with any html tool, can be organized with normal MS
> html workshop, and then compiled using FPC's chmcmd (2.4.4 in theory, but
> 2.6.0's is better)

So where do you define the TOC or Index items? Inside the HTML files?
Is there documentation or a wiki page on the usage of chmcmd?

I searched the wiki and would these two useless pages:

   http://wiki.freepascal.org/htmlhelp_compiler
   http://wiki.freepascal.org/chmcmd

Neither describes how to actually create application help, define a
TOC or setup Index entries.

And this URL...
       http://wiki.freepascal.org/Add_Help_to_Your_Application
...explains a bit more, but uses plain HTML files located in a folder.
Still no TOC, Index or Search support, because they are simple HTML
files that will be viewer with a web browser, and not CHM help.

As I mentioned in a earlier post too. I remember using HelpScribble,
which is a commercial Windows product that we used in the Delphi 7
days to author application help. It now (for some time I guess)
supports CHM too, but the help source is in a proprietary format, and
magically generates a CHM file from that. You define the TOC and Index
items from within HelpScribble. What is the equivalent for LCL
application developers (eg: cross-platform application developers)?
HelpScribble is a Windows only tool, and uses the Microsoft help
compiler - but I guess it could possibly run under Linux WINE, but I
haven't tried.


>> Also, how does my product know where to find LHelp (or whatever CHM viewer
>> I want to use)?
>
> That's a *nix/Linux, not a Lazarus problem. If the OS is braindead and doesn't
> support this, what's other option is there then to do it yourself?

What are you talking about? Of course it is a Lazarus problem! How do
you tell your LCL program where to find the help viewer? How do you
tell LHelp (or any other CHM viewer) to load a specific CHM file, and
then display a specific help topic (like in the case of context
sensitive help)? Lazarus IDE does this for the RTL, FCL and LCL, but
how would you do this in LCL applications? In the IDE you have the
chmhelp package, you have a Help configuration dialog etc  Must you
design and build the same functionality into your LCL based apps, or
is there already something like that in LCL that developers can use?

eg:
In fpGUI it has a default location and file name it looks for to find
docview (the recommended help viewer). The developer can override the
helpviewer executable name and path. The fpGUI framework knows what
parameters docview supports, so knows how to call docview to display
specific help topics.  The fpgApplication instance has a HelpFile
property to specify where an applications specific INF help file is,
but docview also has a predefined location that it searches for help
files - again user configurable.  To create your own INF help, one
simply needs to edit a single plain-text file, with very easy markup,
which is much less verbose than HTML or XML. The markup language is
mnemonic, making it easy to associate them with their functions.The
TOC and Index items are define inside the single plain-text file. Then
simply compile the help source file with the supplied WIPFC help
compiler executable, and you have application help in the INF format.

Simple, easy and configurable. And this process is well documented in
the docview.inf file - supplied with DocView.

In seems LCL application help creation is just the opposite. The
Lazarus IDE is slowly but surely getting a help system working, but
none of that functionality translates to LCL based applications. LCL
application developers are still left behind - 10+ years into the
Lazarus project.

So maybe you can shed some light on this topic, seeing that you are
the creator of CHM tools in FPC & Lazarus. How do you add context
sensitive help in your LCL based application? Or do you simply not
ship help with your applications at all.


-- 
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://fpgui.sourceforge.net