User Guide Complete! (well, almost)

BlitzMax Forums/BlitzMax Programming/User Guide Complete! (well, almost)

Hello everyone. I have been working on a user guide for a little while now and I've done about as much as I can do. I did it as both a service to the Bitz community and as a learning tool (I learned quite a bit as I was testing things along the way).

There are still some parts that are unfinished, and I'm quite sure there are some parts that are incorrect or need some additional information, but overall I think it is a good start.

If anyone is interested, it can be found here:
http://www.geocities.com/amiga5k/BMGuide.zip - RTF format (37k)
http://www.geocities.com/amiga5k/BMGuide2.zip - SXW format (41k)

(.sxw is the original. This is the OpenOffice.Org format {a FREE suite of programs similar to Microsoft Office})

Anyway, everyone is welcome to add, change, convert the documentation.

Please have a look and let me know.

Thanks,
Russell

Nilium

Couldn't you have just put them both in the same archive? :P

Uber Lieutenant

Quiet, fool. 56kers are still among us. Even they have problems with text files :D

FBEpyon

Nice dock, but it would be better if it was in a orderly HTML format or something so you could have quick links...

Nilium

I am a 56ker -_-

Russell

FBEpyon, I can output it in html if you like. OpenOffice.Org even exports in Adobe Acrobat! Hyper links were/are on the drawing board (linking to its reference in the reference section when complete).

Ok, I also now have a pdf version:
http://www.geocities.com/amiga5k/BMGuide.pdf

..and an html version:
http://www.geocities.com/amiga5k/BMGuideWEB.zip
(This is plain text HTML with no hyper links as yet. Have fun!)

It's not perfect (by a long shot!), but I thought someone might find it useful, or want to use it as a starting point for an even better User's Guide since BMax's isn't that great at all (in fact, honestly, it's quite pitiful).

Hopefully this will be addressed in the NEAR future.

Thanks,
Russell

Robert

Give this man a medal :)

This is excellent work Russell - I suggest that Mark incorporates it into the official BMAX help once you have filled in any missing sections. The Language reference provided is very much a techie document, this guide is the kind of 'hold your hand' one which will be very useful for newcomers.

I'll post any errata here if I find it:

Edit:

1) Guide says Double vars are slower than Floats, according to Mark this is not true since the CPU uses 80-bit precision internally for all float calculations.

2) A String is not a native type, it is actually a decendant of the Object type which just happens to be defined for you. Float or Double would be a better example of a native type.

3) Arrays are not 'native' variables, they are also a kind of Object. The difference is that there is special support for them within the compiler.

4) .length should be used rather than SizeOf to get the length of a string, since SizeOf in most languages, and in most other cases refers to the size of the type, not the data it holds.

Beaker

It's a pretty good beginners guide. I presume that is your target audience?

Russell

Hi, Robert and thank you for your kind words. Yes, I definitely wrote this for the beginner as such a 'hold your hands' document hadn't been shipped with the product as yet.
On your points (and there are actually many more, I'm sure ;):
1) My bad. Will be changed!
2) I guess native is not the best term to use. Perhaps 'built-in' would be more accurate?
3) Same point as number 2. If floats and doubles have built-in functionality, maybe they can really be considered objects as well.
4) I assume you're referring to this section:

What If we wanted the length of a particular element? It wouldn't make sense to get the length of an integer arrays's element, since all integers are the same length. For strings, though, we may want to know how many characters are in a particular element:

Local A_String:String[3] = ["Here's","a","string"]
Print A_String[2] ' Prints 6

If you want to know the length in bytes of used memory for a variable, use the SizeOf() function. Look at this example:

a:String = "Hello"
Print SizeOf(a)

In the line 'Print A_String[2] ' Prints 6' I forgot to put the '.length' after it. This will be fixed. But otherwise, I actually was trying to explain the difference between SizeOf() and .length.

Would someone like to volunteer to write maybe one or two sections in the same hand-holding style - assuming NO prior programming knowledge? What I'm looking for is not a one or two sentence description, but a real 'this is what it is, does and looks like. And this is why you would use it' type of explanation. Examples of their use would also, of course, be a great help!

The Array section needs to be written (I wrote one, but then had to 'go back to school' on the subject myself! (How embarrassing! - But, an excellent learning experience as well).

The graphics section is quite skimpy...not to mention the non-existant sound section (Not my specialty...)

Anyway, just let me know if anyone would like to submit a section!

Thanks in advance,
Russell