[Lazarus] Lazarus IDE help and Application help formats

Graeme Geldenhuys graemeg at opensoft.homeip.net
Mon Aug 17 14:31:29 CEST 2009


Mattias Gärtner wrote:
> 
> It's not sufficient to only have help files. The important piece is
> to find and present the help. Just take a look at the mails. We have
>  thousands of help pages and still people say we have no usable help.

I would say the biggest problem is because the help is only available 
online. If Lazarus includes off-line help by default, and they click 
"help" or F1 inside the IDE dialogs, then at least you will see something.

If I work from home, I am not online. Hence, I have no IDE help. At 
least I download the FPC html help, so I can view that.


> When someone needs help at a certain place, then a F1 should open the
>  help for that - context sensitive help. For example when a user is
> in the compiler options dialog, a F1 should tell the help viewer to

This is exactly what I want to address. Currently Lazarus doesn't have 
off-line help, and doesn't provide a help system for developers own 
programs.

> open the help for the 'compiler options dialog'. That's what I mean
> with support for "keywords" and "remote control". The online help


fpdoc has keyword support and the new versions generate index pages. The 
"custom help viewer" that we right can work like 'lhelp'. Index, keyword 
and Search tabs on the left side and a HTML viewer component on the 
right side. Maybe we can even modify 'lhelp' to suite our needs.

As for context sensitive help. I think a HTML page can still be used, as 
long as the page has anchor tags included. That way you can tell the 
HTML viewer component to open the following urls in various situations.

Help button in Compiler Options dialog
   help://docs/compiler_options.html

or Compiler Options diaglog and Linking tab active
    help://docs/compiler_options.html#linking
   or
    help://docs/compiler_options_linking.html

or Smart Link checkbox is focused and user presses F1
   help://docs/compiler_options_linking.html#smartlink


It obviously depends on how we want to split the help of tab based 
dialogs. Each tab has it's own html page or the whole dialog has one 
html page, with many anchor sections we can jump to.



> No. Where is the search field? Who produces the html from the doc
> files?

The same design as 'lhelp' or any other CHM help viewer. Index, keyword 
and Search tabs on the left and HTML viewer component on the right.

We can look at fpdoc code for how indexes and keywords are generated. We 
can even use grep (like 'find in files' dialog) or regex unit - all 
included with FPC or Lazarus already.


For the help viewer we can opt for the following:
1) Use the AsciiDoc (*.txt) files as-is, and render them as HTML
    in-memory only when needed (viewed by user). That we nobody
    needs to pre-compile and package the help.

2) Pre-compile the AsciiDoc to HTML and package it in a ZIP archive.
    Make that available for download. Help viewer can now display the
    help as-is.


Option 1:
---------
pros:
  - Help will be instantly available - no extra work required by the
    user.
  - Help would be more up-to-date even for users getting Lazarus from
    SVN or Git repositories.
  - Also because the AsciiDoc doesn't really have much markup in them,
    we can grep / regex those files as-is for keyword searches.

cons:
  - In memory rendering to HTML, so initial load might be slower, but
    honestly I don't think this will really be an issue.
  - It might be easier to work with the row *.txt help if they are not
    in a single ZIP archive. Then again TZipFile allows standard file
    handling routines with files inside an archive, so this might not
    even be a problem.


Option 2:
---------
pros:
  - Loading might be a bit quicker compared in in-memory rendering to
    HTML format.
  - A single ZIP archive might be easier to use.

cons:
  - More work is required because help needs to be compiled first.
  - Help needs to be re-compiled after every help patch is applied.



I think option 1 is the best option. Similar in fashion as what Lazarus 
can read fpdoc xml directly without first having to pre-compile the 
help. Not to mention, it is much less effort.


Regards,
   - Graeme -


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





More information about the Lazarus mailing list