Author Topic: [Controversial] Better Axe Documentation Could Be Needed (Read 18160 times)

josh landers · « **on:** March 18, 2014, 05:39:12 pm »

***I realize that this may be somewhat controversial and I wish that everyone just give thier opinions without blowing up.

As I have been going throughout this forum I see a major difference between the forum for TI-BASIC & Axe. The key is in the way people have responded to the different types of programming problems. Now I'm not saying axe parser is anything like the syntax of ti-basic, its not. What happens is the forum for tibasic need only be searched to find out how to do something. But in this forum I see a common problem with the answers people give....
1) read the manual
2) a link to something that may not even be in axe, with the promise its similar

What I find even worse than that is when someone responds with the irc chatbox and doesn't put the solution on the topic.

This all boils down to one thing.... does axe parser need better documentation. As such should we have a better command list with more details about each of the commands. Why does the community need this? Because there is always the small chance that we scare off someone who really wants to learn it but may not have the ability to access our site every day.
I urge you to repond appropriately to this thread, stay on topic, and help each other find a solution.

Hayleia · « **Reply #1 on:** March 18, 2014, 05:48:13 pm »

Quote from: josh landers on March 18, 2014, 05:39:12 pm

But in this forum I see a common problem with the answers people give....
1) read the manual
2) a link to something that may not even be in axe, with the promise its similar

Could you give examples of those ? Because I don't think I ever saw 2, and whenever I saw 1, it was not just "RTFM" but "this command is what you want (which answers the question), see the manual for more reference (not 'RTFM' but 'I can't tell you everything better than it's said, and now that you know where to look, you don't need my help anymore')".

Matrefeytontias · « **Reply #2 on:** March 18, 2014, 05:52:12 pm »

In my opinion, the current commands list is very fine, and complete enough to give you everything you need to know about Axe commands.

Sometimes, people ask questions that make me (personally) think that they never bothered trying to solve their problem with reading the command list, although I usually try to answer with clarity (I hope so at least. Not a big fan of RTFM).

Also, learning is not about getting things done by other people. If you come and say "hey I would want some code that does that", we're expecting you to be wanting to learn things, so we say "here, this algorithm is what you want, implementing it in Axe will be a good exercise and will make you progress and understand the whole thing". If we just gave you the code, well good, you successfully copied text from one place to another.

So in my opinion, if we respond like that, there's a reason.

josh landers · « **Reply #3 on:** March 18, 2014, 11:04:50 pm »

I dont want to step on anyone's toes. All im saying in a nut shell is this...
Why if the syntax for a simple command such as bitmaps not even mention that you need a header... I dont think that thats good documentation for a command.
Now I'm certain that the command list has no single mention of what you have to do to make tilemapping work... and on top of that most of the tutorials never even say that you have to use hexadecimal notation for your tilemap declaration pointer.

willrandship · « **Reply #4 on:** March 18, 2014, 11:32:42 pm »

Tilemapping isn't a mode, in that you'd have to write the routine yourself. In this regard, the lack of documentation for it is because it's not part of the language. You're not going to find official documentation on how to make gravity physics either, because they're not a built-in feature.

I would agree with you more on the bitmap command if there was actually any justifiable reason to use it. I regard it as a fairly worthless instruction, since stacking Pt-Ons is faster and the same number of bytes.

More documentation, with better details, would be better, though that can be said for many programming languages, not the least of which is x86 assembler, or, for another example, low-level openGL.

The thing about small community projects like this is that the list of people who can do the things you want is very small, and the list of people who are willing to is even smaller. If you want something changed, you'll generally have to do it yourself, since the fact that it hasn't yet been done is evidence that it's not going to happen.

TIfanx1999 · « **Reply #5 on:** March 19, 2014, 01:10:22 am »

Will is correct. There really isn't any reason the command list should include how to make a tilemap work. That's more of a general programming thing, and I know I've seen a tilemapping tutorial or two floating around here. It seems like you are more interested in general tutorials, and specifically ones that cater to AXE. Would it be nice? Yea, but then again, people need to find the time and drive to do them. We actually used to have a tutorial section... I wonder where that went.

Hayleia · « **Reply #6 on:** March 19, 2014, 02:10:20 am »

Quote from: josh landers on March 18, 2014, 11:04:50 pm

most of the tutorials never even say that you have to use hexadecimal notation for your tilemap declaration pointer.

You don't have to. You can put any part of your data between brackets, in a Data() command or between quotes (a bit harder to use, you need to know the correspondence). Usually, quotes are used for text data because it is a bit more convenient to write/read for the user writing/reading the source code. And hex is used for sprites because it doesn't take much space in the code. But you don't have to, you can declare your sprite like this if you want:
[]→°SquareSprite Data(π 11111111 ) Data(π 10000001 ) Data(π 10000001 ) Data(π 10000001 ) Data(π 10000001 ) Data(π 10000001 ) Data(π 10000001 ) Data(π 11111111 )
This is much more convenient to read (everybody can see that this is the sprite of a square), but it is a bit annoying to scroll through (even though not annoying at all with zStart's jump to label feature).

My point is that there are always an infinite number of ways to achieve one thing, so the documentation would have to cover all those ways to be complete, which is impossible. Hence why it is "incomplete".

DJ Omnimaga · « **Reply #7 on:** March 19, 2014, 02:35:37 am »

There used to be Axe tutorials in the site navigation, but now they're all scattered through the Axe sub-forum and some non-tutorial articles are no longer viewable, thanks to the upgrade. I agree with most people who replied, although I agree with Josh about the IRC/shoutbox thing, since if someone only responds there and the user doesn't notice right away, it will get lost in the logs.

josh landers · « **Reply #8 on:** March 19, 2014, 07:13:54 pm »

Ok all great points, I think that when we do have such a small community of axe users we should maximize the potential for understanding how it works. As ive thought about this alot... how about a more verbose command list.

Runer112 · « **Reply #9 on:** March 19, 2014, 08:01:38 pm »

Quote from: josh landers on March 18, 2014, 05:39:12 pm

As I have been going throughout this forum I see a major difference between the forum for TI-BASIC & Axe. The key is in the way people have responded to the different types of programming problems. Now I'm not saying axe parser is anything like the syntax of ti-basic, its not. What happens is the forum for tibasic need only be searched to find out how to do something. But in this forum I see a common problem with the answers people give....
1) read the manual
2) a link to something that may not even be in axe, with the promise its similar

I can't say I've noticed this. If people do this, then they're being somewhat rude. I certainly try not do it myself, or if I do tell the asker to look at an external resource, I tell them exactly what part relates to your problem and how. I generally see others providing helpful answers as well.

Quote from: josh landers on March 18, 2014, 05:39:12 pm

What I find even worse than that is when someone responds with the irc chatbox and doesn't put the solution on the topic.

I know I tend to try to provide programming help over IRC a lot more than on the forums. That's usually because I can quickly and interactively solve the problem with the person experiencing it, working out any issues that may arise as they come. But if you'd prefer a solution be posted on the forums, just ask! I'm sure most people would be happy to oblige.

Quote from: josh landers on March 18, 2014, 11:04:50 pm

Why if the syntax for a simple command such as bitmaps not even mention that you need a header... I dont think that thats good documentation for a command.

It certainly does:

Quote from: Commands.html

Draws a bitmap to (X,Y) on the main buffer, back buffer, or specified buffer respectively. The bitmap data should have in order: width (1 byte), then height (1 byte), then the rows of the image padded with zeros to the nearest byte. Mode 0 is "Pt-On" logic and Mode 1 is "Pt-Change" logic. Mode 0 is used if unspecified.

Quote from: josh landers on March 18, 2014, 11:04:50 pm

Now I'm certain that the command list has no single mention of what you have to do to make tilemapping work...

As others have said, tilemapping is an algorithm that a coder must implement, not a built-in feature of the language. Therefore, I wouldn't expect it to be described in the language's documentation. Also as others have said, basic tilemapping implementations are described and provided in a number of tutorials on the site. Finding them now is just a bit trickier, since the new site removed its explicit index of tutorials, which I agree is not a great situation.

Quote from: josh landers on March 18, 2014, 11:04:50 pm

and on top of that most of the tutorials never even say that you have to use hexadecimal notation for your tilemap declaration pointer.

You don't have to use a hexadecimal string to include data, but it's certainly an easy way. The hexadecimal data inclusion syntax is present in the command list, and it appears in numerous fully-explained code examples in the documentation (Documentation.pdf). Also included and documented in both is another common way to include data, Data().

Quote from: josh landers on March 19, 2014, 07:13:54 pm

I think that when we do have such a small community of axe users we should maximize the potential for understanding how it works. As ive thought about this alot... how about a more verbose command list.

What kind of verbosity are you looking for here? As far as I'm concerned, the Commands.html file does exactly what it's supposed to do, providing succinct but complete explanations of what each individual command/operator/syntactical element does.

josh landers · « **Reply #10 on:** March 19, 2014, 11:54:13 pm »

They are shrouded in a cloud of possibilities. Which are endless, but what I think is a good example is needed for each one with all possible arguments.
And the arguments could be colorized to make sence of what is required for the command to work and whats not. Some commands leand themselves to this in the descriptions but some do not. One such example is pxl-on and then you have Bitmap which gives you the options but doesnt tell you how to make bmp in the option.

Eeems · « **Reply #11 on:** March 20, 2014, 12:00:51 am »

Quote from: josh landers on March 19, 2014, 11:54:13 pm

They are shrouded in a cloud of possibilities. Which are endless, but what I think is a good example is needed for each one with all possible arguments.
And the arguments could be colorized to make sence of what is required for the command to work and whats not. Some commands leand themselves to this in the descriptions but some do not. One such example is pxl-on and then you have Bitmap which gives you the options but doesnt tell you how to make bmp in the option.

bmp files are pretty standard. http://en.wikipedia.org/wiki/BMP_file_format I'd assume that it's a sequential piece of data in which bits with a value of 1 turns the pixel on and 0 off.

Runer112 · « **Reply #12 on:** March 20, 2014, 12:37:03 am »

Quote from: josh landers on March 19, 2014, 11:54:13 pm

They are shrouded in a cloud of possibilities. Which are endless, but what I think is a good example is needed for each one with all possible arguments.

I think the descriptions speak for themselves. The examples for most commands would just be pretty pointless anyways, like Pxl-On(95,63), Pxl-On(40,20)^r, Pxl-On(7,0,L₁).

Quote from: josh landers on March 19, 2014, 11:54:13 pm

And the arguments could be colorized to make sence of what is required for the command to work and whats not.

Signatures are colorized, the colors just represent different syntactical elements or data types. And every valid form of each command is shown, so what's required for a command to work is for it to be of one of the given forms.

Quote from: josh landers on March 19, 2014, 11:54:13 pm

Some commands leand themselves to this in the descriptions but some do not. One such example is pxl-on and then you have Bitmap which gives you the options but doesnt tell you how to make bmp in the option.

I thought it was pretty straightforward, a pointer to the bitmap width byte, followed by the bitmap height byte, followed by the image data in the standard, row-major format, with each row padded with 0 bits at the end if necessary to fill a whole number of bytes. Here's a post I made on Cemetech giving an example.

If any command's syntax isn't clear, just ask.

josh landers · « **Reply #13 on:** March 20, 2014, 01:16:06 pm »

Example:

Code: [Select]

Before: EXP▶Hex Converts the number to hexadecimal and returns the pointer to that string.

Code: [Select]

After: EXP▶[HEX] -> PTR  Converts the expression to hexadecimal and if a pointer is declared it will be available at named pointer.

The red is not needed, but if you want the pointer to go somewhere you should provide this information.

Eeems · « **Reply #14 on:** March 20, 2014, 01:21:26 pm »

Quote from: josh landers on March 20, 2014, 01:16:06 pm

Example:
Code: [Select]
Before: EXP▶Hex Converts the number to hexadecimal and returns the pointer to that string.
Code: [Select]
After: EXP▶[HEX] -> PTR Converts the expression to hexadecimal and if a pointer is declared it will be available at named pointer.The red is not needed, but if you want the pointer to go somewhere you should provide this information.

You know you start modifying the documentation with stuff like that and then submit it to Runer112 to include in the official releases.

Author Topic: [Controversial] Better Axe Documentation Could Be Needed (Read 18160 times)

josh landers

[Controversial] Better Axe Documentation Could Be Needed

Hayleia

Re: [Controversial] Better Axe Documentation Could Be Needed

Matrefeytontias

Re: [Controversial] Better Axe Documentation Could Be Needed

josh landers

Re: [Controversial] Better Axe Documentation Could Be Needed

willrandship

Re: [Controversial] Better Axe Documentation Could Be Needed

TIfanx1999

Re: [Controversial] Better Axe Documentation Could Be Needed

Hayleia

Re: [Controversial] Better Axe Documentation Could Be Needed

DJ Omnimaga

Re: [Controversial] Better Axe Documentation Could Be Needed

josh landers

Re: [Controversial] Better Axe Documentation Could Be Needed

Runer112

Re: [Controversial] Better Axe Documentation Could Be Needed

josh landers

Re: [Controversial] Better Axe Documentation Could Be Needed

Eeems

Re: [Controversial] Better Axe Documentation Could Be Needed

Runer112

Re: [Controversial] Better Axe Documentation Could Be Needed

josh landers

Re: [Controversial] Better Axe Documentation Could Be Needed

Eeems

Re: [Controversial] Better Axe Documentation Could Be Needed