PureBasic Docs - Errors & needed improvements to the man
Moderator: Documentation Editors
Re: PureBasic Docs - Errors & needed improvements to the man
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
[André on 5th Oct. 2012: works with PB5.00b4 for Windows]
Best regards.
Guimauve
Last edited by Guimauve on Tue Sep 11, 2012 11:03 pm, edited 1 time in total.
Dear Optimist, Pessimist,
and Realist,
While you guys were
busy arguing about the
glass of water, I DRANK IT !
Sincerely,
the Opportunist
and Realist,
While you guys were
busy arguing about the
glass of water, I DRANK IT !
Sincerely,
the Opportunist
Re: PureBasic Docs - Errors & needed improvements to the man
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: http://www.purebasic.fr/english/viewtop ... 12&t=51251
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: http://www.purebasic.fr/english/viewtop ... 12&t=51251
"Have you tried turning it off and on again ?"
A little PureBasic review
A little PureBasic review
Re: PureBasic Docs - Errors & needed improvements to the man
PB 4.61
Now it leads to Dim instead of ArraySize(). Is it moving around ?Trond wrote:- Typing ArraySize() and pressing F1 leads to the wrong manual page (Array instead of ArraySize()).
"Have you tried turning it off and on again ?"
A little PureBasic review
A little PureBasic review
Re: PureBasic Docs - Errors & needed improvements to the man
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.
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.
"Have you tried turning it off and on again ?"
A little PureBasic review
A little PureBasic review
Re: PureBasic Docs - Errors & needed improvements to the man
1) UserGuide - Displaying text output (console), 1st paragraph contains an improperly formatted hyperlink -
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....]
Code: Select all
ReferenceLink "debugger" "debug window"
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....]
-
- Enthusiast
- Posts: 542
- Joined: Tue Apr 24, 2012 5:08 pm
- Location: Ontario, Canada
Re: PureBasic Docs - Errors & needed improvements to the man
The problem with the OffsetOf description is that the whole thing seems to be incorrect and/or outdated.Arctic Fox wrote: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.Help: OffsetOf wrote:... When used with an Interface, the function index is the memory offset, so it will be IndexOfTheFunction*4.
Code: Select all
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 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.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 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
~ Spike Milligan
-
- Enthusiast
- Posts: 542
- Joined: Tue Apr 24, 2012 5:08 pm
- Location: Ontario, Canada
Re: PureBasic Docs - Errors & needed improvements to the man
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:
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?
In this section, the word than is used in several places instead of the word that. For example:
I have seen this same error in many other places in the PB documentation.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.
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?
Last edited by BorisTheOld on Sun Sep 16, 2012 9:43 pm, edited 1 time in total.
For ten years Caesar ruled with an iron hand, then with a wooden foot, and finally with a piece of string.
~ Spike Milligan
~ Spike Milligan
-
- Enthusiast
- Posts: 542
- Joined: Tue Apr 24, 2012 5:08 pm
- Location: Ontario, Canada
Re: PureBasic Docs - Errors & needed improvements to the man
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.
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
~ Spike Milligan
-
- Always Here
- Posts: 6425
- Joined: Fri Oct 23, 2009 2:33 am
- Location: Wales, UK
- Contact:
Re: PureBasic Docs - Errors & needed improvements to the man
I agree 100% with your recent posts to the Docs subject - and 200% with the comment aboveIf 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.
IdeasVacuum
If it sounds simple, you have not grasped the complexity.
If it sounds simple, you have not grasped the complexity.
-
- Always Here
- Posts: 6425
- Joined: Fri Oct 23, 2009 2:33 am
- Location: Wales, UK
- Contact:
Re: PureBasic Docs - Errors & needed improvements to the man
Information on Passing & Receiving Structures should be in the Help. See this post for info:
http://www.purebasic.fr/english/viewtop ... 13&t=47006
http://www.purebasic.fr/english/viewtop ... 13&t=47006
IdeasVacuum
If it sounds simple, you have not grasped the complexity.
If it sounds simple, you have not grasped the complexity.
- Andre
- PureBasic Team
- Posts: 2071
- Joined: Fri Apr 25, 2003 6:14 pm
- Location: Germany (Saxony, Deutscheinsiedel)
- Contact:
Re: PureBasic Docs - Errors & needed improvements to the man
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....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.
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).
Re: PureBasic Docs - Errors & needed improvements to the man
OK then, thank you.
"Have you tried turning it off and on again ?"
A little PureBasic review
A little PureBasic review
Re: PureBasic Docs - Errors & needed improvements to the man
That is great newsAndre wrote:Fred already agreed to make a separate sub-forum for bug-reports on the documentation.
The nice thing about standards is there are so many to choose from. ~ Andrew Tanenbaum
- Andre
- PureBasic Team
- Posts: 2071
- Joined: Fri Apr 25, 2003 6:14 pm
- Location: Germany (Saxony, Deutscheinsiedel)
- Contact:
Re: PureBasic Docs - Errors & needed improvements to the man
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!
As we now have a separate sub-forum (http://www.purebasic.fr/english/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!
As we now have a separate sub-forum (http://www.purebasic.fr/english/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!