It is currently Sat Aug 24, 2019 11:13 pm

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 Previous  1 ... 11, 12, 13, 14, 15
Author Message
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Mon Aug 06, 2012 2:06 am 
Offline
Enthusiast
Enthusiast
User avatar

Joined: Wed Oct 22, 2003 2:51 am
Posts: 743
Location: Canada
In the "Cipher" section of the help, the CRC32FileFingerprint() command is missing but the command exist.

[André on 5th Oct. 2012: works with PB5.00b4 for Windows]

Best regards.
Guimauve

_________________
Dear Optimist, Pessimist,
and Realist,

While you guys were
busy arguing about the
glass of water, I DRANK IT !

Sincerely,
the Opportunist


Last edited by Guimauve on Tue Sep 11, 2012 11:03 pm, edited 1 time in total.

Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Tue Sep 11, 2012 6:55 pm 
Offline
Addict
Addict
User avatar

Joined: Wed Aug 31, 2005 11:09 pm
Posts: 3694
Location: Italy
In the page where the math operators are discussed, should be mentioned the shorthand

x + c, instead of x = x + c

and its correspondents

x * c
x / c

etc.

can be subject to potentially unexpected side effects when the x part is a "complex expression (not to mention a function call such as Random())"

for more info and one example of it see: viewtopic.php?f=12&t=51251

_________________
[ My little PureBasic review ]


Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Tue Sep 11, 2012 7:58 pm 
Offline
Addict
Addict
User avatar

Joined: Wed Aug 31, 2005 11:09 pm
Posts: 3694
Location: Italy
PB 4.61

Trond wrote:
- Typing ArraySize() and pressing F1 leads to the wrong manual page (Array instead of ArraySize()).


Now it leads to Dim instead of ArraySize(). Is it moving around :D ?

_________________
[ My little PureBasic review ]


Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Tue Sep 11, 2012 8:07 pm 
Offline
Addict
Addict
User avatar

Joined: Wed Aug 31, 2005 11:09 pm
Posts: 3694
Location: Italy
André

could be possible delete the posts about the suggestions already implemented in the manual ?

It's becoming too slow to check in a 15 pages thread if something was already reported / fixed.

_________________
[ My little PureBasic review ]


Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Thu Sep 13, 2012 2:00 pm 
Offline
Enthusiast
Enthusiast
User avatar

Joined: Wed Sep 22, 2010 1:17 pm
Posts: 294
Location: United Kingdom
1) UserGuide - Displaying text output (console), 1st paragraph contains an improperly formatted hyperlink -
Code:
ReferenceLink "debugger" "debug window"

2) UserGuide - Displaying text output (console), last paragraph - note to select console on Mac systems applies to Linux too.
3) UserGuide - Structuring code in Procedures, line should read (it contains an extraneous 'but'):
Also, although this program didn't really need to, this procedure is called after calling "WindowCreate" to make sure the gadgets are the right size initially.
4) As observed by BorisTheOld: ClearStructure, InitialiseStructure, CopyStructure functions are missing from help index and the command index page.

[Andre on 3rd Oct. 2012: fixed 1-3), set 4) on To-Do-list for Fred....]


Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Sun Sep 16, 2012 4:06 pm 
Offline
Enthusiast
Enthusiast

Joined: Tue Apr 24, 2012 5:08 pm
Posts: 542
Location: Ontario, Canada
Arctic Fox wrote:
Help: OffsetOf wrote:
... When used with an Interface, the function index is the memory offset, so it will be IndexOfTheFunction*4.

On 64-bit it is IndexOfTheFunction*8. This goes for the example, too. Pointers are 4 bytes on 32-bit and 8 bytes on 64-bit.

Code:
Structure Person
  Name.s
  ForName.s
  Age.w
EndStructure

Debug OffsetOf(Person\Age) ; will be 8 as a string is 4 byte in memory (16 on 64-bit)


Interface ITest
  Create()
  Destroy(Flags)
EndInterface

Debug OffsetOf(ITest\Destroy()) ; will be 4 (8 on 64-bit)


The problem with the OffsetOf description is that the whole thing seems to be incorrect and/or outdated.

Quote:
OffsetOf can be used to find out the index of a Structure field or the index of an Interface function. When used with an Interface, the function index is the memory offset, so it will be IndexOfTheFunction*4.


The use of the word "index" implies a zero-based index that in the case of interfaces is used to calculate a memory offset. Whereas, the value returned is always a memory offset for both structures and interfaces.

The examples are correct -- with the improvements given by Arctic Fox.

_________________
For ten years Caesar ruled with an iron hand, then with a wooden foot, and finally with a piece of string.
~ Spike Milligan


Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Sun Sep 16, 2012 7:09 pm 
Offline
Enthusiast
Enthusiast

Joined: Tue Apr 24, 2012 5:08 pm
Posts: 542
Location: Ontario, Canada
I forgot to mention another problem with the Compiler Options section of the documentation.

In this section, the word than is used in several places instead of the word that. For example:

Quote:
InitializeStructure initialize the specified structured memory area. This is useful when the structure contains dynamic objects like array", list or map which have to be allocated internally by PureBasic. 'Structure' is the name of the structure which should be used to perform the initialization. There is no internal check to ensures than the structure match the memory area. This function is for advanced users only and should be used with care.


I have seen this same error in many other places in the PB documentation.

By the way, in the above example the sentence: "There is no internal check to ensures than the structure match the memory area."

should be written as: "There is no internal check to ensure that the structure matches the memory area."

I have a question: How picky do you want us to get about errors in English grammar, spelling, and word usage? :)

_________________
For ten years Caesar ruled with an iron hand, then with a wooden foot, and finally with a piece of string.
~ Spike Milligan


Last edited by BorisTheOld on Sun Sep 16, 2012 9:43 pm, edited 1 time in total.

Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Sun Sep 16, 2012 9:40 pm 
Offline
Enthusiast
Enthusiast

Joined: Tue Apr 24, 2012 5:08 pm
Posts: 542
Location: Ontario, Canada
And while I'm on a roll, I have a few observations about the PB documentation:

PureBasic is promoted as a cross-platform language, but much of the documentation has a Windows bias. It seems to me that all the documentation should be concerned only with standard cross-platform usage. Platform specific topics should be kept to a minimum and isolated in their own sections - one section for each platform.

The platform specific sections should restrict their content to general topics, such as how to interface with external libraries, or how to write code that can take advantage of the operating system's API. For example, a detailed explanation of how to use prototypes to interface with dynamic libraries, would be far more useful than scattering unorganized fragments of API code throughout the documentation.

The problem with including API documentation in the PB manuals is that it can never be complete. Even Power Basic, which is a Windows-only language, expects users to read the MS documentation if they want to use API services. Their own documentation contains nothing more on the topic than how to write declare statements to interface with the Windows libraries.

If PB users keep demanding examples of API code, then perhaps this is a sign that more cross-platform features should be added to the language, rather than more API examples added to the documentation.

_________________
For ten years Caesar ruled with an iron hand, then with a wooden foot, and finally with a piece of string.
~ Spike Milligan


Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Sun Sep 16, 2012 11:02 pm 
Offline
Always Here
Always Here

Joined: Fri Oct 23, 2009 2:33 am
Posts: 5830
Location: Wales, UK
Quote:
If PB users keep demanding examples of API code, then perhaps this is a sign that more cross-platform features should be added to the language, rather than more API examples added to the documentation.


I agree 100% with your recent posts to the Docs subject - and 200% with the comment above :mrgreen:

_________________
IdeasVacuum
If it sounds simple, you have not grasped the complexity.


Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Wed Sep 26, 2012 9:32 am 
Offline
Always Here
Always Here

Joined: Fri Oct 23, 2009 2:33 am
Posts: 5830
Location: Wales, UK
Information on Passing & Receiving Structures should be in the Help. See this post for info:
http://www.purebasic.fr/english/viewtopic.php?f=13&t=47006

_________________
IdeasVacuum
If it sounds simple, you have not grasped the complexity.


Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Wed Sep 26, 2012 1:36 pm 
Offline
PureBasic Team
PureBasic Team
User avatar

Joined: Fri Apr 25, 2003 6:14 pm
Posts: 1700
Location: Germany (Saxony, Deutscheinsiedel)
luis wrote:
could be possible delete the posts about the suggestions already implemented in the manual ?

It's becoming too slow to check in a 15 pages thread if something was already reported / fixed.


I noticed this already myself, especially as I can't work regularly on this topic and even more: for several things only Fred/freak can tell because of the internal knowledge....

Fred already agreed to make a separate sub-forum for bug-reports on the documentation. Then each doc-related "problem" can be read / checked / marked as 'Done' separately, just as with the bug-reports for Windows / Linux / MacOS.

Then this long thread will be moved there and closed (for using single forum entries in the future).

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


Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Wed Sep 26, 2012 2:01 pm 
Offline
Addict
Addict
User avatar

Joined: Wed Aug 31, 2005 11:09 pm
Posts: 3694
Location: Italy
OK then, thank you. :wink:

_________________
[ My little PureBasic review ]


Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Wed Sep 26, 2012 4:03 pm 
Offline
Addict
Addict
User avatar

Joined: Wed Dec 23, 2009 10:14 pm
Posts: 3022
Location: Boston, MA
Andre wrote:
Fred already agreed to make a separate sub-forum for bug-reports on the documentation.

That is great news :)

_________________
The nice thing about standards is there are so many to choose from. ~ Andrew Tanenbaum


Top
 Profile  
 
 Post subject: Re: PureBasic Docs - Errors & needed improvements to the man
PostPosted: Thu Sep 27, 2012 2:37 pm 
Offline
PureBasic Team
PureBasic Team
User avatar

Joined: Fri Apr 25, 2003 6:14 pm
Posts: 1700
Location: Germany (Saxony, Deutscheinsiedel)
Thanks guys, for all the input to fix bugs in the manual and generally make a better PB documentation, you gave over the last months/years! :D

As we now have a separate sub-forum (viewforum.php?f=37) I will close this thread. Please post further doc issues in the new sub-forum in separate threads, to have a better overview what's fixed and what is still to do. Thanks!

Of course, I will re-read this thread for "open" (not checked, not done....) suggestions.
Anyway... feel free, to post them in a new separate topic in the new "Bugs - documentation" sub-forum! :wink:

_________________
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 Previous  1 ... 11, 12, 13, 14, 15

All times are UTC + 1 hour


Who is online

Users browsing this forum: No registered users and 2 guests


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