[Lazarus] Lazarus documentation

[Marco van de Voort]

On Tue, Dec 29, 2009 at 02:11:23PM +0200, Graeme Geldenhuys wrote:
> >> very bad idea by the way.
> >
> > Explain.
> 
> Unlike Windows, there is no default CHM viewer for Linux.

True. The default depends on desktop suite (gnome ->gnorpm, KDE ->
kchmviewer, rest mostly xchm or use a CHM plugin in mozilla)

> So if lhelp is a CHM viewer, why can't we use it for other CHM (non
> Lazarus related) files. 

What is the point? There are already at least 4. Admitted, none is default,
but a 5th one won't suddenly become default either.

> Otherwise Linux users would have to install two CHM viewers - one for
> Lazarus CHM files and another for any other WINE projects that have CHM
> files. 

So what? Then at least we can focus lhelp sharply on Lazarus' needs, and not
get bogged down in Wine users complaints and feature wishes, just to save
on average 1.5 MB of kchmviewer on a minimalists HDD. Lhelp is about
FPC/Lazarus' needs, not about Wine's.

> If that is the case, if lhelp doesn't support other CHM files, then I will
> simply use a CHM viewer like GnoCHM (or any of the others) than do support
> any CHM files and ignore lhelp.

The other viewers are just that, viewers/ebook readers.

lhelp is meant as the backend of an integrated helpsystem. For an IDE.

Lhelp should be
- be instrumentable to be able to forfill all roles for the IDE (all forms of search, including
   fulltext)
- be relatively lightweight (no additional packages as dependancies)

This is easiest achieved when lhelp is a part of lazarus more or less, and
the way to instrument is undocumented (so the best can be chosen on each and
every platform, and can be changed if the optimum changes), and uses an
internal html engine.

I liked the original setup of lhelp, no nonsense using an internal widget, I
heard Andrew is messing with an external browser backend, and I hope that is
only an option for extreme cases.

I don't think you can really instrument a browser perfectly in this, since
good instrumentation is a two-way street. (and browsers know nothing about
helpsystems). The fact that there is no single browser and no single way of
instrumentation to one aggrevates this. DCOM, COM, QT IPC all will require
libs to interface to Mozilla, Opera Konquerer etc.

Even if a good helpsystem ever arrives on Linux (which I seriously doubt
atm, unless freedesktop gets a whole lot stronger), I think the early steps
will be tiny, and horrible compromises, and it will be 4-5 years before
something usable is in every distribution.

It's a bit the same as why I don't like helpsystems to be plugin patchworks.
Somehow the interface is always the lowest common denomitor, and because the
plugin architecture is a weak compromise, the plugins are bad in quality and
never really fullfill the potential they could have had, even given the
limited (lowestcommon denomitor interface) border conditions.

Such architectures are purely compromises to avoid taking irreversable
decisions, but I think usually one gets in a situation where the dominant
plugin determines the interface, and the other plugins are stopgaps,
still resulting in effectively a monoculture, but one that has unnecessary
limitations forced on them for political reasons.

So we keep our own, and keep the documentation in a way that multiple
formats can be generated (which I admit is not the case for the latex docs),
and wait till there is really a suitable alternative.

It looks like that windows 7 will be chm as default most of its lifetime
(since even if htmlhelp3 emerges with a VS release this or next year, it
will require additional runtimes to be installed), so the only question is 
the helpfile situation on Apple (of which I directly admit not having a clue about)

But at least if something is possible there, and somebody is interesting in
writing the backends and the ide->helpsystem communication, there is a
possibility.

>  Why use two separate viewers to view the same CHM file format?

First, lhelp is not a viewer but a helpsystem backend. It would be called
"lview" otherwise ;-)

And why invent two wheels? A ferrari and a farmers cart should simply use the
same ? No, they are designed for totally different purposes, even though
they both have wheels.

The .INF duplication is actually worse than this, in that they are both
helpsystems, contrary to e.g. gnorpm or kchmviewer which are not.