[Lazarus] New Help System & Viewer - sneak preview

[Graeme Geldenhuys]

2009/10/1 Marco van de Voort <marcov at stack.nl>:
>
> 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?

  $ make rtl.chk fcl.chk

This generates the HTML output.  Not what I want.


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

> - how links over module bounderies work,

Explain "module"?


> - do you support legacy "id" based numeric keys?

Yes, text and numeric keys are supported.


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


> - How is the fulltext search organized? Does it add up with multiple files?

See previous answer. Yes.


> - Does you system need write access (e.g. for cache files)?

No cached files are required, so no write access needed to view help.
The only time the help viewer writes to the disk is when you added
custom user Notes to the help topics while viewing the help, or adding
Bookmarks. Those notes and bookmarks will be stored in the users
AppData (writeable) location. So you can view help directly from a
CD-ROM and still see your Notes or Bookmarks with the help.


> - 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'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.
Format of loading multiple files as a single "virtual bookshelf" is as
follows

   $ helpviewer <file-1>+<file-2>+...+<file-n>

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:

Contents
  + Free Pascal Language Guide
  + FCL documetation
  + RTL documentation
  + LCL documentation



> - Can you create combined TOCs?

Yes, see previous answer.


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


> - Can you pack arbitrary HTML into a file?

I don't see the use of this. Can you explain why you would want too?
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. 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.


> 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. Microsoft just took the quick route in slapping them into
a single archive and call it a new help format. 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.


-- 
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/