PureBasic Forums - English

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

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

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 ?

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.

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....]

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.

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?

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.

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

Information on Passing & Receiving Structures should be in the Help. See this post for info:
http://www.purebasic.fr/english/viewtop ... 13&t=47006

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).

OK then, thank you.

Andre wrote:Fred already agreed to make a separate sub-forum for bug-reports on the documentation.

That is great news

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!