[Lazarus] Building help files: the nitty-gritty

[Mark Morgan Lloyd]

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

Agreed, and the various wiki pages etc. do appear to stress that the 
final conversion of files to .chm is still work-in-progress (with 
caveats on alignment etc.).

>> Right, so stop crowing about it FFS and just say HOW TO DO IT. Then somebody
>> else can come along and demonstrate that a .chm is no more difficult.
> 
> :-)  I've explained this many times before, and then created a web
> page to stop repeating myself.
> 
>   http://fpgui.sourceforge.net/docview_ide_integration.shtml

Relevance noted, will revisit. In that pretty pictcha of yours, should 
FPCHELP be decorated with a $ to indicate it's a shell variable?

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

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

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

Good point. But at the same time most unix-style OSes can't read .inf, 
so one would need to bundle docview or whatever. Which I think suggests 
that an important point is having a flexible and foolproof document 
generation process, which can produce .inf, .chm or whatever... 
basically, any format where a viewer can jump straight to the relevant 
section (which specifically excludes .pdf, for this role).

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

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

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

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