Page 1 of 15

PureBasic Docs - Errors & needed improvements to the man

Posted: Mon Aug 31, 2009 11:52 am
by Andre
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 23-Sep-2011)
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: http://www.purebasic.fr/english/viewtopic.php?t=28136)
[Separate bug-thread]- Add3DArchive(): documentation about the return value is missing (adding archive sucessful or not?)
[Separate bug-thread]- WaitWindowEvent(): a note about the default value (number or PB constant) of the optional 'TimeOut' parameter is missing
[Separate bug-thread]- 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)
[Separate bug-thread]- '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
[Separate bug-thread]- #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()
[Done]- note at Chr(), that it can contain also Unicode characters
[Separate bug-thread]- 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: http://www.purebasic.fr/english/viewtop ... =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
- [..... more to be added here ....]
- 08/28/2010: complete manual: a note about the really used standard (Windows-1252) instead of only "ASCII mode" is requested
- 09/02/2010: Base64Decoder(): output buffer should be 25% instead of 33% (see following discussion about percental math...)
- 09/04/2010: RemoveString() and ReplaceString() need a description of what value to use for the default search mode when specifying a StartPosition
- 09/09/2010: DatabaseUpdate() example should mention both parameters + several listed missing translations in french manual
- 09/10/2010: GetFunction() refers to CallFunctionFast() and CallCFunctionFast(). It would be better if it referred to the prototypes
- 09/24/2010: [Separate bug-thread] AddMailAttachment() has desicriptions of mime types, some desicriptions are written in French
- 10/08/2010: [Done] Pressing F1 on InputEvent3D() brings up the help with a "This program cannot display the webpage" message
- 01/06/2011: declaring constants is possible more than once, if they are declared with the same value each time + add a remark regarding the evaluation of strings in conditional expressions
- 01/08/2011: "Customizing the IDE" - suggestion for adding a more precise description
- 01/19/2011: SetMenuItemState() is set to checked(ON) with any non-zero entry, -1,+1,99,etc.
- 01/25/2011: Texture : Loadtexture() can even load *.DDS files (check the really supported gfx format, as the Ogre.log lists a lot more supported formats)
- 03/09/2011: [Separate bug-thread]structure related Compiler Functions + more are missing in the index: Win64, Help Index. InitializeStructure, CopyStructure and ClearStructure
- 03/13/2011: CreateImage() is no longer restricted to 8192x8192, but is now 32000x32000
- 04/22/2011: if a procedure doesn't include a 'ProcedureReturn' the return value defaults to zero
- 05/05/2011: ScrollBarGadget() code example does not scroll anything
- 06/16/2011: [Done] CopyMemoryString() should be updated to describe the need to allow space for the #Null at the end of a string...

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

Posted: Mon Aug 31, 2009 11:58 am
by Andre
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:

Posted: Mon Aug 31, 2009 12:33 pm
by Kale
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

Posted: Mon Aug 31, 2009 1:00 pm
by Progi1984
There is no mention in the manual about PureBasic SDK and its use.

Posted: Tue Sep 01, 2009 4:56 pm
by luis
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.

Posted: Tue Sep 01, 2009 5:19 pm
by srod
General syntax rules :
- 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.

Re: PureBasic Docs - Errors & needed improvements to the man

Posted: Mon Sep 21, 2009 6:47 pm
by Little John
PB 4.40 Beta 3, documentation of AESEncoder()
Result$ = AESEncoder(*Input, *Output, Size, *Key, Bits, *InitializationVector [, Mode])
But as far as I can see, AESEncoder() returns a number, not a string.
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: Select all

If AESEncoder(@String$, *CipheredString, Len(String$), ?Key, 128, ?InitializationVector)
   Debug "Ciphered: "+PeekS(*CipheredString)
of the given examle is flawed.

Regards, Little John

Re: PureBasic Docs - Errors & needed improvements to the man

Posted: Tue Sep 22, 2009 4:57 pm
by luis
Help on DESFingerprint()

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

Re: PureBasic Docs - Errors & needed improvements to the man

Posted: Wed Sep 23, 2009 5:56 pm
by luis
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.

Re: PureBasic Docs - Errors & needed improvements to the man

Posted: Sun Sep 27, 2009 7:09 pm
by Andre
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:

Re: PureBasic Docs - Errors & needed improvements to the man

Posted: Sun Sep 27, 2009 7:17 pm
by Little John
Thank you! :)

Regards, Little John

Re: PureBasic Docs - Errors & needed improvements to the man

Posted: Sun Sep 27, 2009 7:56 pm
by flaith
content deleted i've got my answer and because i have misunderstood :wink:

Re: PureBasic Docs - Errors & needed improvements to the man

Posted: Sun Sep 27, 2009 8:41 pm
by luis
André, can we continue to post corrections/requests for the helpfile in this thread ?

Thank you!

Re: PureBasic Docs - Errors & needed improvements to the man

Posted: Mon Sep 28, 2009 6:57 pm
by Andre
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... :)

Re: PureBasic Docs - Errors & needed improvements to the man

Posted: Tue Sep 29, 2009 6:40 pm
by Andre
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!" :P

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: