Wiki Wiki Wiki

Avaunt!

I've changed it to "Caution" and added an Icon...
What do folks think of the icon? Should the other sections get icons too?

I like it conceptually, but think it'd be more useful where that "!" is at the top... I often miss that because it's out to the side (though the right justified placement is good there because it doesn't interfere with the basic syntax)

Very good point. Will make it so (later when I have time).

Hmmm... I don't see any changes? Are these updates on the function references? I still see Caveats and no icon.

https://wiki.secondlife.com/wiki/User:Strife_Onizuka/LSL_Style

I'm glad the thread has turned around to something much more constructive and practical.

Bingo.

Sure, some folks prefer to see an example to seeing what's actually required. However, many beginners will misinterpret the example, thinking that the angle brackets are part of the function call for llSetColor.

It's better to be correct and complete and a bit obscure than to generalize and be misleading. As Einstein said, "Things should be put as simply as possible, but no simpler." As Knuth said, it's better to be accurate even if a bit confusing, than to be inaccurate. The confusion caused by accuracy is far easier to correct.

I disagree with the idea of adding a "Concept" line.

The problem is, everyone has a different concept, since it's something we're making up. Try to apply this to every LSL function and ... oh my. Imagine how differently 3 different writers would write up this Concept line. The results would be quite different in each case.

Compare that with the prototype line. They would all agree, except for different parameter names. Of course, good parameter names are important, and hopefully, most of the variations would be people using different synonyms, so the actual difference would be small.

But now we're adding some new thing called a "Concept", which isn't defined. What to put there? Oh, well, put what makes sense to YOU when you think of this function!

Bad idea.

Be accurate. Be clear. And add tutorial and example information for the beginners.

But don't just make stuff up and promote it to the top of the page.

The thing that's really important to get right is the *purpose* statement. It should be as clearly understandable as possible by a newbie. Still, there are some functions that would be impossible to state the purpose of without using rather obscure technical knowledge, especially those involving rotation conversions.

One of the challenges for documenting any function is identifying the background of obviousness. Without knowing that background, it's impossible to communicate effectively. Getting it wrong either way leads to problems. Getting it wrong by putting the bar too low causes needless repitition and verbosity. Getting it wrong too high leads to unanswerable questions.

We should not assume the background of obviousness is the same for all functions.

Ones like llSay() and llSetColor() should be written with a relatively low level. For llSetColor() it does behoove us to say that a vector is used to represent a color, with details on this easily found (either on the page or by a link -- ideally a link, because the color concept occurs in lots of functions).

Functions that deal with vectors and rotations shouldn't have to be written assuming you have no clue what a vector or rotation is. However, they should point you to good information on vectors and rotations.

The current layout achieves this objective. If the current layout (with prototypes) causes confusion, then we need tutorial pages explaining how to read the prototypes, and an easy way to find them.

What was wrong with "Caveats"? It was the perfect word for the purpose.

Someone said they "didn't like it" without justifying their dislike in any way. What's wrong with that word? It's like saying "I don't like A#," when talking about a musical composition.

A little OT, but there's something I don't understand about how to edit the wiki pages, having to do with templates.

Consider llResetOtherScript():
http://wiki.secondlife.com/w/index.php?title=LlResetOtherScript

I figured out how to add a caveat. But if I wanted to edit the first one, "If name is missing from the prim's inventory or it is not a script then an error is shouted on DEBUG_CHANNEL. ", how would I find that text?

That's just an example, but it seems that every time I see a minor flaw in the text that I'd like to fix, I can't find it, because of some template magic.

Thanks!

LOL, welcome to template hell! The shout text is hiding in Template:LSL Function/inventory so if you want to change it you have to look at all the pages that use it to see if it makes sense everywhere.

Cerise is correct, it's in https://wiki.secondlife.com/wiki/Template:LSL_Function/inventory

I really should add a parameter to disable the caveat...

What did you want to do to the caveat on llResetOtherScript?

I didn't like the sign icon in that context... so i found a bug icon (a red ant) to use instead.
Thoughts?

maybe a yellow ! sign... the red is used on most forums to report bad posts...

the ant is counter intuitive to most net use since people like to put insects on pages to mess with users.... and it doesn't draw much attention (I'd have thought someone was being cute)

I tried a yellow icon but it didn't stand out enough...

JIRA Bug:
https://wiki.secondlife.com/w/index.php?title=User:Strife_Onizuka/LSL_Style&oldid=347122

Red/Orange Sign:
https://wiki.secondlife.com/w/index.php?title=User:Strife_Onizuka/LSL_Style&oldid=347102

Red Ant:
https://wiki.secondlife.com/w/index.php?title=User:Strife_Onizuka/LSL_Style&oldid=346542

Try a chartreuse :}

More importantly, how would I have found this text? I didn't want to change THAT one, but a number of other times, I've tried to fix some clumsy text or typos and could not find the source of the text due to being nested deep in templates.

Either the templates list at the bottom of the edit page is incomplete, or I just plain don't understand it (assuredly the latter, but possibly the former as well).

The whole idea of Wiki is so that users can edit the text. So, my simple question is: how do we find where to edit the text?

Use the one above as an example. But, I want to learn to fish; I don't want a grilled trout on a plate.

Random comment: I wish the font size of stuff enclosed within <lsl> tags was smaller. I've always thought that fixed-width fonts were easier to read at smaller sizes than variable-width fonts but the wiki seems to use the opposite - regular text seems a bit smaller than lsl text.

Seems to be resolution dependant. Anything in lsl tags for me in the wiki is always smaller then the rest of the text and I have to magnify it. This is using IE, Chrome & Firefox.

Weird. I've noticed it both at home and at work.. Maybe I've got some funky version of the font installed..

well I do notice that on default text zoom (FF) that fixed width appears bigger, but isn't actually (probably just the effects of the spacing increasing individual letter definition) but zoom doesn't seem to affect preformatted text =/ (useful for my large screen dimensions), so bumping lsl down might be painful compared to bumping general up (although it's at 12pt so I dunno....)

Hmmm.

The start of the rabbit hole is at the top of the article. There you will see some templates, if one of the templates parameters involves a function parameter that is involved with the text you want to change, go to that templates source. Now inside those templates anything can be going on. Those templates work by setting the equivalent of environment variables (they persist after the template has finished executing; their values are later used when generating the layout). They also may include other templates that work the same way; but in practice, the depth is rarely more than two deep (with the exception of llSetPrimitiveParams, where it can get to be three deep I think). But the trick to tracing these things is with the function parameter names. The names get inlined and to do that they have to be passed from one template to the next.

The only other templates currently that are used are templates to hold the tables of constants. They are typically not at the top of the article but in the template body. Just look for "|constants=".

But to aid in editing, I'll start wrapping inlined text in span tags with an id parameter listing where they are from (so you can use FireBug to aid in editing).

I've never seen it not include a template it is using in the list. But if you think the list is out of date, click the Preview button.

Thanks, Strife -- the light bulb is beginning to glimmer.

I understand the usefulness of the templates. It's too bad they tend to make much of the wiki uneditable by anyone but a very few.

I believe the template in question was indeed listed but it just didn't register on my radar. I'll work on my radar.