PureBasic Docs - Errors & needed improvements to the man

Andre · **Posted:** Mon Aug 31, 2009 11:52 am

I decided to post our internal "To Do" list related to the manual, so everyone is aware what's already noted and is able to add suggestions.
As well Fred, freak and I are able to make (public) statements about "what's done"... :wink:

But important! It would be very helpful, if larger discussions about suggestions are avoided. I know this already from german forum, when the topics are becoming too long... :twisted:

I will review the following list from time to time, and added new requested suggestion or marked topics with "[Done]".

ToDo list for the docs of PureBasic v4.40 and later:
(last revised by André on 10-Feb-2010)

Quote:

Docs::Manual (always valid for english version, other languages are independent)
-------------
- following examples are linked in the docs, but not available:
[Done] Gadget3D.pb, Sound3D.pb, Window3D.pb
Node.pb (Note: there is still no example code, but the wrong link in the docs was removed)
Map.pb
- OpenDatabaseRequester(): description of optional parameter [, Plugin] is missing in the docs
- Process lib: adding Source example
- 3D engine: source example, showing stuff like collision, etc.
- EventLParam() / EventWParam() : users are requesting manual descriptions for them, because they are included since PB 2.4 but still not officialy supported...
- Math lib: currently there is noted in the Overview, that mostly .f floats are supported. Either Doubles should also be supported by PB or a note about this (and correct type converting) must be added.
- Unicode example - there should be one in Examples directory, as many users are requesting this.
- 8192x8192 restriction for images was removed? => then the docs must be updated
- Terrain lib: the generating of realtime-shadows on terrains isn't supported by PB now. A note should be added to the manual - or will this be fixed within a short time?
- Goto: more "warnings" at related keywords (Select...), that it shouldn't be used because of stack problems (see here: viewtopic.php?t=28136)
- Add3DArchive(): documentation about the return value is missing (adding archive sucessful or not?)
- WaitWindowEvent(): a note about the default value (number or PB constant) of the optional 'TimeOut' parameter is missing
- Fog/SkyDome (and probably other 3D commands too): more informations about parameter type and possible ranges are required (see here: http://www.purebasic.fr/german/viewtopi ... 946#216946)
- 3D libs: include "#PB_Compiler_Home +" in every example code to make them runnable!? (see here: http://www.purebasic.fr/german/viewtopi ... 951#216951)
- 'Compile executable' is completely missing in the IDE_Compiler.txt doc - e.g. there should be added a note, that on MacOS ".app" must be added to the executable name to make it run stand-alone
- #PB_Integer constant is not mentioned in the docs
- MD5Fingerprint(): Rework the example + add a note about correct usage on older Windows OS (see german thread)
- Scintilla.txt: example + screenshot should be added to the docs
- Library Subsystems: DirectX 7 need to mentioned with PB4.40!

Topics added because of suggestions in this thread:
- PB functions implemented as inline - have a mention of it the doc. Sometimes knowing a certain function is inlined (no stack used) can influence some decisions.
- mention in the manual about PureBasic SDK and its use.
- suggestion about AESEncoder()
- note at Chr(), that it can contain also Unicode characters
- add 'NewMap' (and probably other new keywords) to the CHM help-index (DocMaker issue)
[Done] - documentation of the new 2D Drawing commands, drawing modes, etc.
- add a note about "Compiler options" ignored when using "Create executable" (see here: viewtopic.php?f=7&t=40225)
- use descriptions in "Survival Guide" by blueznl' about type casting and expression evaluation for improving the manual
- Goto leaving Select:Case blocks lead to a unbalanced stack / better use If:Endif blocks thens => add a comment to the manual
- LoadTexture(): check the really supported gfx format, as the Ogre.log lists a lot more supported formats

Also be aware of notes about improving the manual by german users here:
http://www.purebasic.fr/german/viewtopic.php?t=7908 (old)
http://www.purebasic.fr/german/viewtopic.php?t=12957
http://www.purebasic.fr/german/viewtopic.php?t=12958

Thanks for any further suggestions!

(Please note: the list above is partly already a bit older, so some things are probably already done :-)

)

Andre · **Posted:** Mon Aug 31, 2009 11:58 am

One additional note:

The help for PB4.40 still must be done. So ".... is missing" statements about the features of the new version aren't needed at this time. :wink:

Kale · **Posted:** Mon Aug 31, 2009 12:33 pm

There is no mention in the manual that you can specify a return type in an interface declaration.

http://www.purebasic.fr/english/viewtopic.php?t=38493

Progi1984 · **Posted:** Mon Aug 31, 2009 1:00 pm

There is no mention in the manual about PureBasic SDK and its use.

luis · **Posted:** Tue Sep 01, 2009 4:56 pm

In "Variables and Types"

typo: "To avaid typing errors", should be "avoid".

I noticed there is no mention of the fact PureBasic's variable are not case sensitive, so "pure" and "PURE" are the same variable.

Would be nice to specify this.

srod · **Posted:** Tue Sep 01, 2009 5:19 pm

General syntax rules :

Quote:

- Return values of commands are always Longs if no other type is specified in the Syntax line of the command description.

Should be integers I guess.

Little John · **Posted:** Mon Sep 21, 2009 6:47 pm

PB 4.40 Beta 3, documentation of AESEncoder()

Quote:

Result$ = AESEncoder(*Input, *Output, Size, *Key, Bits, *InitializationVector [, Mode])

But as far as I can see, AESEncoder() returns a number, not a string.

Quote:

The 'InitializationVector' is a 32 bytes random data area

But in the given example the 'InitializationVector' has only a size of 16 bytes.

//edit:
As netmaestro wrote, the encoded string produced by AESEncoder() might contain zeros! So we can't use PeekS() on it.
IMHO it's a good idea to mention this fact explicitly in the docs for safety's sake. It also means, that the following part

Code:

If AESEncoder(@String$, *CipheredString, Len(String$), ?Key, 128, ?InitializationVector)
   Debug "Ciphered: "+PeekS(*CipheredString)

of the given examle is flawed.

Regards, Little John

luis · **Posted:** Tue Sep 22, 2009 4:57 pm

Help on DESFingerprint()

"compatiable which any standard linux hash password " should be "compatible with ..."

luis · **Posted:** Wed Sep 23, 2009 5:56 pm

Would be nice for the PB functions implemented as inline to have a mention of it the doc.

Sometimes knowing a certain function is inlined (no stack used) can influence some decisions.

Andre · **Posted:** Sun Sep 27, 2009 7:09 pm

I've fixed / added the following suggestions:
- a return type can be specified in an interface declaration
- "Variables and Types" chapter: added a note, that PB's variables are not case-sensitive
- Return values of commands are always Integers now
- spelling errors at DESFingerprint() and other description of (english) Cipher library docs

The other suggestions I will put on the ToDo list in first topic - they are up to Fred & Timo... :wink:

Little John · **Posted:** Sun Sep 27, 2009 7:17 pm

Thank you!

Regards, Little John

flaith · **Posted:** Sun Sep 27, 2009 7:56 pm

content deleted i've got my answer and because i have misunderstood

luis · **Posted:** Sun Sep 27, 2009 8:41 pm

André, can we continue to post corrections/requests for the helpfile in this thread ?

Thank you!

Andre · **Posted:** Mon Sep 28, 2009 6:57 pm

luis wrote:

André, can we continue to post corrections/requests for the helpfile in this thread ?

Of course! This is it, what this thread if thought for...

Andre · **Posted:** Tue Sep 29, 2009 6:40 pm

According to the "Quad bug" and similar threads I would suggest to add a little chapter about proper type casting (using different types of variables in expressions, expected and maybe different results,...) to the manual...

And don't say: "just do it!"

It need to be done by the "professionals" like Fred & freak.
Or anyone is able to write such thing with some good examples, how it should be done and not be done...? :twisted:

PureBasic Forum

PureBasic Docs - Errors & needed improvements to the man

Who is online