Hi, (mostly for Michael I guess)

I've been spending some time to renew my familiarity with the IDE and FV, to do some minimal maintenance and fix some of the "old" bugreports.

As by-product of this work, I thought to do some minimal documentation (wiki), and maybe update the objects/fv/ide classchart.(since I need that for myself anyway)

The latter is the easiest question: is classchart.ps still the source of the pdf classchart ? If so, what do the modifiers "ready","untested" etc mean? Maybe their meaning should be annotated in the source?

The second is a bit harder,

I tried to run makeskel over the fv/ directory to try to generate some skeleton docs to have on the side, but it seems it fails on half of the files (next to empty XML). I first thought it didn't support the TP object model, but some classes are done.

Before I start debugging, does sb know what that could be?

Grtz

Marco

Not currently.
Someone else generates the pdf classchart from a OpenOffice spreadsheet.

If so, what do the modifiers "ready","untested" etc mean? Maybe their meaning should be annotated in the source?

They could, but it would be better to remove the alltogether.

In general, the idea is to create the classchart from within fpdoc. The idea is to create an XML file that simply has the structure of the class tree:
<TObject unit="system">
<TPersistent unit="classes">
<TComponent>
...
</TComponent>
</TPersisent>
</TObject>

Should be easy to do. then a tool can be used which converts this tree to PostScript or PDF or whatever...

Not without the failure message...

Michael.

And where is that one? Couldn't find it in svn.

Yes, an abstract format. However you might get into problems with dividing it up to nicely fill a page that way.

The idea is to create an XML file that simply has the structure of the class tree:

Why XML? It is so human-unreadable, and more a machine format than an editable one? I like the current ps format much more. OTOH the editor would be a simple treeview mostly.

Should be easy to do. then a tool can be used which converts this tree to PostScript or PDF or whatever...

See above.

There was none. It just generated an empty xml for e.g. Views.

It isn't. I get the ready made PDF :-)

I know.

XML because it can be easily manipulated.

> Should be easy to do. then a tool can be used which converts this > tree to PostScript or PDF or whatever... See above.

Yes, but postscript is impossible to maintain automated. Hence the inbetween-format.

Simple:

read(4, ">>>>>>>>>>>>>>>>>>>>>>>>>}\n\n{==="..., 256) = 256 access("Platform.inc", F_OK) = -1 ENOENT (No such file or directory) write(3, "<?xml version=\"1.0\" encoding=\"IS"..., 118) = 118

Change to platform.inc and it works fine.

Michael.

In our previous episode, Michael Van Canneyt said:

Hmm, that is not an healthy situation.

(that also has advantages btw, in a previous job I could print A2 (single sheet sideways into an A3 printer), and being able to solve this could be nice)

I suggest for now to at least maintain the classchart.ps, simply because the format can easily used as reference for whatever follows.

Yes, but what you save on the manipulation, you lose on the editing, making it nearly mandatory to make and support a gui tool. IMHO for small data amounts like this it is not worth it :-)

Do you have enough info to generate this from sources, and e.g. tell TP, Delphi and interface hierarchies apart? Then we only need to add a treeview to the gui doc tool so we can add properties there?

We then have to define a handy set of properties to control formatting, but probably we need to see the raw output for that first then.

Solved thanks. Got an awful deja vu feeling there.

I know.

Yes, but then you'll have A LOT of work, because the .ps is heavily outdated :(

Small data amounts ? Have you ever counted the number of classes ? :-)

I have enough info, yes. What is needed still is the ability to merge 2 trees.

We then have to define a handy set of properties to control formatting, but probably we need to see the raw output for that first then.

Yes.

I had the same thought :-)

Michael.

In our previous episode, Michael Van Canneyt said:

Well, if the opposite is entering the PDF's entry manually....

216 in the IDE only. That's a rough count using

egrep -i "=[ ]?object[ ]?\(" *

There might be a few duplicates due to ifdef declaration (e.g. for TV2.0 outline support).

It is probably easy to make a postprocessor for the egrep output that constructs a tree and writes .ps format. It can even comment the unit names if needed.

I'll see if I can hack something up, since I need something printable NOW.

Ah, objects. OK. Because for classes the numbers are discouraging:

- 100 classes in RTL
- 1267 in packages
- 573 in compiler
- 3660 in Lazarus

:-)

I'm curious :-)

Michael.

In our previous episode, Michael Van Canneyt said:

It's still an automated method. Ok, the grep will take half a minute instead of 2 seconds.

So that is not the problem, the problem could be conflicting names and duplicate declarations under ifdef.

Also if object() syntax is used for classes, you need to also grep for object().

If they are a few, that is not a problem, and you can toy with it.

It's simple tree building; below is the rough script + data I made this afternoon:

http://www.stack.nl/~marcov/classchartstuff.zip

ide.txt,fv.txt,rtl.txt are the outputs of the grep (with another filter to filter out svn dirs). Also I removed a few OS/2 only objects from rtl.txt

These files are catted together (see shellscript) and passed through the +/- 150 line fpc filter script.

The result is output.txt which has first some warnings, and then the rough .ps output.

To use classes you need to fix the egrep and the split function in the filter program. That split function is too simplistic and unsafe anyway, something you'll hit for sure with larger bodies of code. (e.g. comments after the class declarations, stuff like

x = class (thespaceafterhis ) // xx

will go wrong, but that is trivially fixed. Unitnames are stored though, since it was both easy, and makes manually fixing the warnings easier.

Note that this is a quick'ndirty script solution. I still think the long run fpdoc based solution is way better, reliable and maintainable. (and deals with the ifdef problem, and can provide a classchart with links etc)

But this could be done quickly in +/- 2 hrs.

Michael Van Canneyt wrote

Someone else generates the pdf classchart from a OpenOffice spreadsheet.

Would it not be appropriate to base a help system (for the RTL functions) on something like "DelphiCodeToDoc" and do an automation for the process ?

With this the Lazarus hopefully could display a decent context sensitive help and use the same help generation scheme for the LCL.

-Michael

Zitat von Michael Schnell :

Lazarus context sensitive help shows documentation of the fpdoc files and comments from pasdoc (similar to javadoc, DelphiCodeToDoc) and it browses through the class hierarchy to show ancestor help. The help content can be edited in the IDE context sensitive or via lazde and Kirk is doing a great job here.

The html content like formatting and links is currently only shown on the html pages or the chm help files. I already started a html viewer using tpipro for the IDE. This should show the formatting and hyper links.

The information for the class chart can be easily extracted via lazarus and codetools in seconds. If someone provides a tool to browse a class chart of thousands of classes, I can help you getting the data. Of course for fpdoc as command line utility independent of lazarus something else is needed.

Mattias

Sounds good. But nonetheless whenever I talk to a Lazarus newbie he says is learning curve is bad because of the much little information is and the bad usability of the help system. I recommend installing the free Turbo Delphi start it, type a code word in it's Editor Window and press F1. With this they in fact do learn to use Lazarus, while they would give up otherwise.

In the German Lazarus forum there recently has been a discussion on improving the (German) help. There had been a suggestion to use a Wiki to update / enhance the help texts. But an automated system to update the online help files would be needed to make this useful. (Moreover the usability (e.g the "context-sensitivity") of the Lazarus help system needs a great improvement, but this of course has to be discussed elsewhere).

-Michael

In our previous episode, Michael Schnell said:

Personally I despise wiki'ed manuals. They are horrible quality, over-hyperlinked beasts of ugly. I always get the feeling that those "everybody hacks away online" manuals are more obsessed with the process than with the result.

To avoid the chaos of too many cooks spoiling the broth, but still have finely grained user input in the docs, FPC at one point tried an annotate system (people being able to annotate problems in the FPC docs on a per page basis in wiki style), however it was plagued with technical problems, and never caught on.

I still like the principle though. It is still visible on the FPC docs page (the "with comments" option)

I still like the principle though.

I do understand this.

But especially with the non-English versions it would be nice to make the update of the help texts as easy as possible to enable the casual volunteer to get involved.

-Michael

... And is probably quite out of date.

Michael.

I fully agree. Wiki for manuals on online help just doesn't work. Links could be broken very easily and the help is stuck in a single format and no good for offline usage.

Why not simply build a option in the HTML generated by fpdoc, so users can click on a link at the bottom of the page or even better, next to each paragraph (something like [edit] in wiki pages), which then emails the documentation maintainers (customisable option) with the comment/fix/suggestion for that documentation paragraph. The doc maintainers can then update the fpdoc (source) documentation. I believe the MSDN help has such a feature as well.

Regards,
- Graeme -

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

Zitat von Michael Schnell :

Do you mean the fact that an external browser is started or the fpdoc html pages or the wiki pages?
The search functions are bad in all three of them.

I recommend installing the free Turbo Delphi start it, type a code word in it's Editor Window and press F1. With this they in fact do learn to use Lazarus, while they would give up otherwise.

Yes, Delphi had always a very good help with lots of examples.

Writing a good help is a lot of work.
FPC and Lazarus have more than 200.000 identifiers in more than 1000 units.

In the German Lazarus forum there recently has been a discussion on improving the (German) help. There had been a suggestion to use a Wiki to update / enhance the help texts.

The online help already uses the wiki for the IDE windows and dialogs. You are all welcome to help improve the pages with examples that newbies understand. For me as developer many things are obvious and so I often can't imagine the problems of newbies. That's why we need the help of users - hint, hint.

For the source documentation fpdoc is used and the fpdoc editor is one click away. So every user can edit the help ad hoc. The only problem is to create a patch and send it. Maybe someone can write a gui tool for creating patches to make this easier.
A wiki for the source documentation is a bad idea, because of the update/rename/delete issues.

Some docs needs improvements:
- the fpc keywords like 'procedure' (they are described in latex documents)
- fpc messages (too short and no links to related information)
- translations
- the bigger picture (tutorials and books)

What 'context-sensitivity' needs improvement? F1 is context sensitive.

Mattias

As an alternative to the "email link" I mentioned earlier (which I still think is the better option), the is also LUFDOC. You generate you documentation HTML with fpdoc. Run the LUFDOC parser (which is very quick) over the HTML which then modifies the HTML to include the LUFDOC comments. The fpdoc HTML can be re-generated at any time because the LUFDOC user comments are stored separately to the original fpdoc HTML - the parser merges to two. The CGI web app simply allows a mechanism to edit the user comments section, but a standard IDE plug-in or GUI app could also be written to do this job.

BTW:
LUFDOC = Live User Fed Documentation.

It's create by the Powtils (CGI framework) author.

For more information on this see the following link. http://z505.com/cgi-bin/mse/idx.cgi?file=fpdocintegrated

Regards,
- Graeme -

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

Do you mean the fact that an external browser is started or the fpdoc html pages or the wiki pages? The search functions are bad in all three of them.

I did not want to start a long winded discussion here :( IMHO the context-sensitive online-help (in Lazarus) is simply not usable (while the context-sensitive help in (also free of charge) Turbo-Delphi is not perfect but a lot better).
- You should get a decent result when hitting F1 on any keyword (of the language, the RTL or the LCL: language-keyword, type, class, function, procedure, property, public variable, variable, ...)
- there should be examples for the use of the topic
- there should be cross references to related and to similar topics
- ... :)

With Lazarus it would be best if the Delphi help could be linked in by the users (of course it can't be shipped :) ). This could be used as a nice starter and everybody can obtain it legally with Turbo Delphi, unless he is a legal Delphi owner anyway.

The online help already uses the wiki for the IDE windows and dialogs. You are all welcome to help improve the pages with examples that newbies understand.

If this is not included in the context-sensitive online-help this is no fun at all ;) .

Yep. Does the system support multiple languages ?

A wiki for the source documentation is a bad idea, because of the update/rename/delete issues.

Seems like you are right here. But regarding the translations this might be not as critical as with the original text.

What 'context-sensitivity' needs improvement? F1 is context sensitive.

Right, but in many (or most) cases it does not work. It seems (much more than the Delphi help) to try to prevent offering a topic that is not the correct one, so it seems to analyze the context of the word under the cursor. That means it only works if the source code already is quite correct (which the user often only can do after reading the help, so we have a deadlock, so that is a very bad idea, IMHO).

In Delphi I simply type a word (i.e. "TForm") in an empty line and press F1 to get help on TForm. This is the usual way I learn about new components I'd like to use. This does not seem to work for me in Lazarus.

-Michael

In Delphi I simply type a word (i.e. "TForm") in an empty line and press F1 to get help on TForm. This is the usual way I learn about new components I'd like to use. This does not seem to work for me in Lazarus.

This works perfectly for me in Lazarus. Perhaps I missed something but unless you mean "offline help" or "out of context help" (e.g: trying to get help on TForm without using unit Forms with proper paths set) then it works 100% in lazarus (you get browser opened with given topic in online help as target).

Perhaps your help/browser is misconfigured? See help/configure help.

-Michael

Ales

Which reminds me of another bug in Lazarus.

Change the Lazarus IDE default language to German. Restart the IDE. Now open the Compiler options and click the 'Hilfe' (help) button. The English help is displayed and not the German wiki help.

http://wiki.lazarus.freepascal.org/index.php/IDE_Window:_Project_Options

instead of the German...

http://wiki.lazarus.freepascal.org/index.php/IDE_Window:_Project_Options/de

PS:
I have no idea how you would test if the translated (non-english) version exists in the wiki or not.

Regards,
- Graeme -

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

That's exactly what the community thing already does.

Michael.

Zitat von Michael Schnell :

Yes, noted. But some points you mentioned I don't understand. So I wonder if you spotted a bug.

Yes. As I said: pascal keywords are a problem because they are only in latex docs.

- there should be examples for the use of the topic

There are already some examples in the docs. So the system is there and _only_ needs to be filled.

- there should be cross references to related and to similar topics

For example the LCL docs already have 485 links to related topics. Not counting the automatic and ancestor links. Again: system is there and _only_ needs to be be filled.

Maybe doable. Needs investigation.

Huh? I'm only talking about the context sensitive online help. The F1 function of lazarus.
Maybe you are talking about fpide?

> For the source documentation fpdoc is used and the fpdoc editor is one > click away. So every user can edit the help ad hoc. The only problem is to

create

> a patch and send it. Maybe someone can write a gui tool for creating patches > to make this easier. > Yep. Does the system support multiple languages ?

Some parts yes. AFAIK fpdoc has, the wiki too. But the context sensitive help of the IDE does not yet support that. The problem with the wiki is that the IDE does not know, if a page has already a translation. The problem with fpdoc is my free time.

I typed TForm, pressed F1 and got:

http://lazarus-ccr.sourceforge.net/docs/lcl/forms/tform.html

The help for identifiers only works, if the IDE can find the declaration. It does not yet search in the registered classes, nor in the whole documentation.
If you want help for an identifier without proper declaration, then you want a context *insensitive* search and as I said: this is missing.

Mattias

Zitat von Graeme Geldenhuys :

Yes, that's why and we don't know how up2date they are.

Mattias

This works perfectly for me in Lazarus. Perhaps I missed something but unless you mean "offline help"

NO I did test "offline help" by d/lding the help file and setting the path to same. This of course is no difference to the online version (if the internet connection works).

Hmm..... I don't think so.

Wen I do a test application and press F1 o TForm in the line TForm1=class(TForm) I do get a help screen

But when I type TForm in some empty line (e.g. outside of any procedures) I get "no help found for"....

So I do need to know where something is allowed to be typed before I get any help on it. :(

-Michael

Yes, noted. But some points you mentioned I don't understand. So I wonder if you spotted a bug.

See my other message in this thread about "context" on what I thing that might not work as designed.

So an _easy_ way to have the users provide examples might be helpful.

Right ! see above

Another goody would be that the decent Delphi 3rd party packets come in sorcecode and with help files that can be linked in the Delphi help system. Using this would greatly help (legal owners) porting such packets to Lazarus

No.

This is exactly what had been discussed in the German Lazarus Forum. Enhancing the German F1 help.

The problem with fpdoc is my free time.

This of course is the problem with all community projects. But better slow than never :)

I (maybe) see. So "context" does not only mean "word under cursor", but in fact it evaluates the context of same (the Delphi help does not seem to do that.)
But why not enhance the "context" help in a way that it offers a lost of available topics with that keyword if no topic that fits the "context" is found (or if the user requests a list <e.g. by Shift-F1> ).

-Michael

Zitat von Michael Schnell :

TForm is out of context, so the context sensitive help does not find TForm.

So I do need to know where something is allowed to be typed before I get any help on it. :(

You want to search context insensitive.
Me2.

Mattias

Zitat von Michael Schnell :

Well, it is not a one click action, but it is not difficult neither: Create the example, save it under docs/xml/lcl/unitname/something.pas and set the filename in the fpdoc editor.
For instance the example of TRadioGroup points to extctrls/radiogroup.pas.

I have no information about the Delphi help system and how to use it platform independent. Maybe you can provide some links?

[...] This is exactly what had been discussed in the German Lazarus Forum. Enhancing the German F1 help.

Can you give me the link to the thread?

[...] I (maybe) see. So "context" does not only mean "word under cursor", but in fact it evaluates the context of same (the Delphi help does not seem to do that.)

Yes. This way the help does not only show help for the identifier itself, but for every ancestor. For example the help for TMyFormDescendant automatically shows the help for TForm. And it shows comments as well.

But why not enhance the "context" help in a way that it offers a lost of available topics with that keyword if no topic that fits the "context" is found (or if the user requests a list <e.g. by Shift-F1> ).

Time. I first worked on the tools to create help content. The next steps are to improve the presentation and context insensitive search functions.

Mattias

have no information about the Delphi help system and how to use it platform independent. Maybe you can provide some links?

Sorry I don't have any experience in _making_ a third party Delphi help, but many of my colleagues do _use_ third party Delphi help file for the packets we bought.

But as these things do exist I suppose there is some freely available instruction on how to create them.

Can you give me the link to the thread?

http://www.lazarusforum.de/viewtopic.php?t=1919&start=15

Time.

:)

I first worked on the tools to create help content. The next steps are to improve the presentation and context insensitive search functions.

Great ! Thanks for your good work !

-Michael