> I think the docs are OK, because its not a "learn basic in 21 days"
> book, but a reference.
That's true, but it should be good enough, hat if you are used to programming, it tells you the basic things, so you don't have to look
into a Forum to get started.
It should be more clear in some Points for example:
#Hello = 10 is a constant.
now, for the Librarys like Gadget, it says in the Command Syntax:
Frame3DGadget(#Gadget, x, y, Width, Heigth, Text$, Flags)
This really confused me for the first time (and others, too), becourse if it says #something is a constant, then #Gadget has to be one too.
What I want to say, is there is a section called ' Words used in this manual' under 'General Syntax Rules'. Maybe something like that should be mentioned there. Or even creating an own 'About this Manual' section would be good to start.
Another Important thing, that is really confusing:
WindowID() returns the ID (Windows uses) for a #Window
EventWindowID() returns #Window
Both are called ID! Now if the Manual talks about ID's, which one is meant? - Another thing that should be more clear.
Another thing is, that we've found a lot of stuff here at the Forum, where somebody said: 'wow, this should be really mentioned in the docs.'
For a lot of commands, the docs say, what it does in general, but (as you said) it doesn't tell about the results, or other important things about the command.
For example MessageRequester: what does it return, if you presed
OK, or Chancel if you specify #PB_MessageRequester_YesNoCancel?
- You have to find out yourself
Or EventType():
The Docs don't say exactly where to use it. So people try to use it to detect for example a Rightmouseclick anywhere in the Window. But this isn't possible. The Docs should say something like: 'EventType() only shows what Type of Event happened on a Gadget, it can not catch events on the Window's background.'
It's those missing little additions, that make users wasting time on debuggig things that are not meant to work that way.
I'm not talking about 'learning Pb in 21 days' here, i'm talking about 'not confusing people comming from a programmig background' !!
The Docs are quite OK, they just lack those little things.
Hope this clears up my point a bit...
Timo
--------------------------------
Programming today is a race between software engineers striving to build bigger and
better idiot-proof programs and the universe trying to produce bigger and better idiots.
...So far, the universe is winning.
