Wiki feedback? Operator Page Layout

the following page is being proposed as a template for each operator in LSL
https://wiki.secondlife.com/wiki/LSL_Addition
and I'd welcome some feedback on it...

currently I've gone with 'common' names for the operator pages with an LSL prefix (so that articles with the same name need not be disambiguated), since they should be easier to search, and won't have to parse characters in the page name (ie doesn't make the wiki run encode/decode operations on the URL).

if the actual operation differs because of the types it's used with it's noted with that type.

I've separated the different types so that they could be targeted from other pages more easily.

I've also added a new category, which isn't linked to the main wiki yet to collect all these pages, and serve as a replacement for the LSL Operators page (it'll be converted to a category). the new category will have notes on precedence, and order of excution, and obviously link all the operator pages.

I was using a footnote wrapper for the notes, but I didn't like that it had such a small link, so defaulted back to targeting a notes sub section. sometimes thoes notes are quite important, such as the case of rotations (anyone know what actual mathematical operation is being done there?)

thoughts? opinions?
if anyone would like to propose a drastically different page layout, i'd encourage starting a new page on a different operator so that people can see the differences between the layouts.

thoughts? opinions?

Would it be worth considering a more tabular approach, with columns for examples, notes and so on?

it's possible, It'd be a bit harder to make it play nice with the content menu and links targeting specific sections on the page, but it is doable. I only went with sections based on those criteria plus maybe a clearer delineation similar that the function pages have... but that may be overkill in this case.

Yeah, you're probably right. There's too many dimensions to the data to work well in a single table.

Another thought: should the info be arranged primarily by operand type? I'm thinking that the way I'd use this would be to find what operators can be used on a specific data type - or pair of data types - and what they do to it.

I like this layout, Void. It's clean, easy to follow, and should be easy to reference from other pages. I agree that footnotes in tiny type would be annoying.

much better!

/me wimps out and gives her proxy voting card to Strife.

my thought was to note where you can have multiple operator types (as I did with integer/float)

I'm thinking multiplcation and division at least will need examples for those as well since you can do
(vector) * (integer/float) multiplication

which is an entirely different operation than

(vector) * (vector) dot-product,

or even

(vector) * (rotation) spacial-rotation...

I'm thinking those will collect nicely into the vector examples, with footnotes in the other types that crosslink to those examples... at least I hope

I picked addition first because it applies to almost all types, and I'm thinking of tackling multiplication next as it has more combined types and see how the layout works with it...

before I only had a single box with indented examples, but it made it a bit monotonous to read, and inhibited targeting.

I plan to make redirect pages for names that aren't covered by the page name, so that LSL_Concatenation will redirect to that page as an example.

I'm not quite sure if quaternion multiplication has a special name, or if it's just considered addition in this case, which I think the notes link covers nicely.

BTW, please don't get me wrong; the layout is great - very clear and concise. I'm just trying to sound intelligent by making what I hope might be intelligent comments and suggestions

nah, if I didn't want input, I wouldn't ask... and a table layout is a possibility if people prefer it... sectioning it like I did might be overkill... me, I've been staring at it awhile so I don't trust my judgment. plus I tend to think at odd tangents to other people, so a layout that makes sense to me might not make sense to the next person, or to someone just starting.

ETA:
I probably over-explain the reasoning behind my design choices, please don't take that as criticism of any ideas offered.

*ponders*
There needs to be a section on mixed type operations (the operators really do accept multiple types).

The way the LSO VM works, it reads the bytecode then it looks at the types and passes it to a type specific function (which then rereads the operator and performs the operation).
Which can be found in...
http://svn.secondlife.com/trac/linden/browser/trunk/indra/lscript/lscript_execute/lscript_execute.cpp
Lines: [1785,2653]

hmmm so at the very least separate out mixed types that aren't implicitly cast? I'll do up two different pages (or three if I find a good example) of the different styles..

Dunno. Looks a little sparse to me.

Do you think it is a good idea to break out each operator to its own page like that? Given how slow the wiki loads as it is, I think I would rather just have a big reference page format of some kind.

I kinda like the Wikipedia operators page, though I think that maybe real examples instead of those prototype examples would be more appropriate. The Wikipedia page is more definitive, but I would expect LSL to be more explanatory/demonstrative.

http://en.wikipedia.org/wiki/Operators_in_C_and_C%2B%2B

A page for each operator on the one hand makes sense as it fits with the plan to have a page for every aspect of the language but at the same time seems to be missing the big picture: I think users will be more interested in the information if it is type-centric not operator centric. Users are more likely to ask "What can I do with this type?" not so much "What can I do with this operator?"

But I don't have any brilliant ideas on how to present this information in any form.

Maybe the operator pages should just be stubs that point the user to the type pages where the operators are discussed with how they apply to the type in question.

I'm just not coming up with much inspiration on this topic.

Brilliant idea, mine wikipedia for layout ideas. I must be slipping.

tabularly we could do one massive list, sortable by precedence, operator type, operand type, etc... but with examples, note, caveats, etc it's gonna be huge and messy even if we can make the page appear clean it's gonna be hell on the formatting... I do agree with the concerns about load time (which has drastically improved) and it's kinda why I'm shy on the stubs (since stubs require more lookups and fetching)...

would a sortable table be targetable from type pages (to sort the list I and target the section on that type?) my wiki foo is very weak, so I don't know what options are possible there...

on a note related to tables and precedence, I'm thinking of separating out assignment and brace operators, due to LSLs backwards order, and classing them as promotion operators (since it isn't obvious what operation/evaluation happens first, for instance () at the same level as other other operations actually have a lower evaluation on the left)

I don't think it needs to be sortable, as long as it is well-organized.

Tables don't need to be huge and messy. For example, the llParticleSystem page is very complex, but the information is well-organized (I think, but I admit I may be biased, since I created it originally <.<. It is just a matter of coming up with the best organizational structure, and it should result in formatting that is fairly easy to accomplish.

I think I would stick with the way that Wikipedia page does it; namely, stick with the Operation table with the syntax and examples, and then have another block which explains precedence in the context of the Operations.

I'll work up an idea and post it later.

sortability just makes things nicer for grouping the data different ways, although my main concern with a table layout is that they tend to be visually cramped the particles table (while informative) stands as an example in that sense... and with all the operators and their various usages that could become a rather large table

I don't have a problem with information density, as long as it is well-organized. As long as my eye can start in one place and navigate to where I need to go fairly quickly, I don't care how dense the information is. In fact, I prefer density over sparseness, as it means less scrolling/navigating.

Also, using cell coloring/shading tends to help a lot in that respect, making it visually easier to quickly ascertain the organization and ease navigation.

Also, what other sort orders would need to be considered outside of operator precedence?

operand type would be a good one, and perhaps associativity (direction operations are done in, and possibly which sides are evaluated first although that might be covered in precedence or evaluation articles), and maybe category (comparison, bitwise, assignment, etc)

I suppose a scripted wiki page with a table that rearranges itself depending on user-selected sort criteria is out of the question?

sorting is more than possible, finding a good method to code that sort is a bit more complex (considering what's being sorted here)