It is currently Fri Jul 20, 2018 6:15 am

All times are UTC + 1 hour




Post new topic This topic is locked, you cannot edit posts or make further replies.  [ 224 posts ]  Go to page 1, 2, 3, 4, 5 ... 15  Next
Author Message
 Post subject: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Mon Aug 31, 2009 11:52 am 
Offline
PureBasic Team
PureBasic Team
User avatar

Joined: Fri Apr 25, 2003 6:14 pm
Posts: 1559
Location: Germany (Saxony, Deutscheinsiedel)
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)
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)
[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: 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
- [..... 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 :-))

_________________
Bye,
...André
(PureBasicTeam::Docs & Support - PureArea.net | Order:: PureBasic | PureVisionXP)


Last edited by Andre on Mon Aug 31, 2009 12:15 pm, edited 1 time in total.

Top
 Profile  
 
 Post subject:
PostPosted: Mon Aug 31, 2009 11:58 am 
Offline
PureBasic Team
PureBasic Team
User avatar

Joined: Fri Apr 25, 2003 6:14 pm
Posts: 1559
Location: Germany (Saxony, Deutscheinsiedel)
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)


Top
 Profile  
 
 Post subject:
PostPosted: Mon Aug 31, 2009 12:33 pm 
Offline
PureBasic Expert
PureBasic Expert
User avatar

Joined: Fri Apr 25, 2003 6:03 pm
Posts: 3000
Location: Lincoln, UK
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


Top
 Profile  
 
 Post subject:
PostPosted: Mon Aug 31, 2009 1:00 pm 
Offline
Addict
Addict
User avatar

Joined: Fri Feb 25, 2005 1:01 am
Posts: 806
Location: France > Normandy > Near Caen
There is no mention in the manual about PureBasic SDK and its use.


Top
 Profile  
 
 Post subject:
PostPosted: Tue Sep 01, 2009 4:56 pm 
Offline
Addict
Addict
User avatar

Joined: Wed Aug 31, 2005 11:09 pm
Posts: 3650
Location: Italy
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.


Top
 Profile  
 
 Post subject:
PostPosted: Tue Sep 01, 2009 5:19 pm 
Offline
PureBasic Expert
PureBasic Expert

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

_________________
I may look like a mule, but I'm not a complete ass.


Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Mon Sep 21, 2009 6:47 pm 
Offline
Addict
Addict
User avatar

Joined: Thu Jun 07, 2007 3:25 pm
Posts: 3169
Location: Berlin, Germany
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

_________________
Please excuse my flawed English. My native language is PureBasic.
Search
RSBasic's backups


Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Tue Sep 22, 2009 4:57 pm 
Offline
Addict
Addict
User avatar

Joined: Wed Aug 31, 2005 11:09 pm
Posts: 3650
Location: Italy
Help on DESFingerprint()

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

_________________
[ My little PureBasic review ]


Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Wed Sep 23, 2009 5:56 pm 
Offline
Addict
Addict
User avatar

Joined: Wed Aug 31, 2005 11:09 pm
Posts: 3650
Location: Italy
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.

_________________
[ My little PureBasic review ]


Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Sun Sep 27, 2009 7:09 pm 
Offline
PureBasic Team
PureBasic Team
User avatar

Joined: Fri Apr 25, 2003 6:14 pm
Posts: 1559
Location: Germany (Saxony, Deutscheinsiedel)
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)


Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Sun Sep 27, 2009 7:17 pm 
Offline
Addict
Addict
User avatar

Joined: Thu Jun 07, 2007 3:25 pm
Posts: 3169
Location: Berlin, Germany
Thank you! :)

Regards, Little John

_________________
Please excuse my flawed English. My native language is PureBasic.
Search
RSBasic's backups


Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Sun Sep 27, 2009 7:56 pm 
Offline
Enthusiast
Enthusiast
User avatar

Joined: Mon Apr 25, 2005 9:28 pm
Posts: 699
Location: $300:20 58 FC 60 - Vietnam
content deleted i've got my answer and because i have misunderstood :wink:

_________________
“Fear is a reaction. Courage is a decision.” - WC


Last edited by flaith on Sun Sep 27, 2009 9:26 pm, edited 4 times in total.

Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Sun Sep 27, 2009 8:41 pm 
Offline
Addict
Addict
User avatar

Joined: Wed Aug 31, 2005 11:09 pm
Posts: 3650
Location: Italy
André, can we continue to post corrections/requests for the helpfile in this thread ?

Thank you!

_________________
[ My little PureBasic review ]


Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Mon Sep 28, 2009 6:57 pm 
Offline
PureBasic Team
PureBasic Team
User avatar

Joined: Fri Apr 25, 2003 6:14 pm
Posts: 1559
Location: Germany (Saxony, Deutscheinsiedel)
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)


Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Tue Sep 29, 2009 6:40 pm 
Offline
PureBasic Team
PureBasic Team
User avatar

Joined: Fri Apr 25, 2003 6:14 pm
Posts: 1559
Location: Germany (Saxony, Deutscheinsiedel)
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)


Top
 Profile  
 
Display posts from previous:  Sort by  
Post new topic This topic is locked, you cannot edit posts or make further replies.  [ 224 posts ]  Go to page 1, 2, 3, 4, 5 ... 15  Next

All times are UTC + 1 hour


Who is online

Users browsing this forum: No registered users and 1 guest


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum

Search for:
Jump to:  

 


Powered by phpBB © 2008 phpBB Group
subSilver+ theme by Canver Software, sponsor Sanal Modifiye