In the meantime I added another feature to the FPDocManager, that shall allow to add description directories to documentation packages. The GUI is a bit rudimentary for now, deserves some improvements.

This feature can e.g. be used to add the descriptions in $Lazarus/docs/xml/fcl to the official FCL documentation. At least this part works already :-)

DoDi

Why are docs for fcl units in the Lazarus sources?

Mattias

I'm not sure. They may be a relict from attempts to document a few currently used units, using the FPDoc Editor. Since these docs don't meet the high standards of the official FCL docs, I never supplied them to FPC.

Some time ago I agreed to delete the xml/fcl folder, but perhaps others did contribute to them as well, and declined to remove it.

There exists one problem with local adds to the documentation: LazDE reformats the XML files in a way, that makes it almost impossible to create patches, or to merge them with new revisions of the original sources. Using the FPDoc Editor for updates (concurrently) can result in the same problems :-(

Recently another problem arose, when a FCL package was added to Lazarus, which does not reflect the FPC FCL.

After various attempts to fix errors and to extend the current documentation, I think that there exist reasons for maintaining additional documentation directories, which are *not* under version control - that's why I agreed to remove the fcl folder from the Lazarus repository. But it still should be possible to maintain local docs, unaffected by SVN updates, until we find an way to prevent conflicts or losses during SVN update.

DoDi

Hans-Peter Diettrich wrote

documentation, I think that there exist reasons for maintaining additional documentation directories, which are *not* under version control

I think you are approaching the problem from the wrong angle. Additional documentation should be the job of the Help Viewer (LHelp, DocView etc), not the documentation generator. Otherwise, you are forcing everybody to generate their own documentation, just to get their own personal notes included in the help. And every time you want to add a new note, you have no generate the docs again! :-(

I have lots and lots of "additional documentation" - extended notes, new code samples, simple inline comments etc. This is done via DocView's "annotations" feature. The annotations are added directly to the help topic I am viewing in DocView. Simply click where you want the annotation, click the annotation toolbar button and start typing. These personal notes are automatically stored external to the INF help file, in a <help_file_name>.notes file. As soon as I load a help file, DocView checks if there is a associated *.notes file, and loads that too. When viewing my help topics, those annotations appear inside my help topics. By default they are colored green, but this is user customizable. To edit/amend an annotation, simply click the green text and start typing.

See the screenshot of DocView showing some example annotations inline as green text. And yes, more than one annotation can be inserted into a single help topic.

http://fpgui.sourceforge.net/screenshots_apps.shtml

Graeme Geldenhuys wrote

Additional documentation should be the job of the Help Viewer (LHelp, DocView etc), not the documentation generator.

+1 !

OTOH, AFAI understand DocView is the only supported help viewer that can search across multiple files.

-Michael

An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120207/c1198ac7/attachment.html>

This may be a solution, but is not supported by current viewers nor FPDoc Editor or hints :-(

Otherwise, you are forcing everybody to generate their own documentation, just to get their own personal notes included in the help. And every time you want to add a new note, you have no generate the docs again! :-(

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

DoDi

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!

Hans-Peter Diettrich wrote

This may be a solution, but is not supported by current viewers nor FPDoc Editor or hints :-(

AFAIK, Graeme is about to do the last steps helping to make DocView a "supported" help viewer (i.e. providing an automated script (ow whatever) that allows a "normal" developer to create the necessary help files from the sources. An additional step might be to allow DocView to be selected as the internal Lazarus IDE help viewer instead of being installed as an external tool.

-Michael

+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

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.

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.

Who implements a f*cken decision?

Mattias

Graeme Geldenhuys wrote

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

Would DocView as a primary Help viewer be able to support Help hints in the current or an even better way ?

... extending the IDE to read those help files instead of parsing unoptimised XML files.

Are there decent chances to allow the users to select DocView as their primary help viewer in the IDE (rather than install it as an external tool) ?

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.

IMHO, forcing a decision is always bad, as long as there still are possibilities to allow for flexibility.

Why not extend the Tool interface (or derive an additional special "helpviewer" interface from same) and handle the help viewer as a selectable external Tool, similar to what can be done with DocView right now, but maybe a little bit better integrated. By this the "online help viewer" can still be selected and be improved as a separate project.

-Michael

Mattias Gaertner wrote

> * Wiki sites are NOT a solution for Context Sensitive Help. That's your opinion.

For me, Graeme's argument is very obviously correct.

-Michael

There are two options I could think of.

Most IDEs have a built-in help viewer, or sometimes an option to use an external help viewer.For the first option, there is normally a panel somewhere inside the IDE windows that display help. This could be done for Lazarus IDE too (in the long term) - compiling Docview or LHelp into the IDE. In the short term, an external help viewer like DocView or LHelp or whatever other help viewer could easily be controlled by the IDE using IPC, Pipes etc.

> ?* Wiki sites are NOT a solution for Context Sensitive Help. That's your opinion.

Read this mailing list. It seems to be the opinion of many others too.

Almost true. Some debian packages install help files.

IDE dialog window help?

About version: many developers wants only the newest documentation version while using older *and* newer Lazarus.

I use Lazarus 0.9.30.x simply because it is stable, and I work in a production environment. Currently those dialogs, menus etc are vastly different to Lazarus Trunk. The Wiki only caters for Lazarus Trunk. So the wiki help for my IDE dialog windows in v0.9.30.x is useless - or rather hard to find anything related.

The fpcdocs are separated from the fpc version too.

Sure, but there are downloadable help files for any previously released FPC version. They don't just cater for FPC Trunk.

is done in real time. Of course a full text search with ranking needs some more processing,

That's already implemented in DocView too, including various search term syntax (AND, OR etc). As for the speed of search, it's actually hard to measure in DocView, because search results are near instantly found. We are talking of <10ms searching across multiple help files. This is why I chose to go with the INF help format - it is super efficient.

Who implements a f*cken decision?

DocView and LHelp are already implemented! Though LHelp is a very rudimentary help viewer, so it would require lots more work. Porting DocView to the LCL widgetset is a breeze, because the UI and INF processing is clearly separated in code.

Michael Schnell wrote

Would DocView as a primary Help viewer be able to support Help hints in the current or an even ?better way ?

There are many ways to support code hints. VB6 used to have a small window below the Object Inspector. Other IDE's used a help panel. Some used a status bar. Some use a popup window etc.. You can embed the help viewer component (in the case of DocView, that would be the TRichView component) in any of them.

As I mentioned in my previous message, you could also allow the IDE to control an external viewer (which could take any shape or size) via IPC etc.

Are there decent chances to allow the users to select DocView as their primary help viewer in the IDE (rather than install it as an external tool) ?

There is nothing that needs to be changed in DocView as far as I know. No technical limitations. You simply need to create a Lazarus Package that registers DocView as a viewer, for what help context and format.

I used to do this, but it never worked well in Lazarus IDE. Did you see the recent comments in this mailing list about end-users that can't get the CHM viewer working? My point exactly! So using the External Tools method was fool proof, 15 seconds max to setup and doesn't require an IDE recompile.

Not making any decision is even worse! Also the problem is bigger than just the help viewer. The help format is another problem. End-users don't know where to contribute help too. Currently we have HTML, XML, Wiki, PDF etc. The help is scattered all over the place, and no specific versions are available for each Lazarus release.

Graeme Geldenhuys wrote

As I mentioned in my previous message, you could also allow the IDE to control an external viewer (which could take any shape or size) via IPC etc.

Displaying the hint Windows is one issue, another is managing the content. Of course the searchable content of the multiple help files is valid to be displayed, but currently the hint windows also display viable information derived from the source files of the project under development.

> Are there decent chances to allow the users to select DocView as their > primary help viewer in the IDE (rather than install it as an external tool)? There is nothing that needs to be changed in DocView as far as I know.

Yes: hint window handling: see above. Maybe more still to be detected.

Yep. Providing a dedicated "external help viewer" interface should be fool proof, does not need recompilation (even though I don't esteem this very important), and allows for multiple help online and offline viewers be separately managed and distributed projects (also possible with packages).

End-users don't know where to contribute help too.

Touche ! ;-)

-Michael

Graeme Geldenhuys wrote

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.

Are you saying that we should choose between chm and inf?

So currently the IDE help system is in shambles, and many tools have been duck-taped to do things they were not supposed to.

I just wanted to test your theory that the IDE help system is in shambles and I did a little google and found this link:

http://wiki.freepascal.org/Installing_Help_in_the_IDE#If_you_are_using_Lazarus_from_Subversion

So in 4 steps which took maybe 30 seconds I managed to add CHM help to my Lazarus SVN even while I knew almost nothing about this previously. The only problem I found is that LHelp takes so long to build the index when it is started.

Another flaw was that this link to the instructions was not present in the main help index of the Lazarus help. I will fix that.

I don't use releases, but I will also check if releases come with offline help out of them. If they don't yet come, they should come with it. With LHelp compiled already and with chm files together in the main Lazarus rpm/deb package.

Mattias Gaertner wrote

Why are docs for fcl units in the Lazarus sources?

I was curious to know if removing this would affect the docs building, so I just did a test:

cd lazarus/docs/html
rm -rf ../xml/fcl
rm -rf lcl/
./build_lcl_html.sh

And the build was identical with the same messages as with xml/fcl existed.

chm building also seams to go normally (although I don't have much experience with it).

So to me it looks clear that we should delete that folder. Anyone against?

How shall these viewers share content?

DoDi

Felipe Monteiro de Carvalho wrote

Are you saying that we should choose between chm and inf?

No, I'm saying: Make a decision - any decision!

Points to consider:

* Is offline help an option. If not - ignore everything I posted today
* What help viewer to use, or must a new one be created
* What features should the help viewer contain
- full text search
- various search syntax (OR, AND etc)
- highlighting of search terms in found help topics
- Index support
- Table of content support
- run-time concatenation of help files
- ability to search across multiple help files (RTL, FCL, LCL, packages etc)
- print support
- exporting of help topics to plain text or PDF
- Bookmarks
- user annotations
- viewer controllable via an external application (IPC etc)
* What help format to use for the IDE itself (dialogs, ide settings etc). This will also help for applications developed with Lazarus LCL.
* If a new (non-existent) help format is chosen, then tools like fpdoc should be modified to output the RTL, FCL etc class documentation to that format.
* What about the other FPC docs like the Language Reference.
* [important to some] Does the documentation look good in the help viewer. It is an insult to the help authors, if there hard works looks crap in the final
product.
* does the help viewer perform well. No point in having a sluggish help viewer that takes forever to load, or search or just even scroll long bodies of help
content.

I just wanted to test your theory that the IDE help system is in shambles and I did a little google and found this link:

Yeah, I believe those directions were fixed a few days ago - after the millionth Lazarus user couldn't get it working following the previous instructions.

But now those instructions probably don't apply to any previous released or current stable Lazarus release - thanks to the menu and dialog overhaul Lazarus had in Trunk.

Once again, the wiki only caters for Lazarus Trunk.

I don't use releases, but I will also check if releases come with offline help out of them.

I'll save you the trouble.... No they don't. No pre-compiled binaries of any help viewer and no offline help of any sorts.

> Why are docs for fcl units in the Lazarus sources? I was curious to know if removing this would affect the docs building,

It doesn't, because the fcl folder is not used in normal document builds. That's why I added a feature to FPDocManager, that allows to include such additional help sources.

Yes, of course, because you just built *LCL* help, not *FCL* help.

So to me it looks clear that we should delete that folder. Anyone against?

No objections here. I'll copy the content to a different location, and use it from there :-)

DoDi

Hans-Peter Diettrich wrote

I've no problems with the IDE help system, except for its setup.

So you can bookmark help topics, search for topics and annotate existing help? Umm, how did I miss that in Lazarus.

> ?* FPDoc Editor is NOT a help viewer. It should not be used or thought > of as such. I used it frequently, to fix errors or add missing facts to the docs :-)

Yes, after all, it is a XML documentation editor.

What's wrong with this approach? It shows (raw) help both from source code and the docs, and it's instantly up-to-date after any change to the docs or code. I like it :-)

I can't bookmark a frequently used topic, or add my own personal notes to that help and see it in the tooltip. As I mentioned before, I annotate existing documentation a lot. - my personal notes that mean a lot to me (and probably mean nothing to somebody else, so should belong in the official docs).

BTW, I'd *require* that every new feature in the Lazarus (IDE, LCL) code has to be documented, before it finds its way into the repository.

And here we come full circle! In which format should we document these features? XML, IPF, TXT, RTF, ODT, AsciiDoc, DocBook, Wiki etc....? And are these features related to the LCL framework, Lazarus IDE itself, or many of the utility apps included in the Lazarus repository - thus it might dictate which help format must be used.... class documentation or general application or README help.

LCL and LazUtils features need to be documented in 2 places:

1-> In the Wiki
2-> In the XML files in lazarus/docs/xml/lcl/

Example:

Wiki-> http://wiki.lazarus.freepascal.org/LCL_Accessibility XML-> http://svn.freepascal.org/cgi-bin/viewvc.cgi/trunk/docs/xml/lcl/controls.xml?view=markup&root=lazarus

And with links between them.

The help format for outputing the XML is irrelevant in this work. I generally test with html.

Hans-Peter Diettrich wrote

No objections here. I'll copy the content to a different location, and use it from there :-)

I killed it in rev 35233. You can copy from previous revisions.

Graeme Geldenhuys wrote

?* Is offline help an option. If not - ignore everything I posted today

It is mandatory, and surely a priority for 1.0 to fix this.

I'll save you the trouble.... No they don't. No pre-compiled binaries of any help viewer and no offline help of any sorts.

I just checked our RPM and unfortunately you are right! They don't include pre-compiled offline help =(

Anyone has an oppinion of the best way to fix this? I see 2 solutions:

1> Add chm building in the release build process for each platform (deb, rpm, windows, mac, etc)
or
2> Put some latest pre-compiled chm in our svn. They will be automatically put into the rpm/deb/etc because those include the Lazarus source.

1 is the more conventional solution. 2 is way, way, way less work =D

Hans-Peter Diettrich wrote

How shall these viewers share content?

I don't understand what you are asking.

- Only one viewer is installed at the time.
- Each viewer has it's own file format (online or offline)
- The different file formats are created by appropriate tools.
- There is a common code base, these tools read

Thus only user annotations are dedicated to the Viewer they are created with.

-Michael

Felipe Monteiro de Carvalho wrote

Anyone has an oppinion of the best way to fix this?

IMHO: (for 1.0, as this seems not like a trivial task):

- define and implement a help viewer interface (this might be based on the "external Tool" interface or on packets that need recompilation)
- provide a version of the online help viewer that adheres to this interface
- (if you think you must) provide a version of the CHM viewer that adheres to this interface
(the rest of my suggest is targeted towards Greame)
- provide a version of DocView that adheres to this interface
- provide a fool-proof way, usable by everybody, to create all inf files from the current sources

-Michael

No question: FPDoc.

DoDi

Michael Schnell wrote

?- define and implement a help viewer interface (this might be based on the "external Tool" interface or on packets that need recompilation)

This is probably already implemented. I followed the instructions in the wiki and click in synedit over TButton, press F1 and it opens TButton in LHelp.

Graeme Geldenhuys wrote

?* What help viewer to use, or must a new one be created

I am indiferent as to help formats per se, but I think we should distribute CHM+LHelp pre-compiled as default. It has problems, but those can be fixed and it is in the source tree of Lazarus, which makes it possible to build it as part of our build process and therefore to include it in our RPMs/DEBs. We cannot have a RPM nor DEB with a binary built from a source code from outside our source tree.

Of course that after that anyone can change his help to INF+DocView if he prefers it, it will simply be the default pre-installed in stable releases and snapshots.

Felipe Monteiro de Carvalho wrote

> ?* Is offline help an option. If not - ignore everything I posted today It is mandatory, and surely a priority for 1.0 to fix this.

So then your previous reply to me simply adds to the problem....suggesting that the wiki must be used for documentation. The wiki help content is locked in a wiki database nobody can access or export. It is also in a format nobody can read. And lastly NOT available offline.

So does that mean the Lazarus Team has finally made a decision on what help format and viewer to officially use with Lazarus? Thus using CHM help as the default help format for Lazarus IDE and Lazarus LCL, and LHelp as the viewer?

Maybe an official email stating that users should stop adding help to the Wiki and rather start editing the "raw" CHM help content. Sorry for my ignorance, but like you have *.tex files for LaTeX, xml for fpdoc, *.ipf for INF help.... what is the documentation source files for CHM?

Also what Linux/Windows/MacOSX CHM help source editors exist so the BIG port from Wiki-to-CHM can begin?

Graeme Geldenhuys wrote

Also what Linux/Windows/MacOSX CHM help source editors exist so the BIG port from Wiki-to-CHM can begin?

Would DocView be better on that behalf ?

-Michael

Felipe Monteiro de Carvalho wrote

This is probably already implemented. I followed the instructions in the wiki and click in synedit over TButton, press F1 and it opens TButton in LHelp.

I suppose no current IDE API handles the tooltip help, but maybe I am wrong.

-Michael

Felipe Monteiro de Carvalho wrote

I am indiferent as to help formats per se, but I think we should distribute CHM+LHelp pre-compiled as default. It has problems, but those can be fixed and it is in the source tree of Lazarus

Is DocView worse on that behalf ?

-Michael

Graeme Geldenhuys wrote

So does that mean the Lazarus Team has finally made a decision on what help format and viewer to officially use with Lazarus? Thus using CHM help as the default help format for Lazarus IDE and Lazarus LCL, and LHelp as the viewer?

That depends on what developers will say and if this idea will achieve a majority among core developers, but to me it looks a good path. Alternatives are welcome, but so far I don't see any alternative to put offline help in our RPM/DEB packages.

Maybe an official email stating that users should stop adding help to the Wiki

The wiki and the offline help complement themselves and should link to each other.

and rather start editing the "raw" CHM help content. Sorry for my ignorance, but like you have *.tex files for LaTeX, xml for fpdoc, *.ipf for INF help.... what is the documentation source files for CHM?

All of our offline help is in XML files for fpdoc.

To build CHM from them is trivial, just do this:

cd lazarus/docs/html
./build_chm.sh

Now build HTML offline help:

cd lazarus/docs/html
./build_lcl_html.sh

It would be great if someone contributes such a script which generates LCL help in INF format.

Michael Schnell wrote

> Also what Linux/Windows/MacOSX CHM help source editors exist so the BIG > port from Wiki-to-CHM can begin? Would DocView be better on that behalf ?

I already have a HTML-to-IPF converter. It's not perfect (HTML can be very sloppy), but it does save you a lot of time. I also have syntax highlighters for IPF files. I normally just use my IDE editor to write documentation, and again code templates to reduce typing, and a keyboard shortcut to an External Tools item that builds the INF file for me.

Felipe Monteiro de Carvalho wrote

That depends on what developers will say and if this idea will achieve a majority among core developers,

Well, could that be discussed between the core developers and a definite answer be given to us mere mortals. That would be nice to finally have an answer.

The wiki and the offline help complement themselves and should link to each other.

I think that is more "fragmentation of documentation", thus making in more difficult for somebody to search and fine help. The wiki is also not searchable offline, hense my suggestion to stop using the wiki, and make all those topics available in a offline format, and only use the offline format from then onwards.

All of our offline help is in XML files for fpdoc.

That is only class documentation! What about the IDE documentation, database documentation, tutorials etc. Do you not think it useful having those in a offline format?

That is the help for pascal sources. The IDE feeds the LCL help system and the chmhelppkg package has registered help for the LCL sources.

Last week I implemented a package (examples/idehelp/demoidehelp.lpk) to demonstrate the IDE's help system. At the moment it demonstrates help for messages, keywords, fpc directives, IDE directives and helpcontext properties. It does not yet have an example for context sensitive help for pascal sources.
The good news is that there is already an example for that: The package externhelp demonstrates how to get help for the windows unit, gtk2 and postgresql.

There are also examples how to register viewers: one that uses a LCL form and one that simply opens a browser.

Of course there is still plenty to do before all the available help work out of the box. There is progress.

Mattias

Mattias Gaertner wrote

There are also examples how to register viewers...

This does sound promising :)

-Michael

DocView is not part of Lazarus source code. Also it would first need to be converted to LCL (though according to Graeme this should be rather easy).

Regards,
Sven

Graeme Geldenhuys wrote

hense my suggestion to stop using the wiki, and make all those topics available in a offline format, and only use the offline format from then onwards.

While converting Wiki content to some help format seems quite impossible, automatically creating Wiki pages from the help sources seem like doable.

-Michael

Then please enlight us how you'd document e.g. this http://wiki.lazarus.freepascal.org/IDE_Window:_Call_Stack in FPDoc.

Not every feature is about source code. In this thread we're also talking about IDE help (e.g. about its windows and its features) and not the features of the underlying code.

Regards,
Sven

I understand that Graeme would be able (and willing) do make a DocView Packet. Another way would be using (an advanced version of) the "external Tool" interface. This already does work nice for DocView.

-Michael

You can register help viewers since many years. The default handles mime type html and simply opens a browser. The package chmhelppkg registers lhelp.

Mattias

The thread subject is "Extending FCL documentation". Please start another thread if you want to talk about something different.

Mattias

That might be, but Felipe is talking about the default for Lazarus. That is what everyone is complaining about: there is no default offline help available after installation.

Regards,
Sven

It was not me who started to talk about IDE windows and such ;)

Regards,
Sven

Sven Barth wrote

, but Felipe is talking about the default for Lazarus.

Yep. The Default supposedly should be a Packet.

-Michael

He does not need much LCL. He just needs to write an IDE package that starts and communicates with DocView. The chmhelppkg starts lhelp as external tool and communicates via SimpleIPC.

I understand that Graeme would be able (and willing) do make a DocView Packet. Another way would be using (an advanced version of) the "external Tool" interface. This already does work nice for DocView.

The external tool is not very context sensitive. For example you can not get help for a dialog.
And it's rather crude for pascal sources. An external tool can use macros to get current source editor filename, line and column. On the other hand the IDE's help interface for pascal sources uses the codetools to find the declaration and passes a complete path to the help. For example the external tool only gets "LoadFromFile", while a registered help gets fpc sources, rtl/objpas/classes.pp, class TStrings, method LoadFromFile.
There is a base class for fpdoc help formats in ideintf helpfpdoc.pas, demonstrating how to convert this information to the fpdoc element path. The only thing you have to do is to find the corresponding element in DocView.

Mattias

Graeme Geldenhuys wrote

That is only class documentation! What about the IDE documentation, database documentation, tutorials etc. Do you not think it useful having those in a offline format?

For that we would need to implement a software to convert the wiki format into FPDoc XML and then integrate that with the rest of the help. It is a doable project, certainly useful, but not a priority for me at the moment.

My answer was based on the assumption that Michael asked why DocView can not be the default instead of lhelp.

Regards,
Sven

Graeme Geldenhuys wrote

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

+10000000000000000~

i have /YET/ to find or use a wiki that makes any sense, is easily searchable, or has a decent index like a book... to me a wiki is nothing more than a pile of postit notes arranged in some random order... this is akin to using something like wordpress as a whole website and pressing it into duties it was not designed for...

Felipe Monteiro de Carvalho wrote

I just wanted to test your theory that the IDE help system is in shambles and I did a little google and found this link:

fail :(

pretend that uncle google simple doesn't exist... better yet, perform the same feat on a machine that is completely offline ;)

waldo kitty wrote

fail :(

What failed?

pretend that uncle google simple doesn't exist...

In latest svn IDE click in the menu Help->Online Help and it will open a local html file which has a link to that page.

better yet, perform the same feat on a machine that is completely offline ;)

In this case he would not be able to download the chm files anyway. Note that configuring is for Lazarus svn users. For release users everything should come pre-installed and pre-configured (not the current situation of course).

It could be easier to use the HTML representation, and allow to integrate that in e.g. CHM files. I see no real reason for forcing content, that is unrelated to source code, into FPDoc XML format - see the FPC documentation (ref, user...), whose sources AFAIK are LaTeX.

DoDi

That might be, but Felipe is talking about the default for Lazarus. That is what everyone is complaining about: there is no default offline help available after installation.

Q: offline Help, or offline Documentation?

Delphi came with PDF files for those who want documentation, and these docs are well prepared for *reading*, not for use as context sensitive help. IMO we should make the same distinction, between help and docs.

DoDi

Not every feature is about source code. In this thread we're also talking about IDE help (e.g. about its windows and its features) and not the features of the underlying code.

See my note on the difference between context sensitive help and (offline) documentation.

It might help to start an new thread, that addresses documentation in general, not only context sensitive help (on the FCL).

DoDi

to me a wiki is nothing more than a pile of postit notes arranged in some random order...

Even worse: you don't have access to all those notes, instead there sits a dumb secretary in between, that will or will not find what you're looking for :-(

DoDi

i, personally, see them as the same... documentation will explain how to use something and provide examples... the help will give examples as well as explaining how to use... seems the same to me...

Delphi came with PDF files for those who want documentation, and these docs are well prepared for *reading*, not for use as context sensitive help. IMO we should make the same distinction, between help and docs.

i have yet to be able to take a PDF to the "library" and be able to read it comfortably, easily and without having to haul other equipment in to access it...

Hans-Peter Diettrich wrote

Even worse: you don't have access to all those notes, instead there sits a dumb secretary in between, that will or will not find what you're looking for :-(

If you use google as your secretary it will always find what you need. Try in google:

lazarus wiki graphics

and see what comes

... then you have to be ONLINE :-(

What's the effort to create an offline equivalent of Google, for indexing - uhm - files not available while offline?

DoDi

ummm... in my old TP/BP 6/7 i hit F1 (cursor on an empty place) and get a window (edit window) that pops up where i can choose from numerous links...

compile
run
close
open

then further down there is

using turbo pascal windows
using the editor
find dialog box (text search)
replace dialog
edit menu
file|save command
file|save as command
"block read" (^KR) dialog box
"block write" (^KW) dialog box

all of these are related to how to use the ide and have nothing to do with examples of source code... if i press SHIFT-F1, i get a beautiful index like one would find at the back of a book and that leads me to all kinds of everything... ide assistance, code assistance, compiler defines assistance, turbo vision stuff, etc... if i place my cursor on a language related word and hit CTRL-F1, then i'm taken to a section specific to that word... i would expect the same in today's *RADEs when one has their cursor on a library routine included with the *RADE...

so i don't see any real difference... hitting F1 should offer help for everything related to the IDE, to the language, and to the library routines that are available...

*RADE == Rapid Application Development Environment

Hans-Peter Diettrich wrote

No question: FPDoc.

Huh?

fpdoc (included with FPC) is for Class Documentation only - source code. FPDoc Editor (included with Lazarus IDE) is meant to edit the XML you feed to fpdoc.

Documentation for an application like the Lazarus IDE's various dialogs, or the Accounting package you wrote with Lazarus etc is NOT class documentation. So you can't use fpdoc, thus you need a different help format when it comes to application help.

So when you say that the developers must use FPDoc Editor when they want to document a new dialog they added to the IDE makes no sense!

Felipe Monteiro de Carvalho wrote

On Wed, Feb 8, 2012 at 7:42 PM, waldo kitty wrote: > fail :( What failed?

ok... let's start again...

while we're in town or over at a friend's place, we download the archive and save it to a disk... now we go to our special place miles and miles away from every where... we take that disk to our machine that is permanently disconnected from the rest of the world... we install the archive to this machine... now tell us how we're going to figure out anything about enabling the help system...

IMHO, even coming from the SVN stuff, there should be a default setting for the help files which should also come from the SVN... one package, one pull... everything goes "here" and is operational right out of the box... no matter what that box's shape is (eg: tarball, install binary, SVN, GIT, etc)...

> pretend that uncle google simple doesn't exist... In latest svn IDE click in the menu Help->Online Help and it will open a local html file which has a link to that page.

we're NOT connected to any network and/or have NO way to access the internet from this particular machine... so still stuck with no help at all...

really? i ran into it the first time i attempted to try FPC and Lazarus... i still don't have help working in a pure FPC environment but that belongs elsewhere, i suppose...

For release users everything should come pre-installed and pre-configured (not the current situation of course).

and this is what some of us have been trying to point out... that being that it should have been seen and handled years ago... i'm still so raw in this environment that while i do want to contribute, i can't even find the beginning of the string to start pulling on to see where the unravel takes place :(

Excellent extension on the analogy! and perfectly fitting, as well...

Rubbish! Waldo is spot-on. My internet at home is wireless, very expensive and I only have a small data bundle per month. So I download things from work, put in on a USB stick and take it home. I can do that for INF, CHM etc help. But I CAN'T do it for the IDE (wiki only) help. So when I am at home (offline) and I don't understand a setting in some IDE dialog, I'm stuck. At least I have offline help for the FPC Language Reference, RTL, FCL though - thanks to the files I downloaded from work.

Note that configuring is for Lazarus svn users.

What is that supposed to mean?

Hans-Peter Diettrich wrote

See my note on the difference between context sensitive help and (offline) documentation.

"context sensitive help" relates to application help too, not just source code / framework help.

In our fpGUI based software from work, and most Windows software, if you are in a edit field in some dialog in your application, and you press F1, you get show the help for that edit field. This is know as "context sensitive help" too! Now if that specific edit field doesn't help it's own help, then normally it defaults to the current dialog (as a whole) help.

[on a side note]
Now GTK or Qt Linux applications on the other hand absolutely suck at context sensitive help. Normally they don't have any help, or they default to the help start page of the whole application. Then it's the users job to browse through the help looking for the information on a specific edit field in a specific dialog. Useless! [sometimes I even wonder why I bother using Linux]

Now from my little experience on Mac OS X, it is nearly as bad as Linux apps. Also Mac apps think you have a permanent internet connection, because most offline help is just skeleton help. You need internet access to get the full help. Again, pointless! [end]

Hans-Peter Diettrich wrote

Delphi came with PDF files for those who want documentation, and these docs are well prepared for *reading*, not for use as context sensitive help. IMO we should make the same distinction, between help and docs.

Why? I have a few OS/2 products from IBM (VisualAge, DB/2 etc). They all include about 3-5kg of books or "documentation" in the box (yes, they are truly huge and heavy). But those exact books are available via INF too - using the exact formatting (but with faster search, cross linking etc).

So no, Help and Documentation could very well be the same think. Just use the right format for the job.

BC3.1 also came with 1m of printed docs, later on it was left to the user to print whatever docs he wanted to have, or to buy the books at extra cost.

So no, Help and Documentation could very well be the same think. Just use the right format for the job.

You confuse the structure (and content) of documentation with the file type. When you write a book, you can store it in Word, HTML, PDF or whatever format you like. But such a book will hardly be usable for context sensitive help. Likewise you can merge all help topics into one document, but I'd not call the result a "book".

DoDi

It's the job of the archive creators, to add the installation procedures to their packages. You may end up in a number of package versions, one for every single platform. You also may end up in Lazarus packages with and without local help included, with and without FPC (RTL/FCL...) help, to please users with narrow bandwith.

I agree that configuring the help system has to be described in local documents or help topics, which are readily accessible *before* the help system has been configured. Such configuration has to be done manually for all additional Lazarus installations.

DoDi

waldo kitty wrote

i, personally, see them as the same...

+1

At a final stage (in a perfect world), all PDF-documentation and offline help, offline help, and great part of the Wiki pages, should be generated from the same sources. Otherwise maintaining this stuff is a nightmare.

-Michael

Sounds good. I really look forward to Greame's decision (not wanting to push him, but.... :) )

-Michael

[...]

all of these are related to how to use the ide and have nothing to do with examples of source code...

Right. The IDE has to find the help topics for the current IDE element, while the editor windows have to find help for the current identifier or keyword. This difference is reflected in the XML sources, where <element> refers to an identifier in source code, and <topic> for other descriptions. Unfortunately the IDE can decide to link to the wiki, which is available only when online - this is what many users dislike.

if i press SHIFT-F1, i get a beautiful index like one would find at the back of a book and that leads me to all kinds of everything... ide assistance, code assistance, compiler defines assistance, turbo vision stuff, etc...

Right, all that *can* be provided in a help system. It's a matter of organization and contribution and, finally, of the help viewer to provide a map (TOC) and an index.

In short: context sensitive help describes all *obvious* items, be identifiers or keywords in source code, or IDE menu entries or dialogs. Everything else is subject to the expectations and needs of the users, with *no predefined* (class, menu...) structure and content.

IMO documentation should transport know-how, starting with "Why should I use Lazarus?", down to more and more specialized topics. All these articles should be well structured and easily readable and understandable, not interrupted by technical details.

Everybody can write such articles, e.g. in the Wiki, but unfortunately this does not mean that such information can be *found* by other users. So we have to add (selected) contributions to the help system, and make them findable by e.g. links, keywords or topic lists. There exists no automatism that could do that automatically. Tags are not really helpful, because every contributor can have a different opinion about useful keywords, and a full-text search is typically too unspecific and contains too much unrelated "noise".

IMO we need a documentation structure in the first place, from which it becomes more obvious which topics should be added (overviews, how-to's...). Then we can start to fill that skeleton with topics like you mentioned before.

DoDi

Right, it's up to the GUI designer to add the proper HelpContext(sic!) to every GUI element, so that F1 can *find* the related information. It's also up to the designer to *provide* that information. All that for *every* application, not only for the IDE.

Now from my little experience on Mac OS X, it is nearly as bad as Linux apps. Also Mac apps think you have a permanent internet connection, because most offline help is just skeleton help. You need internet access to get the full help. Again, pointless!

There exist pros and cons. Internet based help is always up-to-date, no need to update a local help base every now and then, and it allows for immediate feedback to the content providers - what does not mean that this chance is really taken by the maintainers ;-)

It's a cumbersome feedback procedure, when every user has to file an bug report on missing or insufficient help items or documentation. With a chance that such a request is delayed until some future version, because the according guru is busy with more interesting invention of new features :-(

Currently I can imagine only one way, to raise the chances for documentation improvement: the responsible developer should be blamed in every place in the documentation, where he is the only person that can provide better content. And these blames should not be simply removable, as happened in the past. Remains the problem of telling the name of the responsible, which has to be left to the Lazarus team; in a company the QC staff would do that, but we don't have such a powerful institution yet :-(

DoDi

Of course you can :-)

Looks like you didn't notice the <topic> feature of FPDoc?

DoDi

Not at all.

When you write a book, you can store it in Word, HTML, PDF or whatever format you like. But such a book will hardly be usable for context sensitive help. Likewise you can merge all help topics into one document, but I'd not call the result a "book".

And this is where you are wrong. INF can serve both purposes without problems (hence the reason I chose it for fpGUI). I reviewed a lot of help file / ebook-type formats before I settled on INF.

OS/2 had two "help file" formats. They are actually exactly the same format but with different file extensions and one bit field that toggles between them. HLP vs INF. The only real difference is that they signal the help viewer how to display them. If it is a HLP file (normally used as application help), the help viewer was 25% of the screen width. When it is a INF file, the help viewer took up 80% of the screen width.

Also, I have numerous books (yes, with chapters etc) and magazines published by companies (eg: IBM, Speedsoft etc) or organizations in INF format too. INF was probably the first "ebook" format around - at least long before ePub and Mobi. OS/2 even had a "Help Library" folder, which contained lots of INF books.

This is why I say INF is truly flexible. It can be a book when needed, a replacement for text files (eg: readme.txt etc), but it can also be used as application help in software.

There exist good and bad books. It's primarily a matter of content, how useful a book is - you cannot really improve the quality of a digital book by visual effects.

DoDi

Hans-Peter Diettrich wrote

Of course you can :-) Looks like you didn't notice the <topic> feature of FPDoc?

Yes I know about "additional topics" in fpdoc. I have used fpdoc for many many years. :) I have also used that feature on occasions, but it doesn't come close to what you need for context sensitive application help.

http://fpgui.sourceforge.net/apidocs/additionaltopics.html

Also, fpdoc requires source code to function. So why would you want to fiddle with source code files, when you are creating application help, which some accountant might read when he struggles with your accounting package.

Again, you are trying to squeeze fpdoc into a feature-set it was NOT designed or intended for.

Hans-Peter Diettrich wrote

findable by e.g. links, keywords or topic lists. There exists no automatism that could do that automatically. Tags are not really helpful, because every contributor can have a different opinion about useful keywords,

You raise a good point - and another reason for one of DocView's many features. I have found too often INF files where the Index specified by the help author was not very good. They seem to do the Index as a "last resort - time permitting". This is why DocView can auto-generate a Index, or it can use the built-in Index of the INF file, or it can merge both. This behaviour is all configurable by the end-user in the DocView Options dialog.

This gives the end-user the best chance to find something helpful from the Index page.

and a full-text search is typically too unspecific and contains too much unrelated "noise".

DocView has a search result rating system built-in, to try and eliminate such "noise". And if the full-text search doesn't work, you can always switch to the Index tab.

Again, you are trying to squeeze fpdoc into a feature-set it was NOT designed or intended for.

I'll stop trying to educate you.

DoDi

Hans-Peter Diettrich wrote

I'll stop trying to educate you.

And the same to you.

G.