PureBasic Library SDK: Update and Improve

[tajmone]

• PB-Library-SDK.html

The PureBasic Library SDK documentation (now converted to AsciiDoc) is quite outdated and contains references to files which are no longer in the SDK, changed paths, etc. We should polish up the document removing deprecated references, updating them with newer ones (when available), and other improvements to update this document to the current status of PB and its SDK.

• [ ] Obsolete References:
  • [ ] §4. Using FAsm
    • [ ] FAsm\MessageBox.asm? — it mentions compiling the FAsm\MessageBox.asm example, which is nowhere to be found in the SDK (not under Windows, at least).
    • [ ] Win32N.inc? — this file is mentioned (provided by Tamas Kaproncai), but it's nowhere to be found in the SDK (not under Windows, at least).
• [ ] x86_64 Assembly — the current document only mentions 32-bit assembly (e.g. the eax register for Procedures' returned values, etc.), it might worth adding the 64-bit equivalents next to these references.
• [ ] macOS and Yasm — §4. Using FAsm should provide some info for Mac users, which rely on Yasm rather than FAsm; either add some notes in §4 or add a dedicated section for macOS users.
• [ ] Unicode Strings — §7. Managing Strings might need to be checked to ensure that it covers Unicode strings (seems to have been written for PB 4.0).
• [ ] Windows only sections — these sections provides instructions for Windows only:
  • [ ] §8. Splitted Library Format — refers to polib.exe; should be expanded to include instructions for other OSs too:
    • [ ] Linux
    • [ ] macOS
  • [ ] §9. Command-Line Options — add instructions and examples for other OSs:
    • [ ] Linux
    • [ ] macOS
• [ ] Fix typos:
  • [x] in §5 » Basic Example — ; Langage used to code the library: ASM or C → Language.
  • [ ] "Splitted Library" — In §8. Splitted Library Format (and elsewhere) should be changed to → "split library". ("splitted" is an archaic past tense form of SPLIT. See Merriam-Webster » splitted).

The above task-list will be updated as fixes are done, and new entries added as the discussion in this thread evolves through PB users' contributions (i.e. it might be worth gathering as many fixes and improvements under a single Issue, instead of having dozens of independent Issues).

This Issue should be kept alive until all obsolete info is spotted and resolved, so that PB users from different OSs can discuss improvements to ensure the document will cover all three OSs adequately — and hopefully some old-time users will remember what the deprecated references were referring to, providing a better context.

---

NOTE — Now that we have an official open source PB repository, we should take advantage of this and update this document, because it's going to be the main source of information on how to create PB libraries in other languages.

This document is particularly important. For example, it's the only place where the Cpu Optimisation compiler options are explained (see §6. MMX, 3DNow, SSE and SSE2).