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.
8) 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.
OK, I cover most of these in the new manual then. I created a new section "GLBasic intern" where I describe these.
Great news! Can't wait to see the new documentation then!!! Thanks!
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.
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? :-)
Great idea. Any free tools to do that?
You could do it as a Wiki, and use some of the free tools for that.
I have been looking thru what exists and this one (http://wikkawiki.org/HomePage) 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 (http://gamecorner.110mb.com/wiki/wikka.php?wakka=HomePage)
I've used Dokuwiki a bit. I've found it really easy to install and use.
http://www.wikimatrix.org/show/DokuWiki (http://www.wikimatrix.org/show/DokuWiki)
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.
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! :good:
:booze: Great work on the "GLBasic intern" section of the manual!!!! THANKS! :good:
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]
It doesn't exist, I'm afraid.
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 (http://www.willhostforfood.com/access.php?fileid=58565)
test - attachment
EDIT:
Now its works :)
But your helpfile are incomplete :P
[attachment deleted by admin]
Changing the help files manually is a _BAD_ idea. I have no time to read and watch all your changes. Just post a message here when somehting needs to be fixed, please.
Thank you for helping my with my "broken English", though.
The help files I posted weren't meant to be the complete help files - they are only meant to be a restructure of the "commands by category" pages for beginners like me that need the commands in more detailed categories than Gernot's version to make them easy to find. I have not redocumented any commands that would need to be checked over, I've only changed the layout of the pages.
Once the users are used to the language then they'll hardly ever need to look up the help, but as a beginner it's very hard to find the commands you need with the helpfiles in the current format. I posted about that a while ago and obviously Gernot hadn't had the time to look into it, so I decided to contribute what little I currently can to the community and the project by doing the restructure myself. I'm trying to help here - the last thing I'm trying to do is create work for you Gernot!!!! That is also one of the reasons that I only pasted the pages I changed - if I'd posted all the html files here Gernot would have to spend hours reviewing everthing to see if anything had changed. The changes are primarily for me, but I figured other beginners might find them helpful, hence the posting here.
As per your post Gernot, I was posting a message when something needed to be fixed. In my opinion the whole "commands by category" needed to be "fixed" as it is too hard to find the right commands as a beginner in their current format. By posting the suggested changes complete in the html format that they're in in the help file, they should be a lot easier and quicker with your limited time for you to implement if you decide to integrate the changes. Surely that's a much better option for you than if I post pages of suggested changes in plain text here and you then need to go and do hours of work to put them back into the html format?
My appologies Gernot if you find my work a problem rather than something helpful - if nothing else though, at least by my going through it I was able to find for you all the commands that have been accidently missed being documented in those pages.
Very good job, FutureCow. That is exactly what I wanted when you started the first thread on this subject! I tried to do my own structuring but it didn't turn out very well I thought so didn't push it any more.