[Lazarus] Building help files: the nitty-gritty

[Graeme Geldenhuys]

Hi Mark,

On 10 July 2012 18:40, Mark Morgan Lloyd
<markMLl.lazarus at telemetry.co.uk> wrote:
> Relevance noted, will revisit. In that pretty pictcha of yours, should
> FPCHELP be decorated with a $ to indicate it's a shell variable?

No, DocView will handle that automatically. DocView can handle many
types of parameters and all are tested when DocView starts up.  eg: It
queries the environment variables defined on your system for a match.
Yes/No. Query if it is a directory? Yes/No. Query if it is a one or
more help files without the .inf extension (in which case it then uses
a predefined help directory/directories specified by the BOOKSHELF
environment variable)? Yes/No.  Query if it is a full path to a .inf
(with the .inf extension). Yes/No.  If still nothing, simply start up
with no help file loaded.

DocView comes with its own extensive docview.inf application help
file, which explains all this and much more.


> [Nod] I suspect that we're not the only people asking for guidance.

And it seems everybody is reluctant to give an answer. I guess LCL
based applications simply don't ship with help? Well, for the few LCL
based apps I have tried (excluding Lazarus IDE), that sure was the
case.

I just remembered form years ago when I still used Delphi 5 & 7, we
used to use a product called HelpScribble to author our .HLP help
files. HelpScribble now supports .CHM authoring too. So I guess that
answers my own question. You need to purchase a proprietary CHM help
authoring tool to generate your own CHM help, and you'll probably be
limited to author those help files under Windows only.

I'm still fuzzy on how LCL based applications know which CHM help
viewer to use though. This is especially important under Linux & MacOS
because the free CHM help viewers available on those platforms have
vastly different features and functionality. Some don't support
searching, some don't have Index support, some don't support CSS etc
etc. And I'm 100% sure they have different parameter options, so the
LCL app needs to know what it can and can't pass the the CHM help
viewer.


> Good point. But at the same time most unix-style OSes can't read .inf, so
> one would need to bundle docview or whatever.

Correct, and I don't have a problem with that. What I was getting at
is that different CHM help viewers support different features, and
there command line parameters will differ too. So how does LCL based
apps know how to tell each of those CHM help viewers that they must
display Help Topic Index 1234, or Help Topic String 'MyDialog1', from
the CHM help file of application X.

These are the most basic things that need to be address for an
application help to have working application help. Amazing no LCL
developer has come across this yet. Maybe the little bit I know of LCL
is just too little. ;-)


-- 
Regards,
  - Graeme -


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