[Lazarus] Extending FCL documentation

[Graeme Geldenhuys]

On 7 February 2012 19:48, Hans-Peter Diettrich wrote:
>
> This may be a solution, but is not supported by current viewers nor FPDoc
> Editor or hints :-(

I'll blame the Lazarus developers for that. See below...


> Usually I'm happy when I get immediate descriptions in the FPDoc Editor or
> hints. But searching the help or overviews etc. require viewers with
> additional information (indices...).

This comes down to the Lazarus Core team that don't have the balls to
actually make a decision on what help format the IDE should use. So
currently the IDE help system is in shambles, and many tools have been
duck-taped to do things they were not supposed to.

 * FPDoc Editor is NOT a help viewer. It should not be used or thought
of as such.
 * Help hints over source code, are read directly from the XML files.
This is simply
   done because NO HELP SYSTEM IS IN PLACE. Yet another duck-tape solution.
 * Wiki sites are NOT a solution for Context Sensitive Help.
 * Wiki sites should NOT be the only help for a offline product.
   - Currently you are forced to always be online, otherwise you get
no IDE help.
   - There are no IDE help files per Lazarus release. You cannot tell
the wiki site to
     export the IDE help for Lazarus v0.9.30 for example.
   - The help generated on the wiki site is locked in a format nobody
can access, other
     than via a web browser.
 * No searching, No Indexing, No Bookmarks and No Annotations are supported
   because of all of the above items.

Suggesting that the FPDoc Editor must now support user annotations, or
that fpdoc must be extended to support user annotations are rubbish.
Those are all band-aids masking the real problem. Fix the actual
problem - Lazarus lacking any offline help system! Then you have a
something to build on, like extending the help viewer to support basic
help functions, extending the IDE to read those help files instead of
parsing unoptimised XML files.

Like I displayed numerous times, DocView already does a crap load
regarding help. It's very fast, very flexible, customizable and
supports a lot of end-user desired features. If the issue with DocView
is that it is based on fpGUI, then I welcome you to simply fork
DocView, and port the UI to LCL - trust me, that is the easy part of
DocView!

The bottom line is, the Lazarus Core team needs to grow a pair and
make a decision for their project, and decide what help system and
offline help viewer they want to use. Avoiding the problem, like they
have been doing for over 10 years, just makes it worse and worse the
longer it is left undecided.

And don't get me wrong, I don't care which way they decide, DocView,
LHelp or create something else. Just make a f*cken decision for the
sake of the Lazarus community!

-- 
Regards,
  - Graeme -


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