[Lazarus] Building help files: the nitty-gritty

[Marco van de Voort]

On Tue, Jul 17, 2012 at 08:15:29AM +0000, Mark Morgan Lloyd wrote:

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

This has all been rehashed umpteen times. The bottom line: It's a work in
progress, people seem to start competing projects instead of chipping in.

Recent progress is slow or has stalled.

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

Decompress a zip with the html help on an ARM with SD or something else
slow.  Then the browser startup isn't the worst bit anymore.  (I've seen the
FPC installer do over 30 minutes of decompression on dos, and that was when
the docs were far smaller. The rest of FPC installed in 2 minutes)

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

It's not really IE. It is simply true browser instrumentation vs cheap and
easy fire and forget browser launching. 

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

I don't know if Andrew is still actively working on lview. I never worked on
the visual part. That's because I originally came to work on CHM from the
textmode IDE side, not Lazarus.
 
> 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.

This is too vague and generic. "look and handled the same" from where? From
the explorer, I agree, that is the users choice.

But the help is lauched from the app, not the explorer, and thus the
app developer's responsibility.

We all would like it otherwise, but on *nix it has been that way for a
while, and it doesn't look like it is going to change soon.

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

xdg-open is opening a document (and even then only the gnome-KDE lowest
common denomitor only.  I'm pretty sure KDE apps don't call their help or
instrument eachother via xdg-open)

I'm instrumenting an application, for which there is no standarized set. KDE
and Gnome afaik both have separate instrumentation (ORB like) systems, which
often change on major releases.
 
> 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

Be careful. That Workshop consists out of two tools, both equally horrid.
One is a simple editor for help projects, and one is the compiler.

You can do without an editor (just generating a hhp project from some other
source), and chmcmd is rougly equivalent with to the compiler.

Most "CHM" authoring tools call the MS compiler in the end. With some
crafting you can simply use commercial authoring tools and then export it to
a hhp project (or rescue that from %TEMP% while compiling).

Or just create html, and use the DOM tool 

chmcmd is rough, but I have gotten reports of people using it ON WINDOWS to
workaround bugs with the MS tool (which seems to have problems with big
files) :_)

Being able to enable the multi-core compression which is in CHM, but not
stable would be another really big boon.

Anyway, the chmcmd compiler should work for most basic projects. A simple
editor that allows you to add html to a project, scan it for labels and/or
outlines should be easy, as long as you control where the html is coming
from. 

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

Well I expanded chmcmd a bit in the last few releases to become a .hhp
compiler (before it was only rudimentary access to the chm writer class, I
basically added the same, but to/from the .hhp ini like format, implemented
recursive scanning for additional files).

But the real virtue is the CHM writer in general. chmcmd only instruments
it. Credit for that mostly goes to Andrew Haines. Sergei did some good work
debugging the HTML modules of fcl-xml too btw.

> 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.
 
The latex chms (ref,user,prog) are generated much the same way. See the
latexcompile or something program in the fpcdocs repo.  (the documentation
sources).  The cherry on the cake is the folding of the keyword index into
ref.chm.

Be warned though. It is ad-hoc code, probably not 2.7.1 compatible (due ot
unicode changes), and works around fcl-xml bugs probably resolved now.