PureBasic Docs - Errors & needed improvements to the man

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

Moderator: Documentation Editors

User avatar
Guimauve
Enthusiast
Enthusiast
Posts: 742
Joined: Wed Oct 22, 2003 2:51 am
Location: Canada

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

Post by Guimauve »

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
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
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 »

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
"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 »

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 ?
"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 »

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.
"Have you tried turning it off and on again ?"
A little PureBasic review
User avatar
spikey
Enthusiast
Enthusiast
Posts: 579
Joined: Wed Sep 22, 2010 1:17 pm
Location: United Kingdom

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

Post by spikey »

1) UserGuide - Displaying text output (console), 1st paragraph contains an improperly formatted hyperlink -

Code: Select all

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....]
BorisTheOld
Enthusiast
Enthusiast
Posts: 542
Joined: Tue Apr 24, 2012 5:08 pm
Location: Ontario, Canada

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

Post by BorisTheOld »

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: 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 problem with the OffsetOf description is that the whole thing seems to be incorrect and/or outdated.
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
BorisTheOld
Enthusiast
Enthusiast
Posts: 542
Joined: Tue Apr 24, 2012 5:08 pm
Location: Ontario, Canada

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

Post by BorisTheOld »

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:
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? :)
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
BorisTheOld
Enthusiast
Enthusiast
Posts: 542
Joined: Tue Apr 24, 2012 5:08 pm
Location: Ontario, Canada

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

Post by BorisTheOld »

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
IdeasVacuum
Always Here
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

Post by IdeasVacuum »

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.
IdeasVacuum
Always Here
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

Post by IdeasVacuum »

Information on Passing & Receiving Structures should be in the Help. See this post for info:
http://www.purebasic.fr/english/viewtop ... 13&t=47006
IdeasVacuum
If it sounds simple, you have not grasped the complexity.
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: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)
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 »

OK then, thank you. :wink:
"Have you tried turning it off and on again ?"
A little PureBasic review
User avatar
skywalk
Addict
Addict
Posts: 3960
Joined: Wed Dec 23, 2009 10:14 pm
Location: Boston, MA

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

Post by skywalk »

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
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 »

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