I don't think the existing documentation stresses the point enough that if you use individual TRadioButtons you won't be able to use ItemIndex to find out which one is checked. Creating a TRadioGroup as a container then adding TRadioButtons to it does nothing useful, ItemIndex is always -1. Change Parent doesn't seem to fix it. It seems like that worked in Delphi, I rarely used string lists.

To use ItemIndex you have to populate the TRadioGroup using strings. I haven't found out yet whether the strings can be changed under program control, but I was building a context-sensitive menu, planning on changing the captions on the buttons to suit the context

New to the list, I've got a resume at
http://devio.us/~ab1jx/files/resume.pdf I used mostly Delphi 3 from when it first fascinated me about 1998 through the end of my last job in 2009. Turbo Pascal before that, VAX and Apple II Pascal before that. Used to tinker with Oberon Native. I spend most of my time in OpenBSD lately so I've been writing C for the last 6-7 years. Delphi was the thing I missed most about Windows.

Alan

On 4/8/16, Alan Corey wrote:

. Creating a TRadioGroup as

This is as it has always been, and as it was even in the Delphi 3 days. Use the component in the way it is designed to work. Why you would even drop individual radiobuttons on a TRadioGroup is beyond me.

Bart

Bart wrote

This is as it has always been, and as it was even in the Delphi 3 days. Use the component in the way it is designed to work. Why you would even drop individual radiobuttons on a TRadioGroup is beyond me.

To be fair, a TGroupBox gets things dropped in it, and both nomenclature and look/feel are similar. It also feels like every few years I make the same mistake Alan has and groan :-)

But yes, design from prehistory - certainly don't need changing.

Mike
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20160408/58a885f0/attachment.html>

Michael Thompson wrote

To be fair, a TGroupBox gets things dropped in it, and both nomenclature and look/feel are similar.

I fully agree. As far as I can remember, even in my Delphi days I've made that mistake of dropping radiobutton controls on a TRadioGroup. Bart, it's not as obvious as you think. It's learning by error, and then getting used to that fact.

Regards,
- Graeme -

Or maybe read the documentation ? At least in the case of early Delphis that would have helped. (can't comment on current Lazarus)

Thinking that you start without reading any form of documentation is an attitude which I highly condemn.

Unfortunately, this attitude seems typical for IT.

If NASA or Airbus or Boeing engineers would use that approach, I guess a lot of rockets, planes and whatnot would fall on our heads.

I am glad they do not seem to have this attitude.

Even cars come with a manual: usually located in the glove box, because your average citizen manages to open that without "Quick start guide".

Michael.

Michael Van Canneyt wrote

Or maybe read the documentation ? At least in the case of early Delphis that would have helped. (can't comment on current Lazarus)

Yep, before the days of Internet, when I bought my copy of Delphi2, It had a manual.
And even the I bought books on Pascal and Dephi and pressed F1 very often (Delphi in those days had a very good help file).

(My initial TP 3.0 only came with a reader in Hebrew, which wasn't very helpfull since I'm Dutch)

But even if you don't read a manual or something like that, and just play with the component, after just a few minutes you must have seen the Items property, played with it and see what it does?

Bart

Bart

J?rgen Hestermann wrote

When asking for documentation here I am often answered: Check the code.

Yep. Correct. If you think the documentation is bad, check the code and write it. Alan, you are welcome to modify the domunentation in the LCL and send a patch. You can also freely update the wiki docs. There's no problem about it and you don't have to ask for permission.

Ondrej

Or the person reading the code with the intend of documentation, is more clever than this. They could report any suspicious parts, and clarify the intend. That way the code would be additionally be checked for bugs.

Bugs where the original implementer may have had a wrong understanding of what he was doing. In which case had the original coder documented it, the bug would have gone into docs.

Assuming the original coder is available for comment, then a person different from that coder can often write much better documentation. (simple because then 2 (or more) people will have though about what it should be)

This doesn't apply to Alan's problem. We try to document important things. It's not our problem that "it is not enough stressed that functionality XYZ is not available on ZYX". We really don't have crystal balls to know what people may think is not enough stressed.

Ondrej

That's a bad idea :-)

Sure, *some* programmers make good documenteers, but in my experience they're the exception, not the rule. My own documentation skills suck. Essentially, if you think like me you'll have no problems. I'm very bad at seeing the problem from other people's perspective. And I'm too old to change now. I'm at the "shout louder if they didn't understand the first time" stage of life.

I do agree though, we're open source. We should all pull our own weight and not expect others to pick up our own slack. It's only in a corporate environment that I'd insist on professionals doing the documentation.

Mike
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20160409/2d3a0f2b/attachment-0001.html>

Yes and I am answering to you in general: we do our best providing documentation. If you think we are not good enough, participate in writing documentation. What is the problem?

Ondrej

J?rgen Hestermann wrote

But in the same way as others complain here about lack of coders I am complaining about the lack of documentation.

Feel free to reduce this lack of documentation.

Ondrej

If everybody shared your approach, there wouldn't be anything like FPC and Lazarus. You should change your way of thinking.

Ondrej

Michael Van Canneyt wrote

Thinking that you start without reading any form of documentation is an attitude which I highly condemn.

I would love to read documentations but very often there is none (or even worse it is wrong, outdated, confusing and incomplete). When asking for documentation here I am often answered: Check the code.

Unfortunately, this attitude seems typical for IT.

It has evolved into this.
When I started with Turbo Pascal very excellent documentation was wide spread. Today with fast version cycling it seems that nobody has the time for it anymore or (even worse) not even has the knowledge about how things exactly behave. So we are all left to use trial and error which is realy sad.

If NASA or Airbus or Boeing engineers would use that approach, I guess a lot of rockets, planes and whatnot would fall on our heads. I am glad they do not seem to have this attitude.

I am not sure that they do not have it.
I saw a report on TV about a test flight of the A380 some years ago where technicians were wondering, why the air craft computer was pumping fuel from one tank to the other in a certain flight situation. It seemed they needed a lot of time to find it out. I would have expected that the complexity was not driven to a point where even the engineers do not fully understand what they have built. Could be that we just had a lot of luck.

Bart wrote

But even if you don't read a manual or something like that, and just play with the component, after just a few minutes you must have seen the Items property, played with it and see what it does?

But then you only *think* you know how it works.
It maybe that some conditions exist, when things behave different. You would never know about them if you have not read it somewhere. It could be that you just wonder why things *sometimes* crash (or whatever).

Ondrej Pokorny wrote

On 08.04.2016 18:56, J?rgen Hestermann wrote: > When asking for documentation here I am often answered: Check the code. Yep. Correct. If you think the documentation is bad, check the code and write it. Alan, you are welcome to modify the domunentation in the LCL and send a patch. You can also freely update the wiki docs. There's no problem about it and you don't have to ask for permission.

That's a bad idea.
The person who wrote the code is the only person who knows what he intended. This person has to write the documentation.

Not only that it would take a lot of (unneccessary) additional time to wade through foreign code (while the original coder already knew this after writing it). Also, every bug would become part of the documentation as it is "how it is coded".

Michael Thompson wrote

I do agree though, we're open source. We should all pull our own weight and not expect others to pick up our own slack. It's only in a corporate environment that I'd insist on professionals doing the documentation.

Well, of course, nobody can be forced to do anything in open source projects. The same applies to coding:
If nobody is willing (or not has the skills) to code for an open source project then it is as it is.

But in the same way as others complain here about lack of coders I am complaining about the lack of documentation.
And IMO all discussions about what should be coded should also end in the question: And who will document it?
Code without documentation is a pain.
Documentation saves a lot more time than it cost to write it.

Ondrej Pokorny wrote

This doesn't apply to Alan's problem. We try to document important things. It's not our problem that "it is not enough stressed that functionality XYZ is not available on ZYX". We really don't have crystal balls to know what people may think is not enough stressed.

I was answering to your statement: "If you think the documentation is bad, check the code and write it." which was an answer to me writing: "When asking for documentation here I am often answered: Check the code." I thought this was in general (at least my statements were).

If I could only.
It would take me months to understand all the code where the documentation is missing/wrong.

Ondrej Pokorny wrote

If everybody shared your approach, there wouldn't be anything like FPC and Lazarus. You should change your way of thinking.

You mean I should ignore facts?

Exactly.

Martin Frb wrote

Or the person reading the code with the intend of documentation, is more clever than this. They could report any suspicious parts, and clarify the intend. That way the code would be additionally be checked for bugs. Bugs where the original implementer may have had a wrong understanding of what he was doing. In which case had the original coder documented it, the bug would have gone into docs. Assuming the original coder is available for comment, then a person different from that coder can often write much better documentation. (simple because then 2 (or more) people will have though about what it should be)

I aggree that this can happen.
But it requires that the reader has at least the same skills regarding the topic of what has been coded.
How long do you think would it take to (fully) understand the code for VirtualTreeView? I have already found bugs in it but never understood why they occur because I do not understand how the whole unit is coded. So how should I even write documentation for it?

I have maintained SynEdit for nearly a decade now. Yet there is code in SynEdit I never looked at, and consequently I have not understood yet. According to you, it is a good thing I have not tried to add any docs. (Actually I should delete the parts I added to the wiki)

On the other hand according to me, anyone could have investigated a single property, or method. To do so would not require an understanding of everything. Yet that person could have documented the one method/property.
If so then at least some parts would have docs.

On VirtualTreeView: I dont know if the Author is around, and if he could/would answer questions, or even proof read contributed docs. But if he was, then the question "How long do you think would it take to (fully) understand" is just the wrong question. The question should be: how much time do you have? Is there a chance, that in that time you can document at least one property or method? If yes, well then start. If you get more done (now or later), then even better.

The problem is, everyone (including me) is very good at pointing out why someone else should do it. And everyone just keeps pointing out it needs to be done.
Well that is fine. Lobbying for a cause is great. But the expectations in that case must be set correct. Someone else may also have a reason not to do it.

Il 08/04/2016 18:56, J?rgen Hestermann ha scritto:

This is more about *reading* the documentation, or maybe to *understanding* it, which is the subsequent step, once a decent documentation is available.

As the complexity increases, you cannot fit in the same page all the relevant information, and you must rely on reader's capability of understanding that what is stated at page 10 may carry implications to what is stated on page 900. This holds true for Airbus or Boeing, and for Lazarus and FPC.

I'm not an expert in avionics, but from my general knowledge even I could have told them the reason for pumping fuel from one tank to another, which is to balance the weight on the wings (fuel tanks are located on the wings). This function must be handled by some part of software related to the aircraft flight attitude most likely fully documented, but completely apart from the section which takes care of pumping fuel to motors!

A very similar case occurred with one of the first Airbus of Lufthansa. At landing it didn't stop at the end of the runway, and ended up in a cabbage field.
The subsequent investigation revealed that:

* The Airbus had a protection preventing the reverse thrust if the landing gear isn't touching the ground. Reverse thrust was enabled only when all the wheels touch the ground.
* Lufthansa procedure, in case of crosswind, is the sideslip landing, meaning the right (or left) wheels of the landing gear will touch ground much later.
* As a consequence, in case of strong crosswind, reverse thrust was enabled too late.

It would appear that someone was unable to detect the problem generated by two fully documented facts, until an aircraft ended up in a cabbage field.

This sort of things do happen even when documentation is good, so let's imagine what may happen if documentation is poor or missing!

Giuliano

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20160409/c1a5126a/attachment.html>

J?rgen Hestermann wrote

Do not implement any new features until all existing features are documented!

Agree.

What? How's that going to work? I prefer my open source projects alive and kicking :-(

I'm not interested in theoretical "wouldn't it be nice". I agree that it would be nice if we have documentation, and I like putting a plan in place to forward this. But the proposal above is insane. If it's serious, please provide an actual concrete plan with 100% documented success rate to magically transform programmers into motivated documenters.

Mike
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20160409/9f739ba3/attachment.html>

Giuliano Colla wrote

I'm not an expert in avionics, but from my general knowledge even I could have told them the reason for pumping fuel from one tank to another, which is to balance the weight on the wings (fuel tanks are located on the wings). This function must be handled by some part of software related to the aircraft flight attitude most likely fully documented, but completely apart from the section which takes care of pumping fuel to motors!

Of course they knew that the general purpose of pumping aroung the fuel was for balancing reasons. They only did not understand why it was done *in the current situation*. They did not expect that it happened at that time. I do not know whether they understood it in the end but I thought it should have been clear and understandable immediately.

It depends on nothing. Stopping all forward movement as a tactic to improve documentation will kill the project.

Please listen. I agree that documentation should be improved, and I agree that we should be planning for it. We're on the same page there.

But that particular plan? Stop all development until *ALL* features documented? Shows no understanding of developers! It will kill the project.

How much history in the code? How many undocumented features?

All I'm suggesting is we focus on sane proposals that will produce tangible, positive results.

Mike
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20160409/ae2f5611/attachment.html>

Martin Frb wrote

On VirtualTreeView: I dont know if the Author is around, and if he could/would answer questions, or even proof read contributed docs. But if he was, then the question "How long do you think would it take to (fully) understand" is just the wrong question. The question should be: how much time do you have? Is there a chance, that in that time you can document at least one property or method? If yes, well then start. If you get more done (now or later), then even better.

Okay.
Then please find the bug that you cannot collapse/expand nodes with the mouse if the main column is not the most left one. Moving this column to the left (even at runtime) makes it working again. And please: No excuse that you have no time or such! ;-)

And believe me, I have already spend a lot of time on reading the code of the VirtualTreeView unit (and many other units too) but it is impossible to dig that deep into each to fully understand them. I cannot do the documentation for every single function and concept in Free Pascal/Lazarus. Is that a reason that I am not allowed to complain about missing documentation?

The problem is, everyone (including me) is very good at pointing out why someone else should do it. And everyone just keeps pointing out it needs to be done. Well that is fine. Lobbying for a cause is great. But the expectations in that case must be set correct. Someone else may also have a reason not to do it.

I don't think that this is my attitude.
I just see it is a waste of time if someone is forced to read and understand code that someone else has written (thereby (mis-)interpreting things that the original coder already knew) while the person who originaly wrote the code was already at that step. Freshly after writing the code he could have written the documentation much easier.

I know, many (most) programmers do not like writing documentations. But leaving it to others is just that attitude that I am blamed for here.

What I would vote for is:
Do not implement any new features until all existing features are documented!

J?rgen Hestermann wrote

I just see it is a waste of time if someone is forced to read and understand code that someone else has written ...

Nobody forces you read or understand code!
I think you should find another project if this is not good enough for you. I don't even suggest that you contribute something yourself because I know it will not happen. I have seen this mentality before. You will find excuses to blame Lazarus developers indefinitely, and find other excuses why you cannot contribute yourself.
Go away troll please!

What I would vote for is: Do not implement any new features until all existing features are documented!

Fortunately you don't have voting power here. This is not a democracy. This is meritocracy.
If your kind of people had true voting power, this project would be dead already.

Juha

Michael Thompson wrote

What? How's that going to work? I prefer my open source projects alive and kicking :-( I'm not interested in theoretical "wouldn't it be nice". I agree that it would be nice if we have documentation, and I like putting a plan in place to forward this. But the proposal above is insane.

It highly depends:

If you think that open source projects are *exclusivley* for those people who contribute on it and who are so involved that they don't need any documentation because they already know everything and have the time to keep track on all changes then, yes, there is no need for documentation.

But if you want to attract a wider audience of people who just use it then documentation is essential.
Otherwise you have to answer the same questions here over and over again (or ignore them and let people use other, better documented tools for programming).

I've just spent some time researching a problem that someone posed on the forum. I'm reminded of how powerful open source is. I had no idea how to answer the question. The wiki, the forum and even Mantis provided a veritable wealth of information before I got to even looking at code documentation.

Mike
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20160409/1afe59c9/attachment.html>

Absolutely off topic, what is the point off that?

Proving that docs can be useful? No need, no one ever said that they were not. This mail is not about what you can or can not do with docs, but who can contribute to them.
Fixing a bug, will not contribute a single word to documentation. (a bug fixer may choose to add doc in addition to the fix, but that is unrelated to the fix.

No one said you have to document ALL of them, start with just one. That was the big point of my last mail. If you ignore that then there was no point in any indeed you studied that much, and can not yet specify for one single function what it does, then that is really just unlucky. That said, I do not claim that the docs you may be able to add at that point, are of any help to your current problem, they may document functions you are not interested in, but that would still be documentation.

Worst case you could add docs that leaves certain questions open, and document only what you were able to find (advertising that they miss out some effects.) this would still be something the next person could build on.

Hi J?rgen,

Hmm, try putting out proposal like this on lkml...

On a more serious note:

Unless what you're doing with Open Source/Free Software is fairly trivial, and a general-purpose solution exists that fits your needs, then you don't really need to contribute to anything, because the problem has already been solved.
You can use binary stable releases and be the happy receiver at the end of the chain. You can settle on just configuring it, writing a script or two in $favorite_scripting_language sometimes, etc.

A programmer/developer of anything based on Open Source solutions, isn't ANYTHING of the above, IMO.

People involved, whether only as users, or as contributors, in projects based on c-like languages of similar size to FPC/Lazarus, they ALL DO THAT. Go read some lkml or kernel-newbies for examples how a MUCH LARGER community handles this...
(Luckily FPC and Lazarus aren't so big that a fpc/lazarus -newbies mailing list would be needed...)

Coders choose to code and do minimal documentation (e.g. comments), others choose to document what the coders wrote. That creates movement and discussion, helps coders correct themselves if need be, keeps the project alive. But it needs input and contribution.

And (Object) Pascal is infinitely MORE readable than any c-like lang. We should be able to do the same so much easier, just by 's facts, as I see them.

-L.