[Lazarus] Building help files: the nitty-gritty

[Mattias Gaertner]

On Tue, 10 Jul 2012 17:39:05 +0100
Graeme Geldenhuys <graemeg.lists at gmail.com> wrote:

> Hi,
> 
> On 10 July 2012 16:40, Mark Morgan Lloyd
> <markMLl.lazarus at telemetry.co.uk> wrote:
> >
> > You're right, but "bigide" explicitly includes ChmHelpPkg (i.e., if I
> > understand things correctly, the various viewers) while "all" doesn't.

make bigide does not include chmhelppkg. You have to pass
OPT=-dUseCHMHelp to do that.

 
> As far as I understand it, that simply registers CHM help with the
> IDE, and gives the IDE a default location of where to find LHelp. And
> with newer Lazarus IDE versions, the IDE will automatically try to
> compile LHelp if the executable doesn't exist. This still doesn't
> compile/generate any of the CHM help files themselves.

Correct.
The docs have references to the RTL+FCL docs, which are outside the
Lazarus sources and have references to programmers guide, which
requires latex. The whole doc build chain has too many dependencies and
need several minutes to build. That's not feasible for a simple make
command.

 
>[...]
> > So presumably that's where the (Lazarus) IDE's FPDoc editor comes into it?
> 
> Correct. But remember, that when you add comments, they become part of
> the documentation. You cannot disable or switch off "user added
> comments" at a later date.

There is a feature request to hide comments when there is an fpdoc
entry.
And there is a feature request to support the new fpdoc notes.
I don't know the state of the annotation system.

 
> > Noted, but I'm using Lazarus (and this /is/ the Lazarus mailing list, so
> > please don't act all surprised :-)
> 
> I know that all too well. :)
> 
> My question still stands though. I don't know what is the
> recommendation for "application help" with LCL based applications. eg:
> I create a new project which is a new Programming Editor. I want to
> supply a end-user help file with my binary - like all good software
> does. What help file format do I use (as the developer of that
> product), and how do I create/edit that help file?
> 
> 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. But what is the source help format for CHM, and what tools
> (help editor) do I use to edit that source format, and what tool do I
> use to "compile" that source help format into the end result CHM file?
> Also, how does my product know where to find LHelp (or whatever CHM
> viewer I want to use)?

I can't help you there.
Same for what image format to use, what installer to use, what version
control system or what upgrade system.

Mattias