Is the scripting wiki helpful to you?

And that's the tactic ALL the trolls use Sindy. LOL

Please, take your fake smile and backstab elsehwere.

Wow, thought you were more observative and astute than that.

OK, you kids done with the little jibes and personal stabs yet? Ready to get back to the subject at hand? I mean, I can give as well as take. The flavor is up to you. You can either be pros and stick to the topic or you can make personal slams (what, because that's all you can muster to make your point?). I prefer presentation of information and even personal opinion, but if you all prefer inuendo and attack and inferring other people's motives.. pick your poison. All the same to me. I can decide ignore one troll just as easily as the other.

(Not calling you a "troll" Argent. You're not. Just asking you to strongly avoid dropping to that level to make points that might otherwise prove interesting.)

Actually, it's not. 80% of that page has nothing to do with bold and italic text. Part of it is some incorrect advice on semantic markup, and part of it is about how text looks like on different browsers.

Yeh, I get that, which is why I'm suggesting you turn your efforts into creating that tool, if that's what you're interested in having, instead of turning something else that's not supposed to be a teaching tool into a bad one.

My point is that you you can put two (or three, or four, or eight) separate documents in a wiki, and cross-reference them, and make them both equally accessible and available and at your fingertips... from each other... without having to change one of those documents (the reference pages) into another kind of document (a user guide).

It's not just layout and presentation. The content and the kinds of details presented, as well as the narrative flow and relationships, is completely different for the two kinds of documents.

Sure.. I'm a troll.. Well known for it around here, actually.

We also use the tactic of saying things like this in forums: You're an idiot, your ideas are stupid and your attempts to be clever-while-insulting are transparent and pathetic. Welcome to my ignore list.

Both examples I gave are typical uses of the llSetColor function. They are not exceptional cases. They are normal and usual. They are not hacked, abused, distorted, or useless.

Obviously I'm not as observant as you think.

Hmmm... if you say so. I didn't btw, mean "hacked and abused" in a negative comment... more as in the aspect of "tortured prims".

But myself, while some may do it, I would not think that applying one's position on a sim to the llSetColor function is a "common" case. I would call that "exceptional". But again, such use really has nothing to do with the syntax format of a reference manual, which should refer to the bottom-line format of the function itself. That, in my experience, means one of two things:

llSetColor(vector, integer);
or
llSetColor(<r,g,b>,side);

Depending on whether the manual is intended to be absolute tech or a little more informative.

AGAIN Argent, the syntax line should not be the "definition" line. The definition section follows... and can be quite lenghty. The purpose of a syntax line is to provide syntax.

By your very argument above (and I've made this point twice before):

llSetColor(vector color, integer face);

should not be used-- by your own arguments-- becuse "color" isn't really a "color"... it's a vector that can come from well... any conceivable vector going, even position or rotation. It would be just as valid then to say:

llSetColor(vector (color or position or rotation or whatever), integer face or whatever variable or concept you decide to use for a face);

I'm not exaggerating here. I'm talking core syntax, not abstracts or expansions thereof.

Maybe not, maybe so... LOL.. but you are SMART... and it's that intelligence I've been trying to appeal to. Observant... I don't have the data to draw a conclusion, nor desire to draw such conclusion. <-- smiley wink, in case the first two missed.

And welcome to forum TOS abuse posting. Hope you had fun.

I know what you mean. I was one of the principles of a company named "hackercorp" back in the early '80s, back when that WAS the common usage, and I still most emphatically deny that this is a hack, in any sense. It's not a crufty hack, a cool hack, a grody hack, a twisted hack, or any other kind of hack. It's normal, unexceptional, and conventional code.

Sure is. Mapping distance, position, altitude, land height, and other vector values into color is a totally conventional presentation mechanism. Not to mention being how sculpted prims work.

My other example, which you seem to have missed, is about applying a color on one face to the other faces on a prim. Again, nothing weird about it.

The bottom line is that the first parameter to the function is a vector.

Absolutely it should. One of Dennis Ritchie's key insights in the design of the C programming language, that has been copied by most languages created since the '70s... including ones that are not at all C like, is that having the definition, declaration, and use of the function use the same syntax makes it MUCH easier to understand. Virtually everyone who writes software today is familiar with at least a couple of languages that follow this model... because it works, and it works well. It's compact, familiar, self-documenting, and presents the types, names, and syntax of the function in one line.

This should be : llSetColor(vector color, integer face)

Which is how it is shown in the wiki. You keep saying you know the correct way to write it but there has not been one single person, newly learning or expert coder who has agreed with that.

ugh that does not work. The moderators do not just look at the single post but all of them. Have fun trying to explain to them that you are not insulting people yourself.

I can accept every argument you make above. I don't necessarily agree... but that doesn't mean you're wrong either. It's good to have both viewpoints presented for consideration.

Your last statement about defining in the syntax line is not one I disagree with (although it may seem contradictory to a prior statement... it's not). The point I made was to use one format or another... but not some kind of kluged form of the two. I again refer to my prior examples.

I totaly agree with you that the llSetColor function uses a vector. I never have disagreed with such. That doesn't make the LsL Wiki any easier for the general populace to read or understand. If it's a tech manual only for techs, it needs to state that in the mission statement so that others stop wasting their time trying to understand it and instead create and look to alternatives to that work.

(Answering this because it's valid and apolicable to this thread).

Jesse, the explaining will most likely be on your part more than mine. Regardless of yours and Sindy's continuing attacks and claims, I insulted no one. I stated my valid personal opinions regarding the state of the LsL Wiki... which is the right of any user on these forums. What I didn't do was call Strife an idiot, transpaent or pathetic, as Sindy has stooped to the level of doing. If you two can't see the difference in having an opinion about a website and an opinion about a PERSON... then there's likely nothing more that I can really say to change your opinions... or your abusive attitudes. There are always one or two people who have to bring drama into a forum.

I said in fact, very early on, that Strife is a nice guy and most likely operates at genius level. That doesn't mean I have to like or even respect the LsL Wiki itself (although I do respect it as an immense and time-consuming effort). But even that respect for sheer amount of work doesn't mean I have to mince words when I say that the Wiki strikes me personally as a convoluted technobabble mess. That's not insulting Strife; that's how it strikes me. Sorry you two don't understand that... and I'm sorry you felt it proper to lower to the level of intentional flaming and trolling to get your points across. You could have instead chosent to simply state your opinions about the LSL Wiki and let that suffice to make your points. You chose otherwise. That was your chosing, not mine. So now we'll let the moderators sort it out... and you two can do the explaining of attitudes and posts.

Eren, "llSetColor(vector color, integer face);" is not "some kind of kludged form of the two". That IS the standard form for both definition and declaration of a function in every C-style language on the planet. If you were defining "mySetColor()" in LSL, that's precidely how you would define it: "mySetColor(vector color, integer face) { ... }".

Sure you have, you said the syntax includes the angle brackets.

Putting incorrect and confusing syntax definitions would make it worse.

That's a completely separate issue, and one that I have no objection to. I am objecting only to your argument that it would be improved by making it less accurate and more confusing.

OK, lets switch gears from llSetColor... Eren, I'm curious on how you would propose to do a different function, like llListFindList, or any function that takes a list? Now you are dealing with a dynamic variable over a static (for lack of a better word) variable. I just can't see how changing the format for the function definition and syntax reference would work for all cases, and how about the function that do return a value too?

iIndex = llListFindList(["a", "b", "c"], ["b"]); ?

That is clearly an example then a definition. That is what people are saying, that the reference is suppose to be just that, a reference. On the wiki if you do not know what a vector is, you can click on it, and it will take you to the page that explains what that type is. Same with any type. So by using llSetColor(<fRed, fBlue, fGreen>, iPrimSide) you will have to reference the <fRed, fBlue, fGreen> not only to the vector type, but then explain exactly what this means. It's more reading, more complex writing.

In CS, we generally learn types first, what they are, how they are used, etc, before one even gets to functions. By the time you are ready to use a function in a script/code, you SHOULD know what a vector is (especially since it's a base type in LSL).

Mainly, the reference way of llSetColor(vector color, integer side_or_face_or_whatever_you_want_to_call_this_variable), fits the same format that a more complex function will use. One standard fits all in this case, so use it, since it's used outside of LSL as well, and a new person who wishes to expand their knowledge will be familiar with the format.

"This should be : llSetColor(vector color, integer face)

Which is how it is shown in the wiki. You keep saying you know the correct way to write it but there has not been one single person, newly learning or expert coder who has agreed with that."

Funny how you ignore the posts like this. Name one person who agreed, in contrast everyone said it was bad. You also ignored the posts asking what was the basis for your 99.9% of the users hate the wiki. Most of us talking to you in these threads have been here answering questions for years and we have not seen that anywhere.

Instead once again you say that the wiki is horrible. You now agree that a User Guide would be helpful but then turn around and say that you will not write it or contribute because LL is not paying you. This translates to the job everyone has been doing sucks and someone needs to redo it but the have to write it how I sayor write a user guide but it is not going to be me. Which is exactly what I stated in my very first post.

Eren: You may have already provided this (haven't read all the posts), but I would very much appreciate a pointer to a piece of technical documentation that you believe is:
-- a good example of writing, and
-- both a good reference and learning tool

Preferably, something on a website so that I don't have to go to a bookstore or buy a software package to read it.

I ask because, frankly, I'm finding some of your examples puzzling -- the suggested changes seem minor (and is some cases obscure actual syntax). I look for more benefits from things like non-templated, more expository passages/examples of basics like 'rotations', 'permissions', or 'event-driven'.

I think one thing to keep in mind is that LSL was invented rather rapidly, and thus its syntax is sometimes intrinsically confusing -- I just mention that because I empathize with Strife, Eren and others of you here who have been trying to make it clearer to readers. It's a difficult task no matter what documentation conventions you choose.

Thanks.
.

Sure I haven't (you know Argent, you have a bad habit of directly contradicting people. Has anyone ever mentioned there are other ways to make your point?).

The angle brackets themselves indicate the use of a vector. Argent, in the past we've had a problem with you apparently reading what you want to use in debate against me... and ignoring my other statements. This is not supposed to be an adversarial debate-- which is a position if I may, that you too often take. This is a statement of opinions and feedback. You don't have to look for things to argue with and you sure shouldn't ignore valid statements, made by me, that qualify and explain my opinions and viewpoints.

Case in point: I think my position regarding recognition of vectors is pretty much established. I very plainly stated, multiple times, that llSetColor(vector, integer); is a valid syntax format. All I've been discussing is PREFERRED layout of the syntax line.

If you'll read back there, I even admitted there are reference manuals that use the "vector color, integer face" format. I simply think that's not the best format for the job or reader-friendly. I know techs use that world wide. They're TECHS. Techs have a reputation for forgetting how other people think and read. Nor have I found such manuals to be particularly informative, since they (like the LsL Wiki) tend to carry on that tech-thought process throughout the rest of their text and examples-- if they even bother to include valid examples, instead just expecting readers to be smart enough to "get it".



I'd have to say that you're putting words in my mouth. Just a teensy biased there are we?

1. It wouldn't be less accruate
2. It wouldn't be more confusing
3. As it is now IS confusing... as evidenced by the majority of people who try to use it.

Seriously Argent... would you like me to post a general public consensus vote forum? Unlike Chaz, I have a long career of creating statistical surveys and I can flat do a very valid, 5-point survey that will solidly establish how people in general feel about the LsL Wiki. Do you really, really think the current tech-opinion would stand up to that on a "Are you satisfied with the LsL Wiki" scale?

The LsL Wiki IS currently confusing. Regular statements-- for years-- from both newbies and professionals have established that fact. The question is-- what are you all going to do about that?

My guess... very little... just as there has been very little done to date. Strife says he posts these forums about every 6 months or so. I haven't seen any significant strides or imrpovements in the Wiki. Anyone else seen any? So again, what are you all going to do about that. Obviously I'm not going to continue bashing my head against a brick wall, nor likely is anyone else who has had to deal with the "tech populace" of the current Wiki (just as I've been dealing with it here in these forums). So it's really up to all of you.

As a note.. someone back there claimed that "no one" has agreed with me in these forums. They really have to be joking. Did they just blip over all the posts that tried to confirm what I was saying? And have they noticed that such people have stopped posting here... faced yet once again with the wall of tech-maven opposition and people totally discarding their opinions. Yet Strife still wonders why he doesn't have more help on the Wiki. The responses to earnest feedback on these forums makes it very obvious why no one wants to help. They're just fed up with trying. It's obvious no one wants their help... or alternately wants robots to follow their every direction. Conformity is one thing; hard-core inflexibility is another.

That's all I have time for right now. I have other things that need attending. See you all later.

Just remember Argent that his pointing out your bad habit, saying that you are putting words in his mouth and calling you biased is not meant to be insulting.

Eren, nearly every single person in this thread has a very long history of helping a multitude of people learn LSL. Several have gone on to help and teach others themselves. We are helping and we are doing that everyday. You are the only person here who has stated several times that you will not help. You want change but you want it on a silver platter with no sweat equity on your part. Furthermore, you want it done to your specifications. I suggested multiple times that you can write a user guide or even a simple primer on a script layout yourself. The only response so far is "Hell no, not me".

We'll have to agree to disagree on that. While I don't pretend to have nearly the expertise you probably do on things like HTML, the fact is there's nothing I've learned to do from that book that hasn't worked. But in any case, once again, the content itself is not what was at issue, only the presentation style.

Look, I mentioned I learned HTML in 2 weeks by reading that book. What I didn't mention was I didn't even have a computer in front of me while I was doing it. My grandmother was incredibly ill at that time, and I spent those two weeks in her hospital room, by her bedside. Because the book was written in plain English, I was able to absorb the information very easily. Had it just been a dry list of commands, I never would have been able to do that. The conceptual descriptions were absolutely crucial to my learning process.

Were there to be similar conceptual descriptions on every page of the wiki, I have no doubt I'd be able to learn LSL as easily as I learned HTML.




It wouldn't be a bad one. It might not be ideally streamlined for YOU and those like you, in that there would be superfluous information you wouldn't care to read, but it would be pretty damned good for many, many others.

And I strongly disagree that it's not supposed to be a teaching tool. As others have already mentioned here, the wiki's stated purpose is "To provide documentation to help scripters of all skill levels." Fact, the simple listing of commands does NOT help scripters of all skill levels. It only helps those who are already at or above a certain threshold. "All skill levels" MUST include newbies, and MUST allow for various learning styles. Otherwise, the mission fails, by definition.




First, as I said, I see no necessary distinction between a reference volume and a user guide. One document can certainly do both. It happens all the time. I'm sorry if that doesn't fit your vision of how the world should be categorized, but not everyone thinks in neat little categories like that. No offense, but to fail to recognize that is to be decidedly naive.

Second, absolutely none of the present content of the wiki would need be removed or altered in any way. All that's needed on each page is the addition of an extra section or two to say something to the effect of "OK, here's the plain-English translation of everything stated above..." That's it. I can't imagine how that could possibly get in your way. Even if it ended up helping no one (which wouldn't be the case), it certainly couldn't hurt anyone either.

Third, while setting up some sort of linkomatic cross-reference structure would certainly be a step in the right direction over what we've got now, it still wouldn't help the people who don't learn that way. Think about the number of people who ask questions on this forum every day that could easily be answered by Googling instead of asking. Clearly, if cross-referencing worked for everyone, those people would have no need to ask for answers here. Whether you think this SHOULD be the case or not, the fact is there is a significant number of people who have a need to see plain-language explanations right next to the tech stuff, on the same page. Those people shouldn't be left out just because some others might prefer brevity.



Again, there's no reason one document can't include both.

Want a good example? The instructions that come with EMG guitar pickups include a schematic, a physical wiring diagram, and detailed verbal instructions, all on one page. If one is fluent in the language of electronics, the the schematic is all one needs in order to know what to do. If one is more of a visual learner, then the diagram of the physical wires will do the job. Or if one is more of a verbal learner, then the written instructions are the way to go. All bases are covered, no matter what the skill level and the learning style of the reader.

Electronics is just as complex of a subject as programming, yet the good folks at EMG were able to find a way to convey the necessary information so that ANYONE could understand it. There's no reason the same couldn't be done for the LSL wiki.

I'm going to ignore the personal comments and attacks in your message and concentarte on the actual content.
You're thinking like a tech, here. Angle brackets are just angle brackets until people learn the syntax of a vector and everything else associated with it, so to the people you're trying to address you're not saying:

"This function takes a vector as the first argument, and the vector is made up of red, green, and blue."

What they see is this:

"This function takes four arguments, red, green, blue, and side... and there's angle brackets around the red, green, and blue."

I've seen examples like this all the way back to PDP-11 Macro assembler, and had to sit down with people and explain what part of the documentation was explaining the function, macro, command line, whatever the example was... and what part was AVOIDING explaining the actual syntax in favor of explaining the specific use cases the person who wrote the documentation thought the "typical user" would want.

It doesn't matter whether it's:

llSetColor(<fRed, fGreen, fBlue>, iSide);

or:

QIO$W IO.RPR,LUN,,,,,<BUF,72.>

Do you understand what the angle brackets in THAT example mean? Do you understand when they're necessary?

People who are familiar with the language will "get" what you're talking about, but they're going to be happier with the syntax the Wiki actually uses. People who aren't are going to pick up just enough to write something that works, and if it happens that their use case matches the one you're thinking of they'll manage well enough, but they won't actually understand what they're writing. When they want to do something slightly different, they'll be lost.

Um, what? "llSetColor(vector, integer);" is not even valid LSL code. It's not a valid definition, it's not a valid declaration, it's not a valid use. It looks like some kind of attempt to adapt one of the forms of C89 or C++ function declarations into LSL. I can see what you're trying to say, obviously, but it's even more of a "techy-geek" way to express the parameters to llSetColor() than the one the Wiki actually uses.

The preferred layout of the syntax line is one that actually describes the syntax.

It's not just that there are manuals that use that format, that format is the actual LSL syntax. That's the real syntax, that's how a function in LSL is defined.

What you propose is less accurate and confusing... because it implies that llSetColor requires angle brackets and takes four parameters. And YES, it DOES imply that to the audience you're trying to reach.

No, why on earth would I want you to do something pointless and misleading like that?

A user guide is organized around use cases. It doesn't explain what llSetColor() does, it explains how color works. It doesn't give you the syntax of llSetColor() and then go on to the next function, it explains how to set the color of one face of a prim, and how to adjust the color, and how to blend colors, and how color interacts with lights, and glow, and textures, and tells you when you should use llSetColor() and when you should use llSetTexture().

I'm not taking about "setting up a linkomatic cross reference structure", I'm talking about the reference manual being linked (as a glossary) to a user guide.

I'm not objecting to expanding or improving the plain-language explanations on the same page, I'm objecting to attempting to combine the structure of a user guide and and a reference manual, as the example page you provided appeared to be doing. Perhaps it was just a really bad example, and other parts of the book are better, but if so perhaps you can find a better one to show.

I don't see why it can't explain what llSetColor does AND explain how llSetColor works. Sorry, but I'm just not quite following you.




That's not a bad idea. I think it's maybe an unnecessary complication, though, since, as I'm envisioning it, the same reference material that would be in the glossary would also be right at the top of each page in the guide. But if repeating that information in a separate glossary makes you feel better, there's certainly nothing to lose by it.




Maybe it was a bad example, since you seem to disagree so strongly with the author's commentary. I just opened the book to random page and plopped it down on my scanner. All the pages follow the same basic format, though. There's a brief one or two sentences to say "The way you do _____ is to use a command called ______." Then the command is listed. Next there's a description of how to use the command, along with some tips. And finally there are examples of how various pieces of code that use the command will appear in browsers.

The wiki in its present form is doing almost all of that already. It's just not written in a language that the layman will readily understand. I can't see what could possibly be lost by just including a "Here's what that means" section on each page, which would correct that shortcoming, without interfering in any way with what's already there.

Because llSetColor has multiple use cases.

Let's go back to the HTML example, maybe that will be clearer. That page was not about the B tag and the I tag and the ADDRESS tag and the EM tag, it was about how to set bold and italic text.

That's precisely right. It's organized around use cases. It's organized around "to do X, you use Y". There may be one command to do that, there may be several.

Organizing the manual that way, you would have a page on "how to change the color of a prim" like the page you scanned was "how to set bold and italic text". It would explain llSetColor and llSetPrimitiveParams([PRIM_COLOR]) and llSetLinkPrimitiveParams(..., [PRIM_COLOR]); and point out that you can use llSetTexture() to get a similar effect, and also that if you want animated colors you should use llSetTextureAnim() with a multicolor texture and a scale of 0 rather than a loop calling llSetColor() over and over again...

I am not objecting to doing that. But the book you found so useful was not just doing that. It is organized in a fundamentally different way.