PureBasic Docs - Errors & needed improvements to the man

Found an issue in the documentation ? Please report it here !

Moderator: Documentation Editors

User avatar
Andre
PureBasic Team
PureBasic Team
Posts: 2050
Joined: Fri Apr 25, 2003 6:14 pm
Location: Germany (Saxony, Deutscheinsiedel)
Contact:

PureBasic Docs - Errors & needed improvements to the man

Post 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 :-))
Last edited by Andre on Mon Aug 31, 2009 12:15 pm, edited 1 time in total.
Bye,
...André
(PureBasicTeam::Docs & Support - PureArea.net | Order:: PureBasic | PureVisionXP)
User avatar
Andre
PureBasic Team
PureBasic Team
Posts: 2050
Joined: Fri Apr 25, 2003 6:14 pm
Location: Germany (Saxony, Deutscheinsiedel)
Contact:

Post 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:
Bye,
...André
(PureBasicTeam::Docs & Support - PureArea.net | Order:: PureBasic | PureVisionXP)
Kale
PureBasic Expert
PureBasic Expert
Posts: 3000
Joined: Fri Apr 25, 2003 6:03 pm
Location: Lincoln, UK
Contact:

Post 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
--Kale

Image
User avatar
Progi1984
Addict
Addict
Posts: 806
Joined: Fri Feb 25, 2005 1:01 am
Location: France > Rennes
Contact:

Post by Progi1984 »

There is no mention in the manual about PureBasic SDK and its use.
User avatar
luis
Addict
Addict
Posts: 3876
Joined: Wed Aug 31, 2005 11:09 pm
Location: Italy

Post 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.
srod
PureBasic Expert
PureBasic Expert
Posts: 10589
Joined: Wed Oct 29, 2003 4:35 pm
Location: Beyond the pale...

Post 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.
I may look like a mule, but I'm not a complete ass.
Little John
Addict
Addict
Posts: 4519
Joined: Thu Jun 07, 2007 3:25 pm
Location: Berlin, Germany

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

Post 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
User avatar
luis
Addict
Addict
Posts: 3876
Joined: Wed Aug 31, 2005 11:09 pm
Location: Italy

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

Post by luis »

Help on DESFingerprint()

"compatiable which any standard linux hash password " should be "compatible with ..."
"Have you tried turning it off and on again ?"
A little PureBasic review
User avatar
luis
Addict
Addict
Posts: 3876
Joined: Wed Aug 31, 2005 11:09 pm
Location: Italy

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

Post 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.
"Have you tried turning it off and on again ?"
A little PureBasic review
User avatar
Andre
PureBasic Team
PureBasic Team
Posts: 2050
Joined: Fri Apr 25, 2003 6:14 pm
Location: Germany (Saxony, Deutscheinsiedel)
Contact:

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

Post 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:
Bye,
...André
(PureBasicTeam::Docs & Support - PureArea.net | Order:: PureBasic | PureVisionXP)
Little John
Addict
Addict
Posts: 4519
Joined: Thu Jun 07, 2007 3:25 pm
Location: Berlin, Germany

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

Post by Little John »

Thank you! :)

Regards, Little John
User avatar
flaith
Enthusiast
Enthusiast
Posts: 704
Joined: Mon Apr 25, 2005 9:28 pm
Location: $300:20 58 FC 60 - Rennes
Contact:

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

Post by flaith »

content deleted i've got my answer and because i have misunderstood :wink:
Last edited by flaith on Sun Sep 27, 2009 9:26 pm, edited 4 times in total.
“Fear is a reaction. Courage is a decision.” - WC
User avatar
luis
Addict
Addict
Posts: 3876
Joined: Wed Aug 31, 2005 11:09 pm
Location: Italy

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

Post by luis »

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

Thank you!
"Have you tried turning it off and on again ?"
A little PureBasic review
User avatar
Andre
PureBasic Team
PureBasic Team
Posts: 2050
Joined: Fri Apr 25, 2003 6:14 pm
Location: Germany (Saxony, Deutscheinsiedel)
Contact:

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

Post 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... :)
Bye,
...André
(PureBasicTeam::Docs & Support - PureArea.net | Order:: PureBasic | PureVisionXP)
User avatar
Andre
PureBasic Team
PureBasic Team
Posts: 2050
Joined: Fri Apr 25, 2003 6:14 pm
Location: Germany (Saxony, Deutscheinsiedel)
Contact:

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

Post 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:
Bye,
...André
(PureBasicTeam::Docs & Support - PureArea.net | Order:: PureBasic | PureVisionXP)
Locked