OxygenBasic formal documentation

[JRS]

I would like to open a discussion on how we can help OxygenBasic with it's documentation efforts. Do we have members of this forum that enjoy creating technical documentation? Jose Roca said it best that no one is going to take O2 seriously unless a better job at documentation is achieved. I think it's unfair to ask Charles to create an outstanding BASIC compiler and formal documentation for it. If this was a commercial product and Charles was getting paid, I wouldn't be writing this. This is not a one person job and everyone needs to take some ownership in the project. Any volunteers or someone willing to take the lead and build their own team?

Charles has a wiki (Mediawiki) available to users which an initial effort was started. I think the best way to document O2 is to scape the forum for code and comments and go from there with a consistent format everyone can follow.

[efgee]

Just looked at the wiki and it seems nothing was added since I touched it last.

Stopped using MS-Windows and with that all programming tools for this operating system a long time ago.
Only stopping by once in awhile to see Oxygen's progress.

Still hoping for a native Linux and OSX version...

[Aurel]

I can build documentation only for function i have made in my own awinh.inc include file
and most of them are only for win32 api wrapper( with some additions <GDI>) and put them with
OxyEdit editor...

for other things i am not sure

[Charles Pegge]

Help with documentation would be very welcome. But where to begin?

The task has to be sliced down into manageable pieces, and let it grow organically. We already have a rudimentary A..Z.

I also suggest producing it in HTML format or something that can easily be turned into on-line web pages which can also be used to produce CHM.

[Aurel]

But where to begin?

Charles i know where to begin with functions from awinh.inc
and explain each function in short...

but for other things i also don't know from where to begin

[efgee]

Here is my suggestion:

Help with documentation would be very welcome. But where to begin?

Charles,
because what I wrote is already several years old the prudent thing to do is:

1) Go through the existing wiki pages and check if some of the provided information is already obsolete.
2) Discuss if the 4 main pages  (Getting Started, Overview, Reference, FAQ) are still appropriate or more need to be added
3) Add new/missing information to Getting Started
4) Add new/missing information to Overview
5) Add new/missing information to Reference
6) Add new/missing information to FAQ
7) Add new/missing information to ...

Charles i know where to begin with functions from awinh.inc and explain each function in short...

Aurel,
If awinh.inc is part of the Oxygen package it would be good to add a subsection in Reference for all prepackaged include files and list/comment each function (including awinh.inc).
If awinh.inc is not part of the Oxygen package it could still be useful to add a Custom Include Files Section (next to the 4 main sections mentioned above) that has information about available user maintained include files, their functions commented and in addition: where this user library can be obtained (maybe not as a link only as text for security reasons - up to the wiki admin).

What do you guys think?

These are my suggestions, but as I mentioned earlier I'm not on MS-Windows anymore and didn't use Oxygen for quite awhile, someone else has to implement the changes/additions.

Have fun   

[JRS]

Let me know if the O2 wiki is the direction (Charles mentioned static HTML) and I'll upgrade the Mediawiki software to the current level. The advantage of a wiki is collaboration. If someone is leading the documentation effort and responsible be the project, a HTML version is feasible.

[kryton9]

I have been thinking about this for sometime too. I put it off because we all sort of have our own header files instead of building up uniform code libraries. We each sort of have our own coding styles too.
So what makes Oxygen so fun, its flexibility is its hindrance for documentation.

Oxygen is almost a platform for making your own language. I was even thinking of writing a spec for what I would like fixed into my own version of O2 and see if Charles could give that to me so I could develop my own version with the syntax I like and document it that way.

So perhaps should be renamed to FoundationBasic, and each Foundation could have a unique Basic built from it that is easier to document and have examples written in a uniform style?

[Aurel]

Kent
Don't get me wrong..
But do you really think that is easy to create your own version with built-in your own functions.
One thing is use your own include file and very different thing is to create your own built-in version
with predefined functions.

[Peter]

So what makes Oxygen so fun, its flexibility is its hindrance for documentation.

Hindrance for documentation.   

[JRS]

What would Christmas be without mysterious gifts?

[Peter]

I wish me further two hands. 

[kryton9]

Kent
Don't get me wrong..
But do you really think that is easy to create your own version with built-in your own functions.
One thing is use your own include file and very different thing is to create your own built-in version
with predefined functions.

That is what I miss about programming languages, like from the 1980's- all the commands were built in, nothing to import, include etc.
That is what I would like to do with O2 my version. Here is my idea:

1. Have O2 core as is currently.
2. Have O2 automatically include a file named user.inc, this would be where I would put all my code which would make all my libraries.
3. Have O2 automatically compile with the RTL and make the .exe file and auto name the .exe with the programs name.
4. I would like my Basic Case Sensitive with only the options I like instead of the many ways oxygen allows things. For example, Equates:
  def
  #define
  %
  $
I would just pick one only.

5. I would like to require () for functions and subs

There are a few more, but these are things that can be done with O2 already by issuing preprocessor commands
but I would want it limited so I could document a uniform help document to make the most of my work, so others could use it.

[JRS]

What I was pleasantly surprised by is how easy it was to port Peter's games to SB. It may be Peter's programming style that made it doable but I think it shows that Charles doesn't walk around toting a leash.

 

[kryton9]

John, yes the freedom oxygen offers is great. I am able to work on my stuff that I mentioned, using the preprocessor directives so it is not a big thing.