[Lazarus] Building help files: the nitty-gritty

[Mark Morgan Lloyd]

Graeme Geldenhuys wrote:
> Hi Marco,
> 
> Nice chatting to an old friend again. ;-)

So lets all try to keep this friendly and constructive, without 
launching into a "my IDE's better than yours" exercise :-)

I'm writing this from the position of an outsider, so am happy to be 
corrected by Marco, Andrew et al. However if I there are areas that I 
haven't been able to "get my head round" after several days scouring the 
Wiki and Google, it's going to be far worse for a tyro. If somebody 
thinks I've got things wrong, I suggest that exploring /why/ I've got it 
wrong and what can be improved is in order.

> 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.

The current situation- and this is with Lazarus trunk, not stable- 
appears to be that HTML keyword-based application help works well 
provided that you're prepared to tolerate browser startup time. However, 
even worse than the startup delay is the fact that in the general case 
neither the IDE nor general apps can tell an existing browser to change 
the page it's displaying: I believe there's a backdoor for this sort of 
thing in IE on Windows but on unix you can end up with multiple browser 
instances that don't go away when the program's shut down.

I very much look forward to the CHM reader being made available for apps 
rather than just for the IDE, I'm starting to code what could be my 
magnum opus and I'd like the opportunity to exercise it.

> 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 end user is entitled to have all files of a particular type (chm in 
the current case) look and handled the same, but I'm not sure it should 
be the developer's choice which program is opened for a given file type, 
unless he is prepared to take full responsibility for things going wrong 
in other apps.

As a general point, current desktops (including KDE and Gnome) have a 
standardised set of programs for opening files by extension (xdg-open 
etc.), and to be quite honest I think it's not to the credit of anybody 
who tries to open a browser or viewer without reference to these.

> 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?
..
> 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.

I added a section to that page on adding a TOC yesterday and how to find 
what options are supported by chmcmd. I didn't want to be too verbose 
since it's hardly my area of expertise, but I felt it needed to be 
documented somewhere.

> 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.

The canonical tool appears to still be the Microsoft Help Workshop (or 
some similar name), and almost everything else appears to be based on 
this in some way: chmcmd is pretty much unique, to the extent that I've 
seen a Debian bug report asking why it's not packaged separately because 
of it's general usefulness. The Wiki page above mentions a 
product/project to convert Tex to chm which I've not investigated, I'm 
now able to convert Lyx source or PDF to HTML hence to a .chm including 
semi-automatic TOC (single-level) but it doubtless needs more work and 
I'm not sure what the situation is regarding integrating CHM in an app.

Got to go, sorry if anything above is incomplete or unchecked.

-- 
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]