Documentation question/suggestions

[FutureCow]

As a new user of GLBasic, I'm having difficulty finding some things in the documentaion. I realise that Kitty Hello would have a million things on his plate that people want implemented, so my question is, is there a way for other people to contribute to the documentation? I've looked for a community wiki or similar and haven't found one. I would be happy to contribute to this (so Kitty Hello doesn't have to do everything!) if there was a way to do it.

I'm finding getting used to GLBasic is taking a bit longer than it might otherwise because some things I expect to be in the documentation either aren't there or I can't find them easily. Also, I'm not always connected to the internet so it would be great to have everything documented so I can find how to do something when I'm offline.

I've made a list of the things I've come across that I've either found so far or that I would like to see in the documentation (hopefully this is seen as constructive help!!!! I apologise if it sounds like I am complaining!!!)

1) A separate section in the documentation describing just the data types and what size they are for the different platforms. This would also detail how to declare each type so that you know that variable$ is a string for example. I keep having to go looking through the tutorial to find out which symbol to use for floats and which for ints.

2) Explaining how to have multiple source files, and how to use a  in your project. I spent a long time looking for an "include file" command before searching for "multiple source files" on the website gave me the answer (though I had to read through a few pages to find it)

3) In the "Commands By Category" section, further sub-grouping of the commands. Eg. If I want to do file manipulation (seek, read, write a file etc), but don't know the commands I have to look in the Input-Output section, then look at the ~50 commands that it gives there to find which one I need. If Input-Output was further broken up it would make it quicker to find the right command

eg.
Input-Output
- File Manipulation
  - Read, CopyFile etc
- Input Devices
  - MouseAxis, Joystate etc.
- Graphics
  - GetScreenSize, LoadBMP etc
- Fonts
  - GetFontSize etc.
- etc

4) Different operating systems - Information about the standard requirements of each platform. eg. What the acceptable screen sizes are, maximum program size, number of colours you can use, commands that don't work on a particular platform (if applicable)

5) How to use the profiler

6) What the Multisampling option is for on the options screen

7) Commands like ASIN and bXOR don't have any documentation. Others like "break" are missing examples.

A section on performance eg. getpixel isn't usable for intensive real time use, hibernate frees up cpu cycles when used etc.

9) The example for the DEC code has no DEC commands in it.

10) LoadBMP should list the different file formats it will load

11) What the Tools distributed with GLBasic are and what they're for.

12) How to debug your code.


Again, my apologies if this sounds like I'm doing a lot of complaining. This seems like a brilliant product so far - hopefully my comments will help improve the it.

[Kitty Hello]

OK, I cover most of these in the new manual then. I created a new section "GLBasic intern" where I describe these.

[FutureCow]

Great news! Can't wait to see the new documentation then!!! Thanks!

[FutureCow]

It might also be useful to add to the help page for animation load/draw commands that frame references are 0 based rather than 1 based.

[Moru]

Mabe it would be helpfull to make something like the PHP documentation where everyone can add comments on the end? In that case you just check what has been written and update the documentation if needed. You = someone that Gernot trusts to do it well I guess, can't expect Gernot to do everything? :-)

[Kitty Hello]

Great idea. Any free tools to do that?

[MrTAToad]

You could do it as a Wiki, and use some of the free tools for that.

[Moru]

I have been looking thru what exists and this one I find quite useful, you can add comment, registered users can change content (or not depending on what you set on each page) and it's very lightweight.

I set up a test on my page, going to try it out tonight if I get the chance.
My testserver

[FutureCow]

I've used Dokuwiki a bit. I've found it really easy to install and use.
http://www.wikimatrix.org/show/DokuWiki

[Moru]

Since that one doesn't have database support won't it get slow with many users? Wikkawiki was very easy to set up too, just create a database and user and answer a few questions and you are running.

[FutureCow]

At work we find it fast - admittedly we don't have heaps of people using it simultaneously.

The files you end up with are just text files with some formatting in them - surely displaying (with basic html like formatting) a text file would be faster than pulling it out of a database - plus there's no database overhead to worry about.
I don't have any particular preference, Dokuwiki is just the one we use at work and therefore the one I'm familiar with. I'll happily contribute to any format/solution that gets implemented! 

[FutureCow]

  Great work on the "GLBasic intern" section of the manual!!!! THANKS! 

[FutureCow]

All,
I had a day free at work so decided to try my hand at improving the commands by category pages in the help file. I'm not familiar enough with the language yet so I'm looking up the help pages for every second command I need to use. I like that the commands are collected in categories, but once in the categories I found it painful to read though every command in the category to find what I was looking for.

The end result of my work is attached. I've extracted the help files from the chm (using 7zip) and modified the html to subcategorise the categories, and put a table of contents at the top. I haven't reintegrated them yet into the chm (still have to figure out how to do that as 7zip doesn't support adding to chm files) but they work fine as html help files if you extract the Commands by Category directory as well.

I have expanded out all the commands currently listed as "..." commands (eg. sock_...) and also added some that were missed in the original documentation.

Please let me know if you find the changes helpful.

[attachment deleted by admin]

[MrTAToad]

It doesn't exist, I'm afraid.

[FutureCow]

There seems to be an issue with the forums. I've posted the files at the attached link in the meantime.
Feel free to give me some feedback.
http://www.willhostforfood.com/access.php?fileid=58565