[Lazarus] New Help System & Viewer - sneak preview

[Marco van de Voort]

On Thu, Oct 01, 2009 at 01:19:58PM +0200, Graeme Geldenhuys wrote:
> > Do you have an overview of what works and what not, and practical aspects of
> > the system?
> 
> How do I generate the FCL and RTL documentation in INF (actually IPF) format?

You tell me! I'm not the IPF expert. I assumed you had found some way to
export one of the existing formats to it.
 
> > - what the "key" is, that identifies a topic
> 
> Similar to HTML. The H<n> tags.  You can then specify document wide
> which H<n> tags should appear in the Table of Content. You can also
> explicitly hide any topic from the TOC.

Actually, on CHM it is external. One can try to get them from the content,
but there are separate tables. The stuff about toc and index below seems to
indicate that it is so there either.
 
> > - how links over module bounderies work,
> 
> Explain "module"?

Bundles of help generated separately from eachother.

> > - How are the index and toc organized? Do they support multiple entries per
> > ??key? Can an (index) search return multiple entries?
> 
> See my first answer. Yes and Yes. The Index is based a lot on the
> information from the TOC data structure. Also if you do not explicitly
> specify index key words, it's not the end of the world either. The INF
> file format stores a dictionary of ALL unique words and symbols. So a
> search will work on all content. The actual help
> contents/topics/articles data structure are simply pointers to the
> dictionary. This is VERY efficient and very fast!

This is roughly how CHM works too, but the efficient versions of certain
parts are not implemented yet. Fulltext search is fine and efficient, except
for the generation (LCL takes 4 minutes to generate)

TOC is binary since weeks, and the binary (B+Tree) index is half
finishes.

> > - What is the time to load the LCL index file and merge it with the FCL and
> > ?? RTL files?
> 
> I have loaded 10+ help files (totalling about 9000+ help pages), all
> over 2MB in size each. Loading time was instant.

(I assume that means with index, search and TOC combination)

> I'm waiting on
> instructions on how to generate alternative output formats of the FCL
> and RTL documentation, so I can do actual tests with those help files.

There are none.

> The Table of Content is then a concatenation of all the files
> individual TOC's. The TOC items will appear in the order of how the
> files where specified. So based on this, it will probably be a good
> idea to structure the FPC and Lazarus help with one top level TOC item
> (name of the document) and then the general TOC one level down. That
> should give you a "global" TOC looking as follows:

CHM also allows to have a "toplevel" CHM that overrides the TOC and Index
for the "slave" CHMs. 
 
> > - Are big tocs loadable in stages?
> 
> No need, the load time is instant. The storage structure of INF is
> very efficient, and are only a few bytes to extract. Good [efficient]
> programming from the 80's and 90's! Something that is lacking hugely
> in today's software.

So is CHM.

> > - Can you pack arbitrary HTML into a file?
> 
> I don't see the use of this. Can you explain why you would want too?

You already encountered that. There only is HTML of ref,user etc. (there
might be others, but other converters might be an adventure. And after that 
with fixing HTML layout, I don't want to ever go there again) 

> The INF has a very easy to learn mark-up language (48 tags to be
> exact) - similar to HTML and XML tags so should be easy to learn.

And nobody knows them. And no system outputs them. 

> I will probably be extending these as the need arises. Also a front-end
> GUI for writing documentation might be nice. Alternatively, a IPF
> pre-processor could be written (similar to fpdoc now), taking one format
> and generating IPF output.

fpdoc has a logical structure. Most html has only a markup related
structure.

> > Note that my CHM experience have made me doubt "generalized" systems of
> > help a bit (multi format ones) like the current textmode IDE and the
> > Lazarus IDE. As always with general systems, you get only the lowest
> > common denomitor.
> 
> I've always said it, and I'll say it again. HTML was NOT design as a
> help medium.

It was meant for hyperlinked text. I don't see why it can't be html.

> Microsoft just took the quick route in slapping them into
> a single archive and call it a new help format.

Then obviously you have not studied CHM thoroughly, since all features you
name are supported by CHM.

> Also note, that yes the FP Text IDE help code was an inspiration to me,
> but I did *not* follow that design. The help viewer I am writing can only
> view OS/2 INF & HLP files (both are actually identical formats except for
> 1 bit flag change). In the future it should probably be able to view the
> original OS/2 help formats and the newer hybrid help format. I am not
> guaranteeing backward compatibility with OS/2 at all - it is simply a
> launching point.

I'm thinking about changing the Text IDE to CHM only in time. But not yet
for the upcoming release. Not all features are already realised in our own
CHM support (even though CHM generally supports it). Andrew is getting close
though.