Talk:LSL Function Style

Coding Standards?

Is there going to be any debate regarding the use of CamelCase, javaCase, or coding standards? Thoughts? Opinions? Flames >> /dev/null Talarus Luan 18:28, 24 January 2007 (PST)

Use the style guide from the old wiki Gigs Taggart 15:38, 25 January 2007 (PST)

Anyone wanna volunteer to write our own sanitized version of that? ;) Talarus Luan 19:03, 25 January 2007 (PST)

Specification

returns random number in range [0,mag)

Energy:	10.0
Sleep:	0.0
Function ID:	8

Dimentox Travanti 08:09, 25 January 2007 (PST)

Now is the time if you want me to change the formating of that table, i've already generated the tables for all 328 functions. Strife Onizuka 10:46, 25 January 2007 (PST)

Actually Looks good with that.. Dimentox Travanti 10:53, 25 January 2007 (PST)

Looks good

Seems to work well. it flows, and concise info. Dimentox Travanti 08:11, 25 January 2007 (PST)

Helper Functions

I added a "Helper Function" section, these are a bit like examples, but are complete functions that encapsulate or use the function in question. If they had pages to themselves they would be linked through "See Also"Strife Onizuka 10:50, 25 January 2007 (PST)

Short Description

I didn't see much point to the short description. That sort of thing really belongs in the specification section.

Templates?

I see that MediaWiki supports some kind of templating system. Is there a way we can use it to define a template for this page type and parameterize the content to it? Would make it easy later to change the template instead of changing hundreds of function pages. Probably can use this for all of the page types which will specify a standardized format for more than a handful of pages. Talarus Luan 11:03, 25 January 2007 (PST)

I have made up a test template for functions, hence: Template:LSL_Function Talarus Luan 12:44, 25 January 2007 (PST)

Creating it as a template is a good idea. And parts can be sub-templated out. --Thraxis Epsilon 12:51, 25 January 2007 (PST)

Please feel free to attack it; you've got a lot more experience than me, as I'm rather new at this MediaWiki stuff. :P Talarus Luan 14:17, 25 January 2007 (PST)

The template is looking really good. What about moving the "See also" section down below the "Notes" section? Talarus Luan 19:05, 25 January 2007 (PST)

I was thinking of doing that, I will do it now. Strife Onizuka 23:48, 25 January 2007 (PST)

Oh I should have said earlier, I've made a template, and I've just finished making stub pages for ever single function. Your template seems to be based on an earlier version of mine (while i was playing with the first pages it was under heave development)Strife Onizuka 23:46, 25 January 2007 (PST)

Well, I started out with something from scratch, based on the experimental page layout at the time, and Thraxis has been updating and trying some things using your Specification Template. It looks like he is having a problem doing conditionals in Template parameter passing, so I don't know if we can get away with it or not. Look at an earlier revision of that page for the one I originally created. It was designed to do the whole page, though I am not sure if that is the best way to attack it or not. Talarus Luan 23:55, 25 January 2007 (PST)

Couple more things: Was it wise creating stub pages already? I was under the impression that someone was looking into getting the LSL namespace assigned for us to use. Will that affect the page locations? IE, would they need to all be moved? Also, your template has a minor grammatical issue in the return value specification. If the return type is "integer", it reads "Returns a integer". Can you conditionally select a word based on the value of a parameter being a specific value? I couldn't find any doc on the #if conditional anywhere myself. Talarus Luan 00:10, 26 January 2007 (PST)

~grumbles~ I was hoping nobody would notice that, yes it can be fixed, it's a bit of a hack (I'll see what i can do; hopefully I'll be able to pick off the first character and compare it otherwise it will be a comparison for just integers ~_~). If we did get the LSL namespace, we would have problems with forced leading caps. About the #if documentation, I spent a few hours experimenting. I personally don't mind having to append LSL_ to the front of pages, good place to use a template. Strife Onizuka 01:08, 26 January 2007 (PST)

You should count on us picking nits. :P Is there any problem with people typing a function name in the Search box and searching for its corresponding page? Talarus Luan 10:29, 26 January 2007 (PST)

None that I know of since the function names are in the template header they show up in a search. Know if someone wants to do a good thing they can make redirect pages for ever LSL function. Strife Onizuka 14:51, 26 January 2007 (PST)

Documentation on the #if (and other commands) is available here ParserFunctions --Thraxis Epsilon 03:52, 26 January 2007 (PST)

Thankies, Thraxis! :D Are there any more good help pages which we should be referring to besides the ones available at the main MediaWiki help page? [1] Talarus Luan 10:29, 26 January 2007 (PST)

Check the Special:Version page from time to time so you can see when new plugins are added and what documentation they have linked. --Thraxis Epsilon 10:50, 26 January 2007 (PST)

I've posted a suggestion, hopefully they will consider Jira:WEB-23, it's for 1.9.x & StringFunctions Strife Onizuka 15:13, 27 January 2007 (PST)

Small issue with the LSLG template

go here: [2]

Then click on llInstantMessage under related. It goes to a page called lllInstantMessage. Hope this is the right place to point this out. :) Darien Caldwell 13:13, 26 January 2007 (PST)

Actually, you can put it in the Talk page for that function or, better yet, make the edit yourself. ;) Talarus Luan 13:32, 26 January 2007 (PST)

LSL Syntax Template?

Any word on when we might see this implemented? Talarus Luan 19:49, 27 January 2007 (PST)

Knock on wood, I hope before the Havok upgrade (would it be Havok 3 or Havok 4?).Strife Onizuka

LSL Function Template borked?

What happened to the LSL Function Template? I'm getting red and yellow errors now. "Template:LSLFunctionAll has been replaced by Template:LSL_Function", "sort value not defined", etc. Whazzup wid dat? Also, how can we embed tables into the template? Would I need to make a template of the table itself? (The pipe chars are throwing the parser) Talarus Luan 12:48, 28 January 2007 (PST)

It's not that the template is borked I'm trying to get all the pages consistent along with cleaning up the mess I made in the Template namespace. I abstracted the function template enough to use it for events as well. Then I made LSLFunctionAll just a pointer to LSL_Function. The 'sort' variable is used to put your function in Catagory:LSL Functions. This way we don't need to make our own giant table at the top. If we had StringFunctions extension this could be done automatically with the use of a template (and would be really slick). The other warning about using the func_desc (or header_desc) has to do with using the proper fields. The footnote was really reserved for short notes about the function and the desc field for the actual function description. I did all this to motivate the pages to be gone through and updated; to fix the bugs I introduced when I created the first templates. So I added the error messages to the template to show what needed to be done with the pages. Strife Onizuka 15:40, 28 January 2007 (PST)

LSL pseudo-namespace

Right now, a lot of pages' titles have been prefixed with "LSL". Can we please not have this pseudo-namespace thing going on, and stop it before it propagates further? There was a discussion on IRC which I think pretty conclusively determined that splitting LSL topics into their own namespace is a Bad Thing (well, only one person was really arguing for it anyway).

In case you missed it: There's no need for splitting things into different namespaces - disambiguation works fine for anything that conflicts, and the guidelines from Linden Labs encourage this (see Editing Guidelines, "Use the simplest, most obvious name possible when creating new pages. We can always create a disambiguation page later if we need to."). It's much easier to create disambiguation pages for just the things that need it than have to go through all this trouble for every single page. Both this pseudo-namespace thing and using an actual namespace needlessly complicate wikilinking (one has to use a template or a longhand [[LSL ____|_____]]). Adding a custom namespace would also break various features of MediaWiki, which is designed to have all the content in the main space - the defaults for search and Go would not work correctly, and redirects would be necessary for every single page in the LSL space.

Can we please agree on this? Celierra Darling 13:50, 29 January 2007 (PST)

While I was writing, Rob Linden posted a comment to this bug on JIRA: https://jira.secondlife.com/browse/WEB-22 Celierra Darling 14:14, 29 January 2007 (PST)

If people want to discuss the future of the wiki by all means do. But not everyone uses IRC and it would be more appropriate to have a discussion about the wiki's future on the wiki. I won't deny I've been pushing things along quickly, my goal is to get things completed. If we spin our wheels discussing how it will get implemented, it won't get implemented. We need people of action and dedication: those who make layouts, templates & content. Talk is cheep.

The use of the LSL prefix wasn't my idea but using it did solve a few problems.

Ambiguities
Outside of LSL ambiguities, they can't happen now. Planning for the future is a good thing.
Audience distinction
When users are reading pages inside the LSL pseudo namespace, they know they are reading pages designed for scripting in LSL. The audience is not the general public but those interested in LSL. Having each function page marked with text like "This is a function in the LSL scripting language..." that introduces LSL etc, would be distracting to the documentation. This helps use define the audience and better server that audience.
Lower case named pages.
When the vast majority of documentation is complete 75% of the pages will have lowercase names. If it were a real namespace or not a pseudo namespace it would be forced to be upper case. It is not reasonable to force a "technical restriction" on the vast majority.
Consistency
By using the LSL pseudo namespace it means that the bulk of the LSL knowledge, page names starts with "LSL_". Do not disregard this as an advantage. Names that start LSL are disambiguous.

Issues created:

Templates templates templates
Yes they are annoying but so is learning a new language, which you had to do at some point to edit pages on any wiki. I've tried to make the templates as easy to use as possible. There are always editing guidelines, its easy enough to put the template usage requirements in there. The advantage of using templates, it is easy to change the layout without having to go through 360 plus pages individually. Course it helps to write them with a sane interface to start with.

When it comes to generic articles, I don't see a need for the LSL prefix; articles on generic topics aren't unique to LSL. But when you are talking about pages on specific functions, events or types; then it should be required. Mostly because, LSL has its own unique quirky restrictions. The LSL documentation should never accidentally lead to a page that ambiguous. When you are talking about a programing language you do not want ambiguities in the documentation. Programing languages are not ambiguous, they are well defined.

A subwiki? no, but a subsection of the wiki yes. It should be interlinked with the rest of the wiki on pertinent topics. Unfortunately there is still almost no content on the wiki. 1/3 of all the articles on the wiki are the LSL function stubs. Another 2/5 of the pages are Message Layouts (stubs). What is left has almost no applicability to LSL.

LSL as a prefix really isn't all that bad and shouldn't be a show stopper. We can always rename the pages (it's a mediawiki feature. But till then it would be best to maintain consistency.

Strife Onizuka 09:10, 31 January 2007 (PST)

Apologies for not replying sooner. I'm have to say that not everyone has as much time to work on the wiki as they'd like to have, but I think our factual arguments should be considered equally. Talk is indeed and thankfully cheap, since it's how contributors stop themselves from getting married to an idea and then offended when flaws are pointed out. Procedures haven't solidified here yet, but on Wikipedia, those people who keep doing things after they're asked to slow down and discuss, we call them "blocked". (It's a preventive measure, not a punitive one.)

I see a few things I'd like to reply to:

I don't understand exactly what naming "ambiguities" you're trying to prevent. I'm pretty sure that, on such a narrow topic as SL, there won't be many such pages which would merit so much detail that they can't be on the same page.
Uhh... o.o Splitting audiences is not a benefit! Why do you want to separate the audiences? Do you not like Summary Style? You don't need something in the lede as clumsy as you claim - you can just have something like "llSetText is an LSL Function that ...". (Besides, "LSL Scripting Language" would mean "Linden Scripting Language Scripting Language"...) Many, many Wikipedia articles start that way - think about who is using the articles. For those who jump into something too complicated, they should have a link back to basic articles.
The technical restriction can be gotten around with a css/javascript workaround, if LL chooses to do so. (The "lowercase" template mentioned earlier needs its other component to actually work the way it works for Wikipedia articles like eBay.)
Why does there need to be a naming convention for something that doesn't lend itself to one? I can understand calling unnamed historical hurricanes "___Place___ Hurricane". But all pages that are categorized as LSL should start with "LSL"? That doesn't make any sense to me. There's no need for a "consistency" here any more than all articles on mathematics on Wikipedia should end with "(math)" or whatever.
Why move to the official MediaWiki if you're going to fork the pages and then introduce archaic syntax again? Although I understand the need for such obscure new methods - Wikipedia's WikiProject Tropical Cyclones (of which I'm a part) works the same way, with tons of infoboxes and special template codewords. But to such a degree as to override so many MediaWiki functions? I'm sure this literally broken syntax isn't better than the old LSL Wiki's syntax, and perhaps worse. It's not accessible to newbies like MediaWiki syntax is (i.e. on the "where the hell is that typo!?" level), and it sure isn't accessible to Wikipedia veterans. I'm sure this isn't what Linden Labs was imagining when they started merging the wikis. Subsections to wikis are done through categories, not an article naming convention.
You seem to be missing a few problems that come up in this. Every single addition of a page to a category will need to have a name sorting bypass, or else everything will be sorted under "L". What about LSL images? What about cross-category pages like "weapon" or "script" or "mass" or "velocity" or....? Are these technical enough for the LSL part of the wiki? How do I memorize which ones are where? (Ironically, now those are ambiguous because I don't know where to look for it!) If the "LSL" is hardcoded into a template and I need to get rid of it, how do I override it?

I'm sure more things will start cropping up as it gets used. I've learned that tools like AutoWikiBrowser can't move articles, so please don't keep adding more pages named like this - it's going to be very difficult to undo already! Celierra Darling 19:02, 3 February 2007 (PST)

Too much text for my eyes to handle.

Don't use a pseudo namespace for now (nevermind the fact that they're not even using pseudo-namespace syntax- LSL llAbs should be LSL:llAbs)
Move all functions that currently use the broken pseudo namespace scheme to whatever minus the superfluous LSL prefix.
Categorise all functions under Category:LSL Functions (which should technically be Category:LSL2 Functions, but I don't think anyone cares about the 2)
If demand requires it at a later date, ask Rob to setup a custom namespace in the MediaWiki install, and move all articles under Category:LSL Functions to the new LSL namespace. (Which would, of course be LSL).

Summary: LSL llAbs -> llAbs, later to LSL:llAbs if we need it. MediaWiki is limited, so if things like http_response required an article that had that name but without the underscore, you'd do http response (context). The only other disambigs you'd need to use would be for any OSSL class names that for some reason match LSL function calls. IF, and only if lots of those crop up, should everything be moved over to custom namespaces (e.g. LSL and OSSL)

SignpostMarv Martin 21:40, 3 February 2007 (PST)

One contention of mine, is that MediaWiki was not designed with technical documentation in mind, nor is Wikipedia a wiki that provides technical documentation (not targeted at least). What works for Wikipedia doesn't work everywhere else; it is an accepted fact that very little is universal. Open any programing language manual. You aren't going to see headers on every page reiterating that you are reading a manual. Sure it may help someone opening the book to the middle but does that serve the person who is using it as a technical reference? No it does not, it wastes their time. The person who is reading it for the technical content should not be waylaid by information for the non-technical readers. Which brings us to the big discussion. What is the purpose of the wiki? What is the focus, to provide general information or technical information? LSL is a technical topic. If we want to have a successful resource it needs to be focused on technical articles with general articles filling the gaps.

You ask about ambiguities: permissions. In LSL there are two types of permissions, script permissions and asset permissions; both have their own set of functions and events. I don't even want to consider how the "permissions" article would look if had to include the other types of permissions that may be lurking though out SL.

Didn't know that using the namespace:title format would get around the naming issue. Probably a good idea to use it. I may write a tool in python to move the pages (leave redirects and create new pages). But considering the current dispute I'll hold off on that. Strife Onizuka 04:12, 6 February 2007 (PST)

(Sorry SignpostMarv, I'll keep it short this time.) Strife, it sounds like you are editing as if you were writing an API. To be frank, you're not: this is the SL Wiki, and articles aren't and shouldn't be a reference book for experienced programmers. This is not just an API. It's a general reference tool for Second Life citizens, not just LSL scripters. Celierra Darling 16:48, 9 February 2007 (PST)

umm LSL is an API and we are writing the documentation for it. "articles aren't and shouldn't be a reference book for experienced programmers" This I have to disagree with you. The place for reference material on SL belongs on the official SL wiki. There should be a core of articles that describe the technical workings of LSL on this wiki because the source for LSL is on this wiki (the implementation for the functions aren't in the source but the compiler and the VM are). The articles on the wiki should be a reference book and a teaching guide but a reference book foremost. Sure the articles should try to achieve both, but they fail if they lack the reference material. The purpose of any explanation or teaching material, is to explain or express the reference material in a fashion that is more readily understandable to the novice. Having both on a page is logical (but so is separating them).
Please help us design better layouts and templates because at this time we only have a few layouts. Being consistent in layout and appearance aids anyone reading the articles, which is one of my goals.
Personal I like documentation that is concise; Why spend a page describing what a few sentences can do? I am not scared of looking up words or terms, google and wikipedia are great for this, concise complex sentences work for me. I really like code examples, when I'm learning something new, I like to see it in action. I like to know the syntax and it's limits. I like to know about related functions and topics. A page describing how it can be used is less useful to me then a couple examples showing it in action. But people learn differently I understand this and accept it. Layouts need to be designed with this in mind.
Strife Onizuka 19:34, 9 February 2007 (PST)

LSL is so simple that anyone can pick it up.

The documentation for the function should be written for everyone. The only reason documentation on LSL should be aimed at technically minded people, or as Celierra says; experienced programmers, is if you were writing documentation for how LSL operates on the server-side.

The average user of HTML does not read the W3C specification of the format(s) (I'm told even the most geekiest of geeks don't even touch the SGML spec with a gigaprim barge pole). The average user of HTML reads things like W3Schools.com

Rather than batch-moving the LSL articles from LSL_llFunction to LSL:llFunction, it might be better to "freeze" the LSL_llFunction articles and discuss an easier to understand format under Talk:LSL Portal.

SignpostMarv Martin 18:23, 9 February 2007 (PST)

An easier to understand format? Be my guest to redesign the layouts. But remember that people learn differently. I would not advocate freezing anything until a replacement has been designed. Talk is cheep and shouldn't be used as a reason to stall progress. It will be easy enough to migrate the information from the pages that use templates. OMG I *hate* the W3C specs (putting an entire spec on a single page is sick) though I'm never satisfied with w3schools. Strife Onizuka 19:35, 9 February 2007 (PST)

There's some confusion of what I said - I'm not saying that the technical details have to be excluded, but the simple things must be included. The beauty of a wiki, as opposed to a programming language manual, is that including the "simple things" is as easy as "___ is an LSL function that is passed a avatar's key and...". Also, making sure not only the most experienced programmers can understand refers both to article content and the MediaWiki syntax. You seem to be disturbingly willing to push away a large portion of your audience and force the remainder to climb a steep learning curve to let them contribute.

About the focus of the wiki - you seem to disagree about what "API" means. Have you ever tried to learn Java from the API instead of the tutorials? From what you're describing, I think you want something like Java's tutorials, not the API, but you still call it an "API".

There is a sort of "freeze" already in place, but no one's heeding the big notice at the top of the page, apparently. Celierra Darling 15:23, 10 February 2007 (PST)

See the following:

Things like function ID, energy, script delay etc can/should all be put into an {{#ifeq:{{{1}}}|foo|bar|}} based lookup template.

The function and type templates are configured to not display a wiki link if they're included on a page titled after themselves- e.g. llAbs will get displayed as a wiki link everywhere except LSL:llAbs.

SignpostMarv Martin 15:30, 10 February 2007 (PST)

You don't have to do anything special to keep pages from self linking, MediaWiki won't let you do it by default. I peaked at your templates... didn't think they were rigid enough. Don't think it provides enough structure. Why not post your layout ideas on the LSL Function Style? Just throw up a horizontal divider and post below it.

@Celierra: About limiting the audience, we need to make a cut off somewhere. We got my Aunt her first computer last month. I was teaching her the basics of the internet. I had to explain that google was not the internet but a website on the internet. She is a smart women and I know she will eventually get a grasp on things. Despite how simple LSL is, it is beyond her.

There are about a half dozen people (give or take a few) working on LSL content. During the time of the LSL wiki this was true. A freeze is only effective if there are people to talk about how things should be done. Half the people tend not to participate in discussions. It isn't much of a community discussion if only two or three people are talking. If the discussion were going somewhere at a fast pace, not being stretched out over weeks, I'd heed the freeze but it's not. Sure we have had quite a bit of talk but it hasn't materialized into a plan. The frozen plan isn't bad, it provides room to grow and is easily changed (yah templates). The frozen plan is nicely situated on LSL Function Style and has gone unchanged now for about two weeks. No changes in two weeks says to me that people are content with the layout, actions do speak louder then words.
Strife Onizuka 16:26, 10 February 2007 (PST)

Strife, now you're just being elitist.

By making the articles too technical you will put people off wanting to learn (you said yourself you don't want to look at the W3C specs).
Your templates are needlessly complex.
Plowing ahead with creating new articles despite well founded opposition is not only arrogant, it's damn rude.

Regarding your claim that "actions speak louder than words", did you ask around on people's talk pages ? Did you leave messages in the Scripters of Second Life group ?

Second Life is a multi-cultural environment with people with a wide variety of skill levels. The overly complex templates and your elitist attitude towards excluding users not only makes it difficult for english speaking/reading Residents to learn LSL, but makes it incredibly difficult to translate the articles into different languages.

This is meant to be a community resource, not a technical manual.

SignpostMarv Martin 18:16, 10 February 2007 (PST)

P.S.: A lot of these are yours- lending further weight to the notion that you should stop plowing ahead with creating the LSL articles yourself.

Mono

Just to stir things up, what are we going to do when the VM is changed to Mono? All the functions & events will need to be updated to include examples in other languages. Maybe we should write the documentation without a preference for LSL at all. Design it more like the MSDN .Net documentation. Strife Onizuka 04:12, 6 February 2007 (PST)

IRC?

Where can we chat about the Wiki and with Rob & the other Lindens whilst we work on this? Talarus Luan 15:03, 29 January 2007 (PST)

Try #opensl on EFNet. Celierra Darling 22:12, 30 January 2007 (PST)

Function & Event Prefix for titles

Checkout any function of event page...
sensor llSensor
and tell me what you think of the Function & Event prefix on the main box title. Struck me as possibly a good idea so that the pages can be told apart. Strife Onizuka 18:13, 10 February 2007 (PST)