[Lazarus] Extending FCL documentation

[Mattias Gaertner]

On Wed, 8 Feb 2012 10:01:20 +0200
Graeme Geldenhuys <graemeg.lists at gmail.com> wrote:

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

+1

>  * Help hints over source code, are read directly from the XML files.

... and from source comments and using all the project and package
information.


> This is simply
>    done because NO HELP SYSTEM IS IN PLACE. Yet another duck-tape solution.

How does DocView provide hint windows?


>  * Wiki sites are NOT a solution for Context Sensitive Help.

That's your opinion.


>  * Wiki sites should NOT be the only help for a offline product.

+1

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

Almost true. Some debian packages install help files. 
About version: many developers wants only the newest documentation
version while using older *and* newer Lazarus. The fpcdocs are
separated from the fpc version too.
So even when the next release will ship some help files there must be
the possibility to use the newest version.


>    - The help generated on the wiki site is locked in a format nobody
> can access, other
>      than via a web browser.

Not entirely true. AFAIK practically you are right.


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

The fpdoc files are about 10MB. You don't need much optimization to
search that. I have some xml projects with more than 100MB and search
is done in real time. Of course a full text search with ranking needs
some more processing, but as long as we are talking about 10MB I see
no big problem.

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

Who implements a f*cken decision?

Mattias