[Lazarus] Building help files: the nitty-gritty

[Reinier Olislagers]

On 17-7-2012 10:15, Mark Morgan Lloyd wrote:
> 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 :-)
Totally agreed.

>> 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.
<snip>
> The current situation- and this is with Lazarus trunk, not stable-
> appears to be that HTML keyword-based application help works well
> provided <snip why HTML help might not be such a good idea>
> 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.
>From another outsider's view, wouldn't this be a solution:
1. document the IPC mechanism used for communication between IDE and
lhelp so application developers can use it
2. compile and distribute lhelp with your application... should be
possible already, shouldn't it?
3. in application: start lhelp and pass messages using 1.

- I don't know intercepting e.g. an F1 keypress from being sent to
system wide help would take special action... perhaps it doesn't.
- Perhaps there is some Linux standard or GNOME or KDE standard that
indicates how to do *keyword sensitive help* with chm files.
In that case the approach above could be a fallback mechanism... or this
approach could be a fallback mechanism depending on programmer's preference.


>> 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.
I'd lean to this conclusion as well.

> 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.
I don't think changing the system wide association between the .chm file
type and the executable to open that is what Mark or I would have in
mind. In any case, I agree that is bad.
However, given my solution above, this step would not be necessary at all.

> 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.
In general, agreed, but:
If that standard allows keyword lookup etc.. I'm all for it. Also, the
number of standards must be manageable ;)
Finally, quite probably not *all* desktops support this (saw your
"current" up there)... so a fallback mechanism would be needed if others
are supported, too.
It may just be too much effort to support all of it... unless this
effort can be moved into some kind of cross-platform application help
framework to be included in say... Lazarus ;)

> The canonical tool appears to still be the Microsoft Help Workshop (or
> some similar name), 
Microsoft HTML Help Workshop, if I've got the right one installed here. Yes.