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/
--
_______________________________________________
Lazarus mailing list
[email protected]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
