Oxygen Basic
Information => Reference => Topic started by: JRS on July 16, 2013, 04:07:39 PM
-
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.
-
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...
-
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 :-\
-
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.
-
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 ???
-
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 ;D
-
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.
-
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?
-
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.
-
So what makes Oxygen so fun, its flexibility is its hindrance for documentation.
Hindrance for documentation. :D
-
What would Christmas be without mysterious gifts?
-
I wish me further two hands. :D
-
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.
-
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.
-
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.
-
Hi Kent,
Be happy that we have so many things.
I hate limited programming languages, which make it impossible to write your ideas.
Kent, just take what you want, if you want to use brackets, use brackets. :D
-
One advantage of flexible syntax, I find, is porting code. A quick partial translation to get the thing working, then gradually trim off all the noisy bits and reconfigure into a structure you are comfortable with.
-
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.
Kent
This can be done if you create small builder program, something like i do in AurelBasic....
But of course little bit exetended with include file options.
And also this program must be capable to add few first lines into main code file.
-
I guess sometimes I miss the simplicity of programming from the old days too much. Do you guys remember the keyboards that had the BASIC keywords assigned to the different keys.
http://www.google.com/imgres?imgurl=http://franmarino.files.wordpress.com/2008/09/timex1.jpg&imgrefurl=http://franmarino.wordpress.com/2008/09/18/assignment-3-home-computers/&h=1192&w=1338&sz=357&tbnid=xPbBMAz4ruem2M:&tbnh=102&tbnw=114&zoom=1&usg=__BIM4HTbSo9pcooKEFNFGz3HygOA=&docid=0Pnx9XVEcVIkGM&sa=X&ei=wEbwUZKREoPQ8wSVoIGYCg&ved=0CEAQ9QEwAw&dur=670
-
It would be quite easy to make a virtual keyboard control for IDEs. Might need a few more keys than the old Spectrum, but it would be good for beginners anyway.
-
I feel we can no longer wait with an attempt at formal documentation. Charles has brought OxygenBasic to the point of a mature/flexible foundation for a BASIC compiler. Charles has demonstrated at one point or another examples that you would expect a BASIC compiler to support, and more. (64 bit, JIT, ...)
I have installed for the project when it first began Mediawki (what Wikipedia uses) to support the documentation effort. Emil took a shot at getting the ball rolling but it may have been to early in the development cycle to cast anything in stone. I feel the syntax of the language is stable/functional and a documentation effort could be started. I don't want to put any effort into a method doomed for failure so before I start working on frameworks and formats, I'm looking for feedback from the O2 team as what tool you think we should use.
-
I favour Bulletin Board Format, since we already use it abundantly :).
It is also easy to auto-translate into HTML for web pages.
-
Excellent point, nothing new to learn. I will try to find a few BB based documentation tools for us to select from.
There is a BBCode extension (http://www.mediawiki.org/wiki/Extension:BBCode) that could be added to the current O2 wiki. This would allow using either standard markup (BB or mediawiki codes) with the option to move to something else if this documentation project takes off.
-
I think the fastest/easiest way to make a dent in this is for me to write a SB script to take what documentation Charles has already created and generate the pages for the keywords. The pages will be pre-formatted with the style/theme agreed on. I will leave linking the pages together into groups for the next pass.
Here (http://www.mediawiki.org/wiki/Extension:Code) is a Mediawiki extension to add syntax coloring to the wiki pages. The best part is it's the same syntax highlighter used on this forum so the template file for O2 should be reusable.
-
If there isn't any interest by others to create formal documentation for O2, I'll take shot at on my own and see how it turns out. If you don't like the end result, don't start whining as I'm giving everyone a chance to define the path we should take with this.
-
If there isn't any interest by others to create formal documentation for O2, I'll take shot at on my own and see how it turns out. If you don't like the end result, don't start whining as I'm giving everyone a chance to define the path we should take with this.
Do you know how to create .chm file ?
Do you know how to explain to people how to create windows GUI app ?
Do you know....
Do you...
OK ...if you whish to do this just go ... ;)
PS.Do i must repeat myself again...?
I work on my chm files for GUI functions which i have created in awinh, and please stop
inputing what you whish that someone else do,ok ... :)
-
PS.Do i must repeat myself again...?
I work on my chm files for GUI functions which i have created in awinh, and please stop
inputing what you whish that someone else do,ok ...
Refresh time.
- This is the OxygenBasic open source project not the RubinDev forum. We are happy to help you with your personal projects but the focus of this forum is moving O2 along.
- Open source projects are successful if people contribute.
- I'm a facilitator and involved in multiple BASIC language projects and I don't have time to explain to you what I have been doing in this industry for over 35 years. I highly recommend you first learn English before a BASIC language if you plan on further conversations with me.
- I don't take on projects I know nothing about.
- There is time for fun and time to get serious. We are lacking on serious from most of the project members here.
-
And for what is awinh.inc than for Oxygen Basic ???
Awinh.inc don't have nothing with my hobby interpreter at all...
do you understand this ?
Ok forget... ;)
-
Aurel,
It's great that you decided to use O2 for your projects creating custom includes and tools to make your development easier. If you're saying that this is your contribution to the O2 project then you need to follow normal open source protocol to have them approved to become part of the standard distribution. Not everything posted is considered an extension to O2. Please check with Charles as to his requirements for having code contributions submitted to the project.
Thanks!
John
-
If I understand correct, you are the commander of this forum.
Aurel can do what he wants!
All is bit unfriendly here. Stay a little bit in the background with your commands.
We are all old enough.
-
If I understand correct, you are the commander of this forum.
I'm a project member just like you. I happen to have more experience than most with managing and moving open source projects along. Hence my statement of being a project facilitator. This project/forum is owned and operated by Charles. (check the WHOIS) I help out on the hosting/Linux side so Charles can focus on the compiler.
We are all old enough.
The petty name calling and disrespect for obviously seasoned members is appalling and my efforts are focused to make it stop. I'm tired of having to be a shrink for forum misfits with anger management issues that don't know when to stop.
Charles has put countless hours of effort into O2 maturing the compiler to provide us with a BASIC compiler that isn't based on QB or other outdated concepts of the past. If your interested in helping this open source project along then ask Charles what can you do based on your skill level to help. If your looking for free help and advice to move your personal projects along, don't get upset if O2 business takes precedence.
-
If I understand correct, you are the commander of this forum.
Aurel can do what he wants!
All is bit unfriendly here. Stay a little bit in the background with your commands.
We are all old enough.
Yes Peter that is true.
My work on awinh.inc is my own work and contribution to Oxygen Basic as almost
only GUI win32 wrapper for creating standard windows controls .
There is some work from Frank in that area .
Same as Peter great contribution in game and graphics includes.
So when I or anyone else want to create game i will suggest Peter sw.inc
which is great for that type of programs.
And if someone want on easy way create GUI programs i will suggest awinh.inc.
So i don't see what is wrong with my contribution here. ???
By the way i think that Charles add awinh.inc in Oxygen package .
-
Wait a minute....
John
Do you try to say that me and Peter are not welcome here
and that our contribution is useless and wrong ::)
-
Do you try to say that me and Peter are not welcome here
and that our contribution is useless and wrong
You must have been off on one of your forum pillages and missed that I have thanked Peter numerous times for his examples showing how to use O2 with his closed source library.
As far as your contributions go I hope for the best that you can stay positive and focus on one direction for more than a few days. Due to you poor English, anger issues, and insistence on using methods that have no current day relevance, I don't give your contributions a lot of thought.
-
I don't give your contributions a lot of thought.
Ok
So from your super-ultra point of view my incudes are crap and
and IUP is something spectacular- infact is just another crap to.
fine...
-
don't get upset if O2 business takes precedence.
:D
o2 is a business? I didn't know that I am employee of this forum.
As I said. very unfriendly at time. I quit my job!
Management is intolerant and arrogant. I hate these branch of industries.
-
Peter,
If you don't understand how an open source project works then spend the time looking at other successful projects. (Linux, SQLite, cURL, BaCon, ...) The other option is to go the commercial route and pay someone to take abuse and listen to your problems. With the commercial offering the concept is to make a profit and if they are large enough satisfy investors/stock holders. The open source movement isn't about the competitive side of business. It's about everyone doing their part for a common goal where everyone benefits from the results.
It's really that simple!
-
Joe (BigBass) from the BaCon forum has been documenting his efforts on SourceForge. I just revisited SourceForge's current tools since the last major upgrade. Joe's docs look GREAT!. Is this something that might work for O2?
BaCon PROTO (http://sourceforge.net/p/baconproto/wiki/Home/)
BaCon HUG (http://code.google.com/p/bigbass-porteus/wiki/BaCon)
-
He did a nice job that is for sure.
Until Oxygen is out of alpha and Charles says the internals are locked and ready to go, I don't see the point of documenting at this point.
Since it could mean a lot of refactoring.
On a side note, I have been on a mission collecting keywords from various projects to help visualize a complete language in my mind.
The main categories, sub categories within that. I have yet to nail down a complete list organized the way I want yet.
I thought I would submit that when the time is right and then we all give it a finished outline of what stays and what goes.
And then we could fill in the details.
I am still thinking of keeping all the data in a sql database and have it generate html files styled with a master css sheet.
-
Putting flesh on the bones :)
(http://4.bp.blogspot.com/-SbgYJxhzF_s/Uk2yjfosPYI/AAAAAAAACGY/EN2mp5KXyW4/s1600/codex_skeletons.jpg)
-
Looks like a mix of all the alien species putting the people together, does this mean Oxygen will have mixins (http://en.wikipedia.org/wiki/Mixin)? I could never wrap my head around how they pull that out!