Community Complete Documentation - A proposal

* (Post imploded under the weight of its own negativity)

I'm sorry you feel that way, I guess. You don't have to contribute at all. The goal is mostly just to make the documentation more clear and complete, really. _{And speaking of source, we have some people trying to pick it apart. But you didn't hear it from me. This isn't the place or the time.}

I'm sorry if I put anyone on the spot. This project simply reminded me of people who wanted to see better documentation, but I understand completely. As for me, I have no capability right now to help when it comes to observing and documenting the exact behavior of anything. I only care about making games/programs I want. Even if the official manual is only 80% correct, as long as my game comes out fine, it's good enough for me, and the shoddy 20% probably will never bother me. My strength is in translation, so if, say, someone finds a piece of information in Japanese and wants to know what it says without using the very retarded Google Translator, that I can help.

I'm really only attempting to make the documentation more concise and complete, with the focus on letting the programmer know what everything does and how to use it. Specification is not a primary focus, because to the programmer it really doesn't matter what EXACTLY is going on behind-the-scenes. I mean, I can do all the writing myself for the most part. But I might want to ask people for help, as primary sources. For example, I haven't the slightest idea how to use BACKTRACE. Every time I try to run it I get 0: 0 or whatever. If someone knew what its behavior is and how to trigger it, you'd be a great source!

We need a way to distinguish variable names (like what VAR("name") is used for) from expressions: INC variable, expression "variable" should look different. I suggest <> INC <variable>, Expression Anyway, I will definitely try to help with this project EDIT: I'm pretty sure BACKTRACE is used to see the history of EXEC uses

FWIW, I proposed this idea before and I suggested to model it after the Garry's Mod Wiki, which is a fantastic example for high-quality community contributed documentation. wiki.garrysmod.com testing

FWIW, I proposed this idea before and I suggested to model it after the Garry's Mod Wiki, which is a fantastic example for high-quality community contributed documentation. http://wiki.garrysmod.com

I'm not sure how things like EXAMPLE([optional,] argument [,optional2]) work Are both optional arguments required, or just one? (but then how would it know which one you gave...) For example: BGMPLAY [channel,] song [,volume] I think that you can do BGMPLAY song BGMPLAY channel, song BGMPLAY channel, song, volume but not BGMPLAY song, volume

I've never really used github before... anyway, here's what ACLS does:

XSCREEN 0
LOAD "GRP4:SYS/DEFSP.GRP"
LOAD "GRP5:SYS/DEFBG.GRP"
FONTDEF
SPDEF
DISPLAY 1
WIDTH 8
BACKCOLOR 0
FADE 0
COLOR 15,0:LOCATE 0,0,0:ATTR 0:CLS
GPAGE 1,1:SPPAGE 4:BGPAGE 5
VISIBLE 1,1,1,1
DISPLAY 0
BACKCOLOR 0
FADE 0
WIDTH 8
COLOR 15,0:LOCATE 0,0,0:ATTR 0:CLS
FOR I=0 TO 3:GPAGE I,I:GCLS 0:NEXT
GPAGE 0,0:GPRIO 1024
SPPAGE 4:SPCLR
BGPAGE 5:BGCLR
VISIBLE 1,1,1,1

(this is why it's so slow)

I'm not sure how things like EXAMPLE([optional,] argument [,optional2]) work Are both optional arguments required, or just one? (but then how would it know which one you gave...) For example: BGMPLAY [channel,] song [,volume] I think that you can do BGMPLAY song BGMPLAY channel, song BGMPLAY channel, song, volume but not BGMPLAY song, volume

In some cases, you can tell by the types of the variables. For instance, addressing your top example, if 'optional' is a string type and 'argument' is a numeric type, then you can tell which two (if there are only two) by the type of the first value. BGMPLAY is documented wrong, if what you write is true. There is no standard way of expressing that syntax on a single line, that I know of. It can be expressed on two lines: BGMPLAY song BGMPLAY channel,song[,volume] (or: BGMPLAY [channel,]song BGMPLAY channel,song,volume but I like the look of the other way better.) EDIT: 12Me21 shows the | disjunction I didn't think of.

I'm not sure how things like EXAMPLE([optional,] argument [,optional2]) work Are both optional arguments required, or just one? (but then how would it know which one you gave...) For example: BGMPLAY [channel,] song [,volume] I think that you can do BGMPLAY song BGMPLAY channel, song BGMPLAY channel, song, volume but not BGMPLAY song, volume

In some cases, you can tell by the types of the variables. For instance, addressing your top example, if 'optional' is a string type and 'argument' is a numeric type, then you can tell which two (if there are only two) by the type of the first value. BGMPLAY is documented wrong, if what you write is true. There is no standard way of expressing that syntax on a single line, that I know of. It can be expressed on two lines: BGMPLAY song BGMPLAY channel,song[,volume] (or: BGMPLAY [channel,]song BGMPLAY channel,song,volume but I like the look of the other way better.)

I got my documentation for BGMPLAY from the help menu, so... anyway, what about variables? are <> ok? INC <variable>,expression otherwise you can't distinguish between: VAR(variable$)=expression and <variable>=expression EDIT: I'm making a list of syntax for every keyword, and I discovered a ton of cool things! For example, you can do GCIRCLE Center point X, Center point Y, Radius, Start angle, End angle [ Flag [ Color code ]] to draw an arc! (I'm not sure why commas are missing, it's probably a typo)

EDIT2:

Also, BGMPLAY can be BGMPLAY {[channel,]song|channel,song[,volume]} but that's harder to read. It would be nice if there were "linked" optional arguments. We are out of bracket types though.

It would be nice if you could label each parameter type with a classed span or something, I don't know what the limitations of this format is, but that would help in case some view of this documentation, for example, wants to have a visual distinction for the types.

Finished syntax for all keywords: http://pastebin.com/pJLR0Pk1

Finished syntax for all keywords: http://pastebin.com/pJLR0Pk1

Dang

Finished syntax for all keywords: http://pastebin.com/pJLR0Pk1

Wow! I'm so glad you pitched in. You are the perfect person for this project!

Oh dear. This is what you get for taking a long nap then. Lemme try and catch up with you all here. NeatNit: Yeah, a wiki-style host would be ideal, but that's more a phase 2 problem. We'll see what we can do (that ISN'T Wikia.) SquareFingers: I want to elaborate a little on what you said. It appears to me that when the system doesn't have enough sufficient information to figure out which arguments are what, it just passes them in left-to-right order until it runs out. BGMPLAY 0,1 plays song 1 on track 0, not song 0 at 1 volume. So BGMPLAY isn't documented wrong (BGMPLAY 0 does indeed play song 0), there just isn't enough information to make it clear how the argument passing behaves. I'll try to make note of this somewhere. Lumage: Markdown compiles to straight HTML, and it does support some degree of HTML within the document itself (to what extent I'm not entirely sure.) This is another issue based on how we want to host it. 12Me21: You said a lot of things (almost too many.) In terms of denoting which arguments are variables and which aren't, it's very rare that this distinction needs to be specifically made so I don't wish to include it in the syntax description. The document will explain what all the arguments do and how to use them, it'll all be in there. As for your syntax doc, this is good! I don't necessarily like your syntax style (it's a bit too complicated and there's a few mistakes, but how could you not make them when you wrote this much) but I could definitely use it as a cross-reference (but what's the deal with COPY *?). Thanks! Some notes I think when an array variable is required I could denote it as array[] to make it more clear. As a result, I'm opting to probably switch to {} instead of [] to denote optionals (the curly braces aren't used anywhere in normal syntax so it seems the most logical choice.) I DO like the idea of writing fixed lists of argument as OR'd lists (like XON MOTION | EXPAD | MIC) so I think I'll use that as well. In terms of passing labels, @label should be enough. Even if you're passing it as a string, the string has to be in the specific label string format. In fact, a label within an expression is parsed to a string anyway. Operators, OUT, and similar things will be described in sysdoc pages rather than an instruction description. It just suits the style better.

Building on 12Me21's work (not finished) (and without regard to slackerSnail's latest post, because I didn't see it): http://pastebin.com/xvMD8bbb

using {} for optionals is probably better so it doesn't conflict with arrays. {|} lists usually aren't the best option anyway since it can get confusing. As for variables, we can always do: real# integer% string$ (wait, this won't work...) array[] Hmm... I still think <variable> might be a better option. It also works with: GOTO @<label>

Hmm... I still think <variable> might be a better option. It also works with: GOTO @<label>

That doesn't really make much sense. You don't do @LBLVAR$ now do you?