GLBasic forum

Main forum => GLBasic - en => Topic started by: Cliff3D on 2010-Sep-06

Title: Documentation?
Post by: Cliff3D on 2010-Sep-06
I have to agree with FutureCow's long-past comments that the documentation for GLBasic is not welcoming to me. I'm struggling to find things. While the community is great and has been pointing me in the right direction, I'd rather the information I want was easier to find.

As a typical and timely example, take my current frustration - multiple files. I've just fought my way into getting Multiple Sourc eFiles working because even the intern does not lead one by the hand to making it WORK - there seem to be missing steps and information.

I'd love to see a Wikki (maybe I have just missed that too?) which users could manage to extend and update the documentation :)
Title: Re: Documentation?
Post by: Moru on 2010-Sep-06
There was a try by one of the community to make a wiki for GLBasic. It hasn't happened much there since everyone seems to know everything already :-)

http://wiki.just-do-i-t.com/index.php?title=GLBasic_Wiki

About your question for multiple source files:

Code (glbasic) Select
GLOBAL gFileTest1
GLOBAL gFileTest2
GLOBAL value%, ok1, ok2

gFileTest1 = GENFILE()
test1$ = "test.bin"
ok1 = OPENFILE(gFileTest1, test1$, TRUE)

gFileTest2 = GENFILE() // Must be called after OPENFILE, otherwise you get the same ID
test2$ = "test.bin"
ok2 = OPENFILE(gFileTest2, test2$, TRUE)

IF (ok1 AND ok2)
READBYTE gFileTest1, value%
READBYTE gFileTest2, value%
ENDIF


(untested but should get you started at least)
Title: Re: Documentation?
Post by: Quentin on 2010-Sep-06
the official help should also be available at

http://www.glbasic.com/xmlhelp.php

but you're right. Would be nice if the chm file was updated too
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-06
And dont forget my website too!  Really must start getting that wiki updated too...

Did you say that you had trouble adding multiple source files to a project ?
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-06
Ah - it's more multiple source files within GLBasic. I have this hankering to have the "main" file have the main routine and perhaps some subroutines and functions, but have a secondary .gbas file which contains the types, extended type, and probably some subroutines and functions. The idea being to make it easier to include the model handling routine in other projects (no copy and paste - just reuse the source file) but... well, to begin with I didn't select the "insert file to project" and I couldn't find where to "select the file" to make it the "main" one and I get all sorts of errors when I tried to move code between the source files.

for example, right now it's "working" using 2 source files provided I keep the split very very simple and just have the types in the library file... but even then I get a bunch of "warnings" :(

Code (glbasic) Select
*** Configuration: WIN32 ***
precompiling:
GPC - GLBasic Precompiler V.8.044 SN:1c15d767 - 2D, WIN32
"ReadOBJ.gbas"(0) warning : note : TYPE OBJModel is not declared

"ReadOBJ.gbas"(130) warning : note : TYPE OBJModel is not declared

"ReadOBJ.gbas"(130) warning : note : TYPE OBJModel is not declared

"ReadOBJ.gbas"(130) warning : note : TYPE OBJModel is not declared

"ReadOBJ.gbas"(130) warning : note : TYPE OBJModel is not declared

Wordcount:291 commands
compiling:
IncrediBuild skips: ReadOBJ.gbas, LoadOBJ.gbas,

linking:
success
_______________________________________
*** Finished ***
Elapsed: 2.4 sec. Time: 11:42
Build: 1 succeeded.


It's fine when run, but I am concerend about missing a warning tha tI SHOULD pay attention to because it's lost in what I consider to be "false warnings".

Any thoughts? Is there a step I can/should take that will tell GLBasic how to compile these two files (call them main.gbas and type.gbas) without throwing up false warnings?

I'm going to go find MrToad's website now to see if there's something there that will help me on this specific one... Thanks! :)

EDIT:- I've spent a while just tidying up the code and trying to get it to split nicely - and it's done, working, no errors or warnings :D
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-06
You can ignore the warnings.  Hopefully they will be removed in the next update.
Title: Re: Documentation?
Post by: Moru on 2010-Sep-06
Quote from: MrTAToad on 2010-Sep-06
And dont forget my website too!  Really must start getting that wiki updated too...

Yes sorry, I got interrupted and just posted to get it saved :-)
Title: Re: Documentation?
Post by: Wampus on 2010-Sep-06
Quote from: MrTAToad on 2010-Sep-06
And dont forget my website too!  Really must start getting that wiki updated too...

Did you say that you had trouble adding multiple source files to a project ?
Yes, excellent website MrTAToad. Thanks.

There are a lot more features and uses of GLBasic's commands than covered in the basic help file. More than a few times I've discovered them through people on the forum here. Its great that people are so helpful but a collaborative dedicated Wiki would be an excellent way to make all that knowledge easier to access. I'd definitely contribute to http://wiki.just-do-i-t.com/index.php?title=GLBasic_Wiki (http://wiki.just-do-i-t.com/index.php?title=GLBasic_Wiki) over time if there was a collective effort involved. Perhaps every time something significant comes out in the forum there could be a reminder to update the Wiki with the information? Something like that.
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-06
Hmmmm... a Wiki sounds potentially very useful indeed, but I must confess that one is depressingly empty. I mean - there is practically everything left to do!

I was having trouble with multiple sources in GLBasic, which turned out to be a combination of messy code (mine) and incomplete/inaccurate documentation. I still don't know how to change the "main" source file to be the master/main: module, but I DO know know to "add to project" a new source - creating it while a project is already open is NOT enough!
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-06
I'm working on the Wiki - at the moment, I'm detailing (in minute detail) everything in the IDE.

You can start having a look at : http://wiki.just-do-i-t.com/index.php?title=GLBasic_Wiki
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-07
Yup, nice clean start just a loong way to go. I suspect most Wiki's have a tough time starting up until they gather sufficient momentum that their progress more-or-less snowballs. It's getting that initial momentum going so that people believe in the Wiki enough to update and extend it. For example, ideally everything should be covered from at least two angles.

The IDE should be documented, obviously, but also everything in the IDE should be documented from the perspective of "wanting to complete task X". For preference the command "insert file to project" - from the context menu that comes up when you right-click the Text Editor window - should be mentioned in the section on Multiple Source Files. Because when I most need documentary help is when I have something in mind that I want to do, rather than wondering what a command I've come across does. Mostly ;)
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-07
I've added a bit about adding multiple source files to a project!
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-07
Thnaks. Tho - I can't find it! (eyesight must be worse than I knew :( )
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-07
Its in the The project maintenance area section...
Title: Re: Documentation?
Post by: okee on 2010-Sep-07
MrAToad, I'm not really familiar with the workings of Wiki systems
but is it possible for users to add comments and examples for each command ?
I like the way PHP.net has done their help system

http://www.php.net/manual/en/language.variables.scope.php (http://www.php.net/manual/en/language.variables.scope.php)
also the ability to type a command after the url brings you to
that command i.e.
www.php.net/print
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-07
All you need to do is register, and then you can edit to your heart's content
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-07
Quote from: MrTAToad on 2010-Sep-07
Its in the The project maintenance area section...

Ahh...errr... that's a pretty great example of what I was talking about wioth regard to "point of view".

I am prone to being a bore typing lots of stuff, but I have been kinda busy today so rather than bore everyone I'll wait to be asked to explain my POV, as a GLB newbie, on documentation using this specific item as a great example.

It boils down to the difference between task orientation and "what does this do?". Existing documenation leans heavily on the side of "What does this do" rather than "How do I...?"
Title: Re: Documentation?
Post by: XanthorXIII on 2010-Sep-07
I'm of the mind that documentation talks not only about the structure of the commands but also gives good examples(Read Several) of how to use that command.
Although I think the website should spruce up on the tutorials section. If anyone knows some really good tutorials. That would be awesome.

Title: Re: Documentation?
Post by: Bursar on 2010-Sep-07
It would also be useful if all related commands were listed next to each other. For instance anything relating to sprites (such as loading, displaying, rotating, collisions) should be grouped together as trying to find them in the help file is a bit of a mission.

Obviously as a newcomer around these parts, I'm expecting some flack for my next suggestion, but... maybe some of the commands in GLB should be changed. Looking at the help file I can see a rather long list of commands starting with NET. Perhaps other commands should follow suit - SPRITELOAD, SPRITEDRAW, SPRITECOLLIDE, SPRITEFREE (rather than GENSPRITE) and so-on. With a similar naming convention for other groups of commands.

It would certainly make trying to locate commands in the help file much easier, but obviously may cause some compatibility issues with existing projects!
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-07
The commands on my website are grouped into the relevent sections, but on the wiki they are just in alphabetical order.
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-07
Quote from: Bursar on 2010-Sep-07
It would also be useful if all related commands were listed next to each other. For instance anything relating to sprites (such as loading, displaying, rotating, collisions) should be grouped together as trying to find them in the help file is a bit of a mission.

Yes, definately, but not just commands IMHO.

The Wiki isn't MrTAToad's baby, it was produced by someone else as a place for the GLBasic community to adopt. It'll only work if WE piut the effort in to learn how to edit the Wiki and add a bit each ourselves, IMHO. WE can make it what we want.

It'll be a bit sad if only newbies ever edit it, but on the flip side - who knows the documentation is lacking more than a newbie struggling to find his or her way? Who best to fill in each gap in documentation as it comes along than someone to whom that revelation is fresh? Wikis live or die by their user base. Either we make it good and helpful, as a large group, or we individually wait for Kitty Hello and MrToad to do all the work (ish).

Alternatively, if the BLBasic gurus could edit the Wiki to add an explanation instead of putting their answers here, and then link to the relevant page in the Wiki, that might kill two birds with one stone - albiet being harder work for the Gurus might mean they feel less inclined to answer :(
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-07
I would like to more or less transfer everything from glbasic.un-map.com to the wiki - it would make editing and changing things so much easier :)
Title: Re: Documentation?
Post by: okee on 2010-Sep-07
MrTAToad I'm willing to help, although still getting used to GLBasic i do know basic very well
Could start on the string commands with a few examples for each command.
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-07
Quote from: MrTAToad on 2010-Sep-07
I would like to more or less transfer everything from glbasic.un-map.com to the wiki - it would make editing and changing things so much easier :)

That sounds like an eminently sensible starting place, and something that anyone should be able to help with, given a few minutes to get to grips with "How to edit the Wiki" (I imagine). I don't do a lot of Wiki editing but - how hard could it be?

Quote from: okee on 2010-Sep-07
MrTAToad I'm willing to help, although still getting used to GLBasic i do know basic very well
Could start on the string commands with a few examples for each command.

I think any and every help would/should be appreciated.

I wonder - should we just try to copy stuff across, amending where we feel able, or should we follow okee's example and pick some specific area to help out in, announcing it in this thread?
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-07
If people want to start adding examples then they can...

If you want to add a command, then take it off my website, and slightly format it for Wiki use - you'll see the current layout I use if you look at one of the commands
Title: Re: Documentation?
Post by: monono on 2010-Sep-07
Great idea! I´m in! Also I never worked on a wiki before.
I am using MrTAToad´s homepage and the online help intesively, because the commands are in a alphabetic list.
Maybe we have to discuss what examples are used per command. Sometimes the examples in the offline help are overwhelming for a beginner. For me it would be nice always to have one minimal and one more complex example.
If MrTAToad would start transfering his stuff, that would be a good start for people to add.
Title: Re: Documentation?
Post by: ampos on 2010-Sep-07
I am one that likes to start with a language reading all the commands, from A to Z, but I encounter very anointing not to find such document.

The chm file seems to be a bit outdated, and to read online, pressing back and forward is a thing I do not like.

...
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-07
Quote from: ampos on 2010-Sep-07
I am one that likes to start with a language reading all the commands, from A to Z, but I encounter very anointing not to find such document.

The chm file seems to be a bit outdated, and to read online, pressing back and forward is a thing I do not like.

...

You will probably find Mr TAToad's web page (http://glbasic.un-map.com/ - also linked in my sig) to be more your liking for the moment, although if you could add each command to the Wiki as you read it might help embed the command in your memory AND help build the Wiki up to serve us all better in the future!

For my part I've made a very basic start on the reverse type of documentation (starting with a task and explaining how to achieve it, rather than documenting the IDE or the commands like a list of parts) with a "Managing Files" section. There's dummy lines and stuff left out, it's just an example to get feedback before I put too much effort in when I should probably be reading the GLBasic tutorials :)

Comments, even criticisms, welcome - to help guide me. I would intend, ideally, to use images (screen captures, possibly even .GIF files to animate specific actions) to help illustrate GUI elements, and probably be more in depth about what tab of which GUI element needs to be active.
Title: Re: Documentation?
Post by: okee on 2010-Sep-07
Just an idea, in the help files for each command the details are given
and below every example is a REFS to other commands that are in the same category
i.e.


Code (glbasic) Select
LEFT$()

a$ = LEFT$(text$, count%)
Returns a string that cuts text$ after count% characters from the left.

STDOUT LEFT$("ABCDEFG", 3) // "ABC"

Refs:
MID$(), RIGHT$()


I think it would be more useful to give a small description of the REfs commands i.e.

Code (glbasic) Select
LEFT$()

a$ = LEFT$(text$, count%)
Returns a string that cuts text$ after count% characters from the left.

STDOUT LEFT$("ABCDEFG", 3) // "ABC"

Refs:
MID$()        Extract one or more characters from a string
RIGHT$()      Return characters from the right-hand side of a string
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-07
+1
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-07
From the web manual, the tutorial "The First Game" tells you to compile and run this code:

Code (glbasic) Select
// --------------------------------- //
// Project: OneMore

DIM playfield[10][10]
level = 0

// Main game
main:
MOUSESTATE mx, my, b1, b2
PRINT "<=", mx, my-8
SHOWSCREEN
GOTO main
END


This will not compile, much less run, issuing these errors instead:

*** Configuration: WIN32 ***
precompiling:
GPC - GLBasic Precompiler V.8.044 SN:fa03fc9b - 2D, WIN32
"OneMore.gbas"(23) warning : probably unassigned variable : mx
"OneMore.gbas"(23) warning : probably unassigned variable : my
"OneMore.gbas"(23) warning : probably unassigned variable : b1
"OneMore.gbas"(23) warning : probably unassigned variable : b2
"OneMore.gbas"(18) error : variable is not explicitly defined : playfield


unassigned variables shouldn't be a major problem (but they arren't declared anywhere?), but does DIM not define playfield?
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-07
People can fill that in as we go along...
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-07
Quote from: Cliff3D on 2010-Sep-07
From the web manual, the tutorial "The First Game" tells you to compile and run this code:

Code (glbasic) Select
// --------------------------------- //
// Project: OneMore

DIM playfield[10][10]
level = 0

// Main game
main:
MOUSESTATE mx, my, b1, b2
PRINT "<=", mx, my-8
SHOWSCREEN
GOTO main
END


This will not compile, much less run, issuing these errors instead:

*** Configuration: WIN32 ***
precompiling:
GPC - GLBasic Precompiler V.8.044 SN:fa03fc9b - 2D, WIN32
"OneMore.gbas"(23) warning : probably unassigned variable : mx
"OneMore.gbas"(23) warning : probably unassigned variable : my
"OneMore.gbas"(23) warning : probably unassigned variable : b1
"OneMore.gbas"(23) warning : probably unassigned variable : b2
"OneMore.gbas"(18) error : variable is not explicitly defined : playfield


unassigned variables shouldn't be a major problem, but does DIM not define playfield?

How DIM is used was changed a fair while after that tutorial.  Howadays, in order to make sure it complies with explicit declarations, you need something line :

Code (glbasic) Select
LOCAL playfield%[]; DIM playfield%[10][10]
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-08
Quote from: MrTAToad on 2010-Sep-07
How DIM is used was changed a fair while after that tutorial.  Howadays, in order to make sure it complies with explicit declarations, you need something line :

Code (glbasic) Select
LOCAL playfield%[]; DIM playfield%[10][10]

I added:

Code (glbasic) Select
LOCAL playfield%, level, mx, my, b1, b2

and now get these errors:

compiling:
C:\DOCUME~1\Cliff\LOCALS~1\Temp\glbasic\gpc_temp0.cpp: In function `int __GLBASIC__::__MainGameSub_()':
C:\DOCUME~1\Cliff\LOCALS~1\Temp\glbasic\gpc_temp0.cpp:93: error: no matching function for call to `DIM(DGNat&, int, int)'
C:/Program Files/GLBasic/Compiler/platform/Include/glb.h:794: note: candidates are: void __GLBASIC__::DIM(__GLBASIC__::DGIntArray&, DGNat, DGNat, DGNat, DGNat)
C:/Program Files/GLBasic/Compiler/platform/Include/glb.h:795: note:                 void __GLBASIC__::DIM(__GLBASIC__::DGNatArray&, DGNat, DGNat, DGNat, DGNat)
*** FATAL ERROR - Please post this output in the forum
_______________________________________
*** Finished ***
Elapsed: 1.8 sec. Time: 23:02
Build: 0 succeeded.
*** 1 FAILED ***


This typifies why I started this thread. It's hard to learn from documentation when the documentation is wrong :(

(I was returning to the tutorials to learn about GLBasic, but instead I'm having to learn how to correct the manual so that I can learn from that?). This is now newbie-friendly :(
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-08
The error message is ambigious here unfortunately.

You have defined playfield twice - once as an array and once as an integer, hence the error message.

However, I dont get that - I get : warning : variable already exists : playfield
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-08
ok -
Code (glbasic) Select
LOCAL playfield%[], level, mx, my, b1, b2 makes it work. So far :)

At: http://wiki.just-do-i-t.com/index.php?title=Variables could we have the variable types "sized" (eg accuracy and memory usage)?
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-08
Thats good!
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-08
I tweaked your IDE page, you should review that.

I am working on documenting tutorial 10 as I go through - I am concerned that this Wiki is not flexible enough to format things well e.g. no {code}{/code} equivalent. Do we need to look elsewhere BEFORE we put too much effort in?
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-08
There is

<source lang=glbasic>
</source>

for large bits of code.
Title: Re: Documentation?
Post by: okee on 2010-Sep-08
Also the font for the examples is very small, can that be easily adjusted ?
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-08
Not that I know of
Title: Re: Documentation?
Post by: Moru on 2010-Sep-08
Quote from: okee on 2010-Sep-08
Also the font for the examples is very small, can that be easily adjusted ?

If you are using Opera you press the + key on the numpad. Firefox you hold ctrl and press + on the normal keypad. Internet Explorer you hold shift or control (forget which one) and use the mousewheel.
Title: Re: Documentation?
Post by: Moru on 2010-Sep-08
Great work on the wiki!

For those that wants to help but don't know how, there is help on the official page of mediawiki:

http://www.mediawiki.org/wiki/Help:Formatting
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-08
Quote from: MrTAToad on 2010-Sep-08
There is

<source lang=glbasic>
</source>

for large bits of code.

Thanks, that's mostly an improvement - though light grey text on a white background (for keywoards) isn't the easiest combination to read, at least the code now stands out from the "chatty" text. I'll aim to do Tutorial 10 today, if I can, then perhaps go back to #1-9 if I get done.
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-08
Quote from: Cliff3D on 2010-Sep-08
ok -
Code (glbasic) Select
LOCAL playfield%[], level, mx, my, b1, b2 makes it work. So far :)

At: http://wiki.just-do-i-t.com/index.php?title=Variables could we have the variable types "sized" (eg accuracy and memory usage)?

It turns out that the code needed to be:

Code (glbasic) Select
GLOBAL  playfield%[], level
LOCAL mx, my, b1, b2, mousefree

DIM playfield[10][10]


I've updated the whole tenth tutorial now, fixing as I go along. I think in future it'll be easier to add to the Wiki if I'm not both trying to learn the product AND correct the tuorials (I'm starting to feel like a troublemaker pointing out the dozens of flaws in every nook and cranny). So tutorial 1 looks appealing to me for my next task.

Please check the new verison of tut #10 at:

http://wiki.just-do-i-t.com/index.php?title=10_The_First_Game (http://wiki.just-do-i-t.com/index.php?title=10_The_First_Game)
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-08
It's me again :D

I've made a start on the first tutorial, at http://wiki.just-do-i-t.com/index.php?title=01_General (http://wiki.just-do-i-t.com/index.php?title=01_General) but I'm not sure about the section on variables any more, having read http://wiki.just-do-i-t.com/index.php?title=Variables (http://wiki.just-do-i-t.com/index.php?title=Variables) (which I'm about to edit, I think). IMHO http://wiki.just-do-i-t.com/index.php?title=Variables (http://wiki.just-do-i-t.com/index.php?title=Variables) is quite unclear about the size of the variables on all platforms, and what can actually be done with them (as in " most operations except for +, -, * and /" does not feel very inclusive).

Maybe I should use the term "Native variable types" or similar in tutorial 1?
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-08
with short, char etc, you cant use mathematical calulcations on them yet (you get compiler errors).

From the quick test I have made, they seem to work in commands okay
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-08
Has anyone got "OneMore" from the GLBasic tutorials working? I'm obviously close, but there's a subtle bug somewhere that means a new level is never started. Also, BLENDSCREEN doesn't work on my netbook :( (I just get the normal black background).

I remeber now why I ditched the tutorials in the first place and opted for just diving in and doing some coding towards what I wanted to write!
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-08
Where is the "OneMore" tutorial ?
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-08
Current HTML manual version (doesn't compile):

http://www.glbasic.com/xmlhelp.php?lang=en&id=130&action=view (http://www.glbasic.com/xmlhelp.php?lang=en&id=130&action=view)

Updated Wiki version (that I can't seem to knock the kinks out of - we never can reach the second level):

http://wiki.just-do-i-t.com/index.php?title=10_The_First_Game (http://wiki.just-do-i-t.com/index.php?title=10_The_First_Game)

I might have another go at it anon, but right now my wife's urging me to play zuma or work on the .OBJ reader code, because fixing up what I'm meant to be learning from is just frustrating me too much!
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-08
It was easy enough to get the original working :)

It was written ages before explicit declarations were added, and thus no global variables were defined...

Quote(that I can't seem to knock the kinks out of - we never can reach the second level):

Me neighter - too hard for me :)
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-08
I can see/get that - but IMO documentation is almost as important as the thing itself. It's what welcomes new customers - new features are GREAT (and i really appreciate extended types, for example) and extras written in the base language itself too, but they are all for existing users surely - what's dragging the new punters in to GLBasic rather than python, darkbasic pro, freebasic etc.? Because I have to admit that I'm seriously considering abandoning the tutorials as being a much harder entry to GLBasic than simply diving in heads first and bugging you when I need  feature I can't see!
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-08
Just take your time, and you'll get through the tutorials :)
Title: Re: Documentation?
Post by: Wampus on 2010-Sep-08
Most new comers to GLBasic will almost certainly want a first-game tutorial. That's exactly where I started and what got me hooked. I can see where Cliff3D is coming from. Once my first iPhone game is complete and I've done my entry for the NES/SNES competition I want to put in some decent time trying to promote GLBasic somehow. Perhaps another tutorial that has some feature that people find attractive would be helpful.

The more people using GLBasic the better for all of us (I think).
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-09
Trouble is few people can spend time updating documentation - and it can take ages :)
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-09
That it does! But I'm generally of the opinion that the more users, the better!
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-09
I've read in documentation today both that the default number type in GLBasic is Integer (so you have to include a decimal point in a number to force floating point math) and Floating Point (so you have to use the Integer term to force Integer math).

Can anyone clear this up for me so I don't make bad tutorials?
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-09
It would depend on the variable type used :

Assigning a floating-point figure to an integer cuts off (and rounds down) the number to an integer

Assigning an integer to a floating-point variable converts the integer to a decimal number

The problem occurs when mixing the two and storing into an integer - if you not careful any decimal numbers would be converted to integers during the calculations, and thus you end up with strange results.

By default, if you leave the % symbol off, you will be using floating-point variables...
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-09
So...the default type of variable is a float and the default type of calculation is integer??
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-09
Not quite - the default variable is floating point and the default result is floating point too.
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-09
Quote from: MrTAToad on 2010-Sep-09
Not quite - the default variable is floating point and the default result is floating point too.

Umm - I'm trying to get a nice clear consistent picture so that any references I make (or copy) in the Wiki are as clear and accurate as possible. This link from the manual:

http://www.glbasic.com/xmlhelp.php?lang=en&id=255&action=view (http://www.glbasic.com/xmlhelp.php?lang=en&id=255&action=view)

and specifically quotes like this:

QuoteTo force calculations to be done as a floating point calculation, add a ".0" to the end of any number typed into your code that you wish to be interpreted as a floating point number.

which I was reading as indicating that the default calculation/result type was integer, unless something specifically denoted floating point (like a trailing .0). I'm just getting a slightly confused "vibe" I guess :( hopefully - having worked out tutorial 10/OneMore to my satisfaction, I'll manage some tutorial 1 editing in the Wiki today :)
Title: Re: Documentation?
Post by: mahan on 2010-Sep-09
I'm a newbie in GLBasic so correct me if I'm wrong but:

Adding .0 after plain numbers/constants in the source, tells the compiler to treat this number/constant as a float variable.

The compiler (if it behaves like most other compilers, which I suppose since it's a precompiler for C(++)) expands expressions to the highest precision and does the calculations from there.

Test this:

Code (glbasic) Select

STDOUT (10/3)
STDOUT "\n"
STDOUT (10.0/3)
STDOUT "\n"
STDOUT (10/3.0)
STDOUT "\n"

KEYWAIT


Hope this somewhat clears the matters up.

EDIT: to run this go to menu Project-Options and check the "Console" checkbox.
Title: Re: Documentation?
Post by: MrTAToad on 2010-Sep-09
Ah - good examples there...
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-09
Yup, it's showing exatly what I was talking about - GLBasic assumes both constants to be integer and/or performs integer math on them UNLESS there is an explicit "float" instruction (in the form of a decimnal place).

Working on transferring and updating bits of manual to the Wiki, I had come to this phrase:

QuoteWhen you create a variable for the first time (e.g. using LOCAL/GLOBAL command, or at the time of first use) you can append a '%' character to its name to indicate that this variable is an integer number. (An integer is a number without a fraction part). Appending an optional '#' will make the variable a floating point number (one with a fractional part). The appendices ('%' or '#') are optional for further use of the variable.

*Note*
GLBasic uses floating point numbers by default. Thus, if you wish to perform integer only calculations, make sure you use the function INTEGER().

(first paragraph included for context only) which felt... inaccurate. I am trying, in my own way, to try and reduce the inaccuracies in the documentation as I copy over, changing programs and text to reflect the "now" rather than the "then" of when the posts were made (so that programs compile and run, for example). I have already reworded the line to ommit the comment that floating point numbers are used by default and you must force the use of integers as that's not entirely accurate, but have left the info about how to use the INTEGER keyword.


Or, to put it another way - run away, run away!! ;)

Title: Re: Documentation?
Post by: mahan on 2010-Sep-09
If you omit the % or #, the compiler assumes a float-variable. (this is a difference to many other basics out there btw.)

Another important thing in the context is that, while % or # in subsequent usage (after the declaration is done) is optional, the $-sign after string variables is NOT optional iirc.

This is because $ is expanded by the precompiler to "_Str" in the intermediate C(++)-format and thus using the same name without the $ refers to a different name on that level.
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-09
Quote from: mahan on 2010-Sep-09
If you omit the % or #, the compiler assumes a float-variable. (this is a difference to many other basics out there btw.)

Yup - if that were reversed then it would all feel more logical/consistent to me. Oh, and as a by-product thousands of programs would no longer compile correctly, or would fail during execution, because of the (purely hypothetical!) change. The main thing seems to be "be careful out there" ;)
Title: Re: Documentation?
Post by: Cliff3D on 2010-Sep-09
Quote from: Ocean on 2010-Sep-09
Quote from: Cliff3D on 2010-Sep-09
"be careful out there" ;)

Hill Street Blues fan by any chance?

I watched it a time or two, back in the day :)
Title: Re: Documentation?
Post by: Ian Price on 2010-Sep-09
The whole float/integer thing has caught me out a couple of times too. It's odd, but you get used to it. Eventually :P