IonicWind Software

Larry McCaughn has come up with some great suggestions and more important much needed help for documenting Aurora.

He has produced very complete sets of html files for individual non-class functions (133 files not including the .css file) and for class methods (413 files not including the .css file).  All of these htmls will require filling in.

The target for Larry's work is a "Programmer's Reference for Aurora" document.  He will be using a tree like structure to associate/group functions/methods.

The Aurora Help I've been working on up to now will be renamed and take on more of a "Guide to Programming in Aurora" approach and will benefit greatly from Larry's hard work.

To speed up implementation of the Reference document, we are looking for people to help fill-out the function/method htmls.  Larry and I have hashed out a standard form so everything will be uniform and consistant.   If a number of people volunteer to work on a handful of functions and/or methods, the process can be rather quickly.

Volunteers: 
Please post here if you would like to join the team.   In your post please note which functions and/or methods you wish to handle.   With Paul busily writing compiler and parser code, he won't be able to directly write docs but he will be available to answer specific questions regarding specific functions and/or methods.

Thank you in advance.

I will start out by taking the all Math Functions and the String Functions.

Who's next ;)

John,
I'm working on the class overview template design.

I still have the following templatesÂÃ,  to do:
ÂÃ,  structures
ÂÃ,  constants
ÂÃ,  messages
ÂÃ,  flags
ÂÃ,  datatypes

The class overview will take a day or 2 and I should be able to knock out the others before the beginning of next week.

John, I believe the title of this topic is most appropriate:

Programmer's Reference and Guide to Programming

I see it being one document with 2 major sections.ÂÃ, 
Like I said, I'll do a little TOC and let you see what you think.ÂÃ,  If you think it would look better after that then it's no problem to split.ÂÃ,  But together you can easily link the guide part to the reference part thus letting the user go as deep as they are comfortable with, at any given time.

Consider the math functions you are working on.ÂÃ, 
IMO, there should be the overview page that says the math functions exist and list them in groups with maybe a one or 2 line summary of what the group does and something like "sin - sine of angle" for each one.ÂÃ,  "sin - sine of angle" would be a link to the individual sin template file.

Also in the function templates there is no need for any clarification of what 'int', unsigned int', 'float', etc. mean.ÂÃ,  That information would be covered in a section covering 'data types'.ÂÃ,  The templates should be as clutter free as possible and still covey the necessary information.
Again, that's just my opinion.

Single document it is then:  'Aurora's Programmer's Reference and Guide to Programming'

We are pleased to submit for your viewing pleasure the 1st version of theÂÃ,  ÂÃ, Guide to Programming and Programmer's Reference.

All of the 600+ templates are included along with some rough place holders in other areas.ÂÃ,  Any and all comments and/or suggestions are welcomed.

What we need now are volunteers to fill in the blanks.

If you are willing to help you can do so by way of the following:

Download the help file and look through it.ÂÃ, 
Any page(s) you are willing to edit can be retrieved simply by right clicking the page and saving it to your computer.
Do not change the name of the file.
After you have finished editing, zip the file(s) and post them back to the forum.

NOTE:ÂÃ,  Before you start editing any pages you should announce it on the forum to prevent duplicate effort.

The Development Team

Help file updated due to missing string function page.



[attachment deleted by admin]

For those new to Aurora: The string functions listed in this documentation are obsolete and will be removed at some point, so don't use them. There are new functions listed in the strings.inc file in the bin directory, you can use that as documentation until this gets updated.

Edit: Nevermind, just don't start using the functions with a $ suffixed. Those should be marked obsolete and possibly removed from the documentation, they're only provided now so you can convert little by little.

And here is the completed type constant list:

TYPE_NONE    0       Used internally by the compiler to represent a void return type
TYPE_STRING    0x01   Represents the string data type, which is currently a fixed length, null terminated byte array (length 255)
TYPE_BYTE    0x02   Represents the byte data type
TYPE_WORD    0x03   Represents the word (16 bit integer) data type
TYPE_INT    0x04   Represents the int (32 bit integer) data type
TYPE_INT64    0x05   Represents the int64 (64 bit integer) data type
TYPE_FLOAT    0x06   Represents the float (32 bit floating point number) data type
TYPE_DOUBLE    0x07   Represents the double (64 bit floating point number) data type
TYPE_USER    0x08   Represents a user defined type, see struct
TYPE_VPARAM    0x09   Used internally by the compiler to represent variable length arguments
TYPE_DATABLOCK    0xA       Used internally by the compiler to represent a block of data statements
TYPE_POINTER    0xB       Represents the generic pointer type, equivalent to void* type in some cases
TYPE_HEAP    0xC       Represents the heap type for function returns, meaning that the compiler will free the memory returned after it is used. Functions returning the heap type must allocate memory first using the heap functions
TYPE_DSTRING    0xD       Represents the dstring (dimensioned string) type, similar to a byte array, but allowing assignment and comparison like a standard string
TYPE_UNSIGNED    0x00010000   For integer types represent an unsigned quantity

Thanks, Parker

How about filling out a couple hundred of the templates in your spare time! ;D
Larry

;D Yes, I'll do some more of them when I have time.

An updated version of Aurora Help has been posted to the forum at the following

http://www.ionicwind.com/forums/index.php?topic=431.msg3750#msg3750

This update adds 103 pages in support of Paul's posting of A;pha 2 Rev 10 to the forum.

It also adds a little color to some of the help pages.

Larry

Okay, I've got a few comments (mostly mistakes I think):
- Data Objects (...) says that variables can contain any non-punctuation character except _, it should say "can contain any alpha-numeric character and the characters _, $ and @" and note that _ by itself is not an acceptable identifier, and $ and @ cannot be the first character.
- CONST DataType aConstantVariable = xxx; is not supported (yet?). You can only make integer constants, using the form const x=y; where y must also be a constant (number or variable declared with const). Also the form #define x y is equivalent.
- My first program:

QuoteThe keyword 'global sub' tell the compiler and linker that a subroutine named 'main()' is to be compiled and it is to be 'global' (visible) to all other subroutines (if any).

It doesn't mean visible to all other subroutines, it means to any other files. And you may note that main must always be global even if you have only 1 file in the project, because Aurora's runtime library calls it.
- I like these two: "Aurora can use pointers." "Aurora can use arrays." ::)
- Some structures (all?) have two opening braces instead of one opening and one closing. For example
struct _linked_list
{

_linked_list  *pNext   Description goes here
_linked_list  *pPrev   Description goes here
pointer  pData   Description goes here

{

Here is another list of constants (my first one hasn't been filled in yet)
MODE_READ  0x0001 Used to specify reading access on the file.
MODE_WRITE  0x0002 Used to specify writing access on the file, note that the contents will be erased.
MODE_APPEND  0x0004 Used to specify writing access on the file, but the previous contents will not be erased.
MODE_CREATE  0x0008 Used to specify that the file should be created if it does not yet exist.

Parker said:

QuoteYou can only make integer constants, using the form const x=y; where y must also be a constant (number or variable declared with const). Also the form #define x y is equivalent.

Are you saying that

Quoteconst x=y;

is the same thing as

Quote#define x y

I was under the impression that

Quote#define x y

could take on the form of

Quote#define x y+2-z

and a const couldn't.

Parker also said:

QuoteHere is another list of constants (my first one hasn't been filled in yet)
MODE_READÂÃ,  0x0001 Used to specify reading access on the file.
MODE_WRITEÂÃ,  0x0002 Used to specify writing access on the file, note that the contents will be erased.
MODE_APPENDÂÃ,  0x0004 Used to specify writing access on the file, but the previous contents will not be erased.
MODE_CREATEÂÃ,  0x0008 Used to specify that the file should be created if it does not yet exist.

That's easy to fix.ÂÃ,  Right click on the page the info belongs on; view source; and save to your desktop.ÂÃ,  Edit the page till it looks just like you want it. Zip it and post it to the forum.ÂÃ,  I'll be happy to insert your corrected page into the next update.

I can't speak for John but I guess what I'm really saying is that some things I will fix for others.
The bottom line is I don't want to be anyone else's clerk typist any more than the next person does.

Thanks for proof reading the docs Parker.  I copied the text and saved it. 
I'm hoping to be finally caught up with work and school by the end of next weekend.  I got way behind after my wreck in January.  I've been trying to catch up for the last couple of weeks.  It has forced me to mostly put aside Aurora stuff and only pop in the forum once in a while.

John

const can use basic math operators too.

the compiler converts

#define x y+z-3

to

const x = y+z-3;

Since they are both compile time constants any identifiers must also be constants.

#define WM_USER 0x400
#define WM_MYMESSAGE WM_USER+1

Will work of course

int SomeValue = 100;
#define BLAH SomeValue+1

Won't work since the compiler doesn't know what the result of a variable is at compile time.  In fact SomeValue doesn't have a value until runtime.

Get it?

The catch Parker made on the {} in structures has been fixed.

Thanks for clearing me up on the const/define thing Paul.

Larry

Help file update.

Massaged entry names in TOC for class methods (weren't consistent)
Added 'purpose' descriptions to all constructor and destructor methods.
Added cross reference 'See ALso' links for all constructors that had a corresponding destructor and vice versa.

Original download link
http://www.ionicwind.com/forums/index.php?topic=431.msg3750#msg3750

Larry

An updated version of Aurora Help has been posted to the forum at the following

http://www.ionicwind.com/forums/index.php?topic=431.msg3750#msg3750

This update is in support of Paul's posting of A;pha 2 Rev 11 to the forum.

The help file now contains 941 pages and 6,569 internal links.

Larry

An updated version of Aurora Help has been posted to the forum at the following

http://www.ionicwind.com/forums/index.php?topic=431.msg3750#msg3750

This update is in support of Paul's posting of A;pha 3 Rev 0 to the forum.

This update includes the basic help file and the separate dx2d help file.

Larry

An updated version of Aurora Help has been posted to the forum at the following

http://www.ionicwind.com/forums/index.php?topic=431.msg3750#msg3750

This update is in support of Paul's posting of A;pha 3 Rev 2 to the forum.

This update includes the basic help file and the separate dx2d help file.

Larry

Now I'm going to sound a bit like Jerry - and I don't know if it was suggested yet - but how about a wiki? I think a wiki would provide more rich and organized help, if everyone makes an effort. Then the offline helpfile could be filled from it...?

EDIT: I found two threads that mentioned it in the general forum. Did the idea ever move forward?

Larry has a database based program that we will be using to fill in the pages through collaboration.  The program can generate the .chm/.html/whatever on the fly.

It's never the same thing as online documentation, though... Look at the php documentation, for example. I think it's the best documentation I ever used. The users can add to each page, so there are tons of clarifications and sample code that are not even part of the original documentation. All of this is moderated, of course. I understand the need for a real help file, but having something that can be changed by anyone and accessed directly without the need of compilation or downloading/uploading would be good too. You could restrict the editing of articles to those who own a license to Aurora...

Another language I use has a wiki that users can edit, and a utility that generates a chm file out of the wiki pages.

It was tried with IBasic and never took off, remember the IBasic Wiki?  Jerry closed it after years of inactivity. 

With only 129 current forum members I don't think Aurora has ther user base just yet to make a wiki more than a curiosity.  Once we get the database filled in then we can look at exporting to a wiki.  But for now it will be up to me to document the code that I am writing, as it should be.

An updated version of Aurora Help has been posted to the forum at the following

http://www.ionicwind.com/forums/index.php?topic=431.msg3750#msg3750

This update is in support of Paul's posting of Alpha 3 Rev4 to the forum.

This update includes the basic help file and the separate dx2d help file.

Larry

Hi all,ÂÃ,  :D

I've downloaded the help file and it is wonderful. A lot of hard work went into this and I am about ready to sit down and read it front to back to help me get up to speed on Aurora. Cudos! to those who've put in the time for this.ÂÃ,  ;)

Vikki

It is just a skeleton, but will give you a general overview of what is currently in the language.

Welcome back, Vikki.

An updated version of Aurora Help has been posted to the forum at the following

http://www.ionicwind.com/forums/index.php?topic=431.msg3750#msg3750

This update is in support of Paul's posting of Alpha 3 Rev5 to the forum.

This update includes the basic help file and the separate dx2d help file.

The tutorial is now included in the main help file.

Larry

Skeletons are good. :)

Thanks Bruce!;)

It's this help file up to date? it haves  some Classes that don't appear on the "official" help file (CWebBrowser,  for example,  are very cool  ;D)