Difference between revisions of "Talk:LSL Function Style"

From Second Life Wiki
Jump to navigation Jump to search
 
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
==Coding Standards?==
== Old Talk ==
Is there going to be any debate regarding the use of CamelCase, javaCase, or coding standards? Thoughts? Opinions? Flames >> /dev/null [[User:Talarus Luan|Talarus Luan]] 18:28, 24 January 2007 (PST)


:Use the style guide from the old wiki [[User:Gigs Taggart|Gigs Taggart]] 15:38, 25 January 2007 (PST)
[[{{FULLPAGENAME}}/Original Design Discussions]] -- All the conversations we had when things were first being made. Much of it not applicable since the style morphed to include some of the presented concerns.
::Anyone wanna volunteer to write our own sanitized version of that? ;) [[User:Talarus Luan|Talarus Luan]] 19:03, 25 January 2007 (PST)
:::I'll start. I'll probably "clean room" it to minimize any copyright issues. I'll get started in the next day or so. [[User:Radslns Hutchence|Rads]] 18:28, 12 February 2007 (PST) PS.. is there a command to timestamp entries like this?
::::* <nowiki>~~~</nowiki> produces [[User:SignpostMarv Martin|SignpostMarv Martin]]
::::* <nowiki>~~~~</nowiki> produces [[User:SignpostMarv Martin|SignpostMarv Martin]] 13:15, 14 February 2007 (PST)
::::* <nowiki>~~~~~</nowiki> produces 13:15, 14 February 2007 (PST)
::::[[User:SignpostMarv Martin|SignpostMarv Martin]] 13:15, 14 February 2007 (PST)


== Specification ==
== Style ==
<div style="padding: 0.5em">
returns random number in range [0,mag)
{|
|-
| [[LSL_Energy|Energy]]:
| 10.0
|-
| [[LSL_Sleep|Sleep]]:
| 0.0
|-
| [[LSL_Function_ID|Function ID]]:
| 8
|}
</div>
[[User:Dimentox Travanti|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. [[User:Strife Onizuka|Strife Onizuka]] 10:46, 25 January 2007 (PST)
There has been some discussion on Jira about the style and the writing and it's been suggested that the style could use some tweaking. Since it's been over a year I thought it would be a great idea if we took the time to discuss the shortfalls and successes of the style along with any new ideas. What ever is decided I'll endeavor to implement be that a small rework or an entire refit. -- [[User:Strife Onizuka|Strife Onizuka]] 07:08, 17 May 2008 (PDT)
:Actually Looks good with that.. [[User:Dimentox Travanti|Dimentox Travanti]] 10:53, 25 January 2007 (PST)


== Looks good ==
==Deep Notes==


Seems to work well. it flows, and concise info.
Deeps notes would be an section with advanced information about implementations, specifications, and highly technical details; not to mention tracking the history of the function and the state of specific bugs.
[[User:Dimentox Travanti|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"[[User:Strife Onizuka|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.
[[User:Talarus Luan|Talarus Luan]] 11:03, 25 January 2007 (PST)
:I have made up a test template for functions, hence: [[Template:LSL_Function]] [[User:Talarus Luan|Talarus Luan]] 12:44, 25 January 2007 (PST)
 
Creating it as a template is a good idea.  And parts can be sub-templated out.
--[[User:Thraxis Epsilon|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 [[User:Talarus Luan|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? [[User:Talarus Luan|Talarus Luan]] 19:05, 25 January 2007 (PST)
 
:I was thinking of doing that, I will do it now. [[User:Strife Onizuka|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)[[User:Strife Onizuka|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. [[User:Talarus Luan|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. [[User:Talarus Luan|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. [[User:Strife Onizuka|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? [[User:Talarus Luan|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. [[User:Strife Onizuka|Strife Onizuka]] 14:51, 26 January 2007 (PST)
 
Documentation on the #if (and other commands) is available here [http://meta.wikimedia.org/wiki/ParserFunctions ParserFunctions]
--[[User:Thraxis Epsilon|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? [http://www.mediawiki.org/wiki/Help:Contents] [[User:Talarus Luan|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.
--[[User:Thraxis Epsilon|Thraxis Epsilon]] 10:50, 26 January 2007 (PST)
:I've posted a suggestion, hopefully they will consider [https://jira.secondlife.com/browse/WEB-23 Jira:WEB-23], it's for 1.9.x & StringFunctions [[User:Strife Onizuka|Strife Onizuka]] 15:13, 27 January 2007 (PST)
 
== Small issue with the LSLG template ==
 
go here: [https://wiki.secondlife.com/wiki/LSL_llShout]
 
Then click on llInstantMessage under related.  It goes to a page called lllInstantMessage.  Hope this is the right place to point this out. :)  [[User:Darien Caldwell|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. ;) [[User:Talarus Luan|Talarus Luan]] 13:32, 26 January 2007 (PST)
 
==See Also / Related Functions Redundancy==
There seems to be a bit of overlap with these two sections. Should we keep both, or consolidate to one or the other? [[User:Talarus Luan|Talarus Luan]] 13:35, 26 January 2007 (PST)
:When I was making the template, the See Also section didn't seem specific enough, I saw it more for external links and keyword documentation. We use to have things similarly organized on the old wiki (rarely would you need both sections). I'll make the See Also section evaporate (hide it by default).[[User:Strife Onizuka|Strife Onizuka]] 14:40, 26 January 2007 (PST)
::Hmmm.. how about "Related Functions" being a sub-subsection of "See also"? Would have to play around with the formatting a bit to make it concise, but that's an option. [[User:Talarus Luan|Talarus Luan]] 18:34, 26 January 2007 (PST)
:::Thats not a bad idea. Could subdivide it into various sub-sections. I'll get on it. [[User:Strife Onizuka|Strife Onizuka]] 15:08, 27 January 2007 (PST)
 
== LSL Syntax Template? ==
 
Any word on when we might see this implemented? [[User:Talarus Luan|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?).[[User:Strife Onizuka|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) [[User:Talarus Luan|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. [[User:Strife Onizuka|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 <nowiki>[[LSL ____|_____]]</nowiki>).  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? [[User:Celierra Darling|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 [[User:Celierra Darling|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.
::[[User:Strife Onizuka|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 [http://en.wikipedia.org/wiki/Wikipedia:Summary_style 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!  [[User:Celierra Darling|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)
::::[[User:SignpostMarv Martin|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. [[User:Strife Onizuka|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.  [[User:Celierra Darling|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).<br/>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.<br/>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.<br/>[[User:Strife Onizuka|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 [http://w3schools.com 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]].
:::::: [[User:SignpostMarv Martin|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. [[User:Strife Onizuka|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 [[argument|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. [[User:Celierra Darling|Celierra Darling]] 15:23, 10 February 2007 (PST)
 
::::::: See the following:
:::::::* [[User:SignpostMarv Martin/Sandbox/llAbs|LSL:llAbs]]
:::::::* [[User:SignpostMarv Martin/Sandbox/Template:LSL/function|Template:LSL/function]]
:::::::* [[User:SignpostMarv Martin/Sandbox/Template:LSL/variable|Template:LSL/variable]]
:::::::* [[User:SignpostMarv Martin/Sandbox/Template:LSL/type|Template:LSL/type]]
:::::::* [[User:SignpostMarv Martin/Sandbox/Template:LSL/function id|Template:LSL/function id]]
:::::::Things like function ID, energy, script delay etc can/should all be put into an <nowiki>{{#ifeq:{{{1}}}|foo|bar|}}</nowiki> 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 [[User:SignpostMarv Martin/Sandbox/llAbs|LSL:llAbs]].
:::::::[[User:SignpostMarv Martin|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.<br/>[[User:Strife Onizuka|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.
:::::::::[[User:SignpostMarv Martin|SignpostMarv Martin]] 18:16, 10 February 2007 (PST)
:::::::::P.S.: A lot of [[Special:Wantedpages|these]] are yours- lending further weight to the notion that you should stop plowing ahead with creating the LSL articles yourself.
::::::::::Good point about internationalization. As you point out, internationalizing the templates will be tricky if not impossible. There should be a separate discussion about it.
::::::::::The articles as they stand are too technical. I admit it, it is my goal to get the technical content onto the wiki and setup the categories. Sorting out the technical content and descriptions is the easy part of the documentation. There is space in the templates for less technical descriptions.
::::::::::There are a lot of unwritten articles. Most are for constants (there are about 360 constants last time I counted). On the old wiki a good number of constants had their own pages. It seemed to go without saying. Know you bring it up, it was a mistake of me to assume, there should be a separate discussion. As to the other unwritten articles, leaving hanging links is just what you do on wikis. It shows where content is needed.
::::::::::Please consider this question: Why can't it be both a community resource and a technical manual?
::::::::::[[User:Strife Onizuka|Strife Onizuka]] 07:17, 11 February 2007 (PST)
 
:''The nesting of this topic is getting to be a pain in the ass. See the sub-topics below for further discussion''
 
=== Internationalisation ===
Good point about internationalization. As you point out, internationalizing the templates will be tricky if not impossible. There should be a separate discussion about it.
<br />[[User:Strife Onizuka|Strife Onizuka]] 07:17, 11 February 2007 (PST)
:[[Talk:LSL_Portal#Internationalizing|Moved to Talk:LSL_Portal#Internationalizing]]
 
=== "LSL:" vs "LSL " ===
I've done some quick tests, and if we use LSL: instead of LSL_ as our prefix, we will still need to prefix every link with LSL: otherwise it will default to the main namespace. For ease of use we would probably still be using a template to do it (moving existing content won't be difficult and changing the template for the links will mean none of the pages will need editing).[[User:Strife Onizuka|Strife Onizuka]] 07:17, 11 February 2007 (PST)
: Actually, I've just thought of something. Should the LSL pseudo-namespace be reserved for such a time as when the Mono/LSL VM source is released ?
: As per the response of Robin Linden in {{JIRA|WEB-22}}, neither "'''''LSL:'''''" nor "'''''LSL '''''" should be used in the article titles at all. Going back to the original proposal of not including any prefix in the article at all. Regarding your concerns for capitalisation, MediaWiki doesn't care whether you enter it in capitalised or non-capitalised, it'll go to the same article- so all the links pointing to the relevant article can be non-capitalised.
:[[User:SignpostMarv Martin|SignpostMarv Martin]] 08:05, 11 February 2007 (PST)
 
:: A quick note, you mentioned nobody editing the style page as evidence of it stabilizing.  But this doesn't show that the ''name'' of the pages are agreed upon.  The "LSL" in the name of ''this'' page is appropriate, especially if you don't have the pseudo-namespace thing going on - it really is a style guide for LSL functions, and not, say, Mono functions or functions of the client or server in the "features" sense of the word. [[User:Celierra Darling|Celierra Darling]] 16:58, 12 February 2007 (PST)
::: The namespace issue isn't unique to functions. The discussion of it doesn't even belong on this page. It is a global style issue.<br/>I made the point to back the use of the current templates instead of SignpostMarv's new templates that don't work for the so far agreed upon Function Style. Since there is only one style proposed on Function Style, it makes sense that it should be what we use; if there were a second proposal on the page things would be different. [[User:Strife Onizuka|Strife Onizuka]] 08:06, 13 February 2007 (PST) <br/> P.S. What has not yet been argued is if the user must use the templates (but that is off topic).
::That comment is old and since then he has made comments that decent from that one. It is my understanding of the current situation that Rob sees the validity in the argument for some separation. This has become a political matter, and he may be unlikely to step into the center of it. [[User:Strife Onizuka|Strife Onizuka]] 08:06, 13 February 2007 (PST)
:::That is incorrect.  Rob posted just today that he sees no point in separation and says we should either merge conflicting pages or create disambiguation. [[User:Gigs Taggart|Gigs Taggart]] 09:52, 13 February 2007 (PST)
 
I haven't really said much on this topic (beyond being very busy with RL/SL projects the last few weeks), mainly because I don't have any real valid opinion on the subject. All I care about is being able to easily and quickly get to the information I need. I don't figure there will be a lot of disambiguation pages for a majority of the LSL Portal Wiki content, so if using pseudo- or real-namespaces presents other problems (the capitalization issue is largely cosmetic and, even though I abhor CSS/Javascript hacks, if it works, use it), perhaps we should not use them. I definitely don't want to have to type "LSL:" or "LSL_" in front of function/topic names to get to the correct page, and I think the concept of making redirects for them to make that work is kinda redundant and wasteful.
 
I also don't believe that there is a "universal way to do it right"; that means I don't believe in the notion that, just because Wikipedia uses a convention, that it is also the best way to do it for the LSL Portal part of the SL Wiki. Different problems require different tools and different tactics to solve said problems.
[[User:Talarus Luan|Talarus Luan]] 13:33, 15 February 2007 (PST)
 
: There is no "LSL Portal part of the SL Wiki"; the phrase is nonsensical to me - the way I see it, these portals should organize information and perhaps identify what needs to be worked on first, not constrain the wiki into strict subtopics.  I'm pretty sure this is meant to be "almost everything about SL", not "these three subtopics of SL".  In the former context, Wikipedia is a perfectly good model to start out with.  It might not be perfect (i.e. capital letters), but it works very well. [[User:Celierra Darling|Celierra Darling]] 15:34, 15 February 2007 (PST)
::I am speaking figuratively, not actually. I really don't care how the information is organized as long as I can get to what I need in the shortest amount of time and effort. If that is achieved via hard partitioning, then that's what I think we should do. If it is achieved via something more general and nebulous, then that's what I think we should do. Wikipedia is a perfectly good model to start out with -- for an encyclopedic-type generic reference work. It is WOEFULLY (and that part comes from my trying to use it to find good reference works in the past) inadequate as a technical reference work. Thus, my contention that what works "perfectly" for Wikipedia MAY NOT work as "perfectly" for us. My point is that we shouldn't throw out whatever good we can glean from following Wikipedia's examples, but we should NEVER EVER assume that it is "the best way to do it" for our particular usage. It very well may not be, and we may develop a better way. I know traditions die hard, but the last thing I want to deal with is cruft coming from dogmatic acceptance of a "popular" way of doing things. [[User:Talarus Luan|Talarus Luan]] 16:02, 15 February 2007 (PST)
 
=== Community Resource vs Technical Manual ===
Please consider this question: Why can't it be both a community resource and a technical manual?
[[User:Strife Onizuka|Strife Onizuka]] 07:17, 11 February 2007 (PST)
: Purely because a large percentage of the community are not technically minded.
: [[User:SignpostMarv Martin|SignpostMarv Martin]] 08:05, 11 February 2007 (PST)
 
: Wait, what?  I thought that's what ''we'' were asking ''you''.  I probably misunderstood; define your terms, please. [[User:Celierra Darling|Celierra Darling]] 16:42, 12 February 2007 (PST)
:: I see the thread now - probably because (in that context) "community resource" is a ''superset'' of "technical manual". [[User:Celierra Darling|Celierra Darling]] 16:46, 12 February 2007 (PST)
:: I should clarify again - this is a wiki, and [http://meta.wikimedia.org/wiki/Wiki_is_not_paper wiki is not paper].  (a very important page in the world of wiki-writing, in my opinion)  There is no need to assume your audience is going to be only the technical people - you can have things for both audiences.  As I mentioned before, summary style is easy.
:: But that is a ''content'' discussion, not what I was talking about.  My intent (many posts ago) was to say that there is no need to make ''editing'' these pages such an annoying, obscure, and technical task.  MediaWiki works; stop breaking it. [[User:Celierra Darling|Celierra Darling]] 16:54, 12 February 2007 (PST)
::: Which is why we shouldn't be using monolithic templates- they make it an annoying, obscure and too technical. You'd have to put a lot of error detection/correction code into the templates to help prevent a Resident from making a mess with a monolithic template <small>(which is one of the things that puts me off working on [[Template:languages-spoken]]- I have to use PHP to generate the huge amount of Wiki code for me.)</small>
::: Modular templates that can be included in other wrapper templates or on their own <small>([[Template:SLurl]],[[Template:SLurl/simple]],[[User:SignpostMarv Martin/Sandbox/Template:LSL/function]])</small> are easier to work with, and create more visual correlation between what does what to someone who is starting out learning wiki code.
::: With a monolithic template, you restrict the design to one fixed design, and a newbie to wiki code would have to view at least 4 pages at once- the article the template is used on, the documentation for the template, the source code for the article and the source code for the template- whereas modular templates can be so ridiculously simple that they can be learnt at a glance. (seriously, take a look at the source code for [[Template:languages-spoken]] and you'll see why monolithic templates suck, although that is one of the 'lookup' type monolithic templates as opposed to a 'content' monolithic template).
::: [[User:SignpostMarv Martin|SignpostMarv Martin]] 19:16, 12 February 2007 (PST)
::::I thought the syntax for the function & event templates was pretty straight forward. If you want text in a section, you just find the variable for it and set it's value. Since there are a number of values included in all templates it provides an example for itself, to an extent. The rest is general editing which they would have to learn anyway. Already have a few people wandering through the pages, so it seems to work. Sure they are monolithic and reading them is not for the faint of heart but they provide the structure for new users to edit upon. Do you expect a new user to know how to implement the Function Style? Do you believe they would get it right? It's a lot easier to fix a botched edit when it is template parameters. Going through and correcting the syntax for a botched edit on a page that includes the complexities of the Function Style inline is going to be hell, especial as the number of contributors increase.<br/>I think having a monolithic template actually makes it easier for a new user to make quality edits. Removes the stress of getting the formatting & style correct. Look at the folks who have been writing function feature suggestions. [[User:Strife Onizuka|Strife Onizuka]] 07:38, 13 February 2007 (PST)
:::::* Your templates will force Residents to learn how to use your templates AND how to use Wiki code.
:::::** ''there are a number of values included in all templates it provides an example for itself, to an extent''
:::::** ''The rest is general editing which they would have to learn anyway.''
:::::** ''they are monolithic and reading them is not for the faint of heart''
:::::** ''It's a lot easier to fix a botched edit when it is template parameters''
:::::** ''having a monolithic template actually makes it easier for a new user to make quality edits. Removes the stress of getting the formatting & style correct.''
:::::* Your templates are overkill.
:::::[[User:SignpostMarv Martin|SignpostMarv Martin]] 13:33, 13 February 2007 (PST)
::::::In my opinion, I like the clean look and consistency of Strife's template over the muddled and inconsistent look of yours. Of course, I am probably a bit biased, as I came up with a similar template at the same time as he did, and he merged some of my ideas with his. I do believe that it is a better template, because it is meant to be a reference; if we want tutorials, we can create tutorial articles explaining the use of the functions and link them in a section of the reference. The vast majority of Wiki use is for reference; the learning curve of LSL is not super steep, and fairly quickly, folks are using the Wiki in reference mode more than learning mode. As such, I prefer a nice, clean, consistent layout, where info is nicely ordered and I can very quickly and easily get the piece of information I need to continue doing my job. I don't want my job to become a Wiki-ized version of "Where's Waldo" in a disorganized, inconsistent reference article. In a perfect world, we would be using something like XML/XSL, entering the content in XML tags and leave the formatting of the page to an XSL stylesheet "template". There is a great beauty in being able to just throw the content in without having to worry about how it is formatted, and also having a single point of control for the look of similar articles, especially for ones like the LSL function reference articles. In this situation, I love the notion of putting data as parameters in a single template, because it mimics (with some advantages) the XML/XSL "ideal" the closest.
::::::I don't expect Joe Shmoe off the street to just jump right in and edit Wiki articles. I want people who a) know their subject matter, and b) have spent the time learning how to contribute to the Wiki. I didn't contribute to the old one until I had done both; why would I expect anyone else to be any different in this regard? Yes, there is a bit of a learning curve using the monolithic template, but not significantly more so than learning how to effectively contribute overall.
::::::[[User:Talarus Luan|Talarus Luan]] 13:57, 15 February 2007 (PST)
:::::::I say ditto"" to what Talarus has said above.  His post sums up my usage of the wiki.  My opinion is that Strife's function template is good.  I like the straight-forward information it presents.  Like Talarus says, most people will use the function pages as a reference, not a tutorial or how-to.  And even those who use it as a how-to will only do so once... future visits to the page will be reference visits.  At the old wiki, information was buried within paragraphs and comments.  I might remember reading something, but not exact details, so I'd have to explore the old wiki, reading a few pages until I found what I needed again.  Strife seems to have the important aspects of the functions in easy-to-read sections.  But, why can't we have the best of both worlds?  Use Strife's template version as the reference/tech manual section, and a long-form description for those who need more than nuts and bolts... all on the same page.
:::::::[[DoteDote Edison]] 19:30, 15 February 2007 (EST)
:::::::: I would like to go in and rewire a few things before the pages get renamed. I would say "deployed", but Strife has been doing that anyway....
::::::::[[User:SignpostMarv Martin|SignpostMarv Martin]] 16:36, 15 February 2007 (PST)
 
::::::::I would love to take credit for the layout but I really only made a few changes to what had already been created. On the bits I have designed in the layout, it has been to allow for information to be easily found. Downplay the parts less important and organize it so the layout improves the readability. For example the main box with the parameter descriptions, the types are in gray and everything is evenly spaced. I found it hard to find the parameters I wanted to read about other wise. I've started to use a similar layout in the Also section to attach descriptions to function names (and have the names all start in the same places). Just had a good idea, will be the last change before I start rewriting the templates (the rewrite won't change the features almost everyone seems to have liked about it). [[User:Strife Onizuka|Strife Onizuka]] 09:25, 16 February 2007 (PST)
 
=== [[User:SignpostMarv_Martin/Sandbox/Template:LSL/type]] ===
Having all the types point to a single page isn't a good idea, there is a lot of information about each type and putting them on a single page doesn't seem like the best of ideas. For one it has the potential to complicate the categories. [[User:Strife Onizuka|Strife Onizuka]] 08:18, 13 February 2007 (PST)
:#It's a launching point. Take a look at [[User:SignpostMarv_Martin/Sandbox/LSL/types|the article]] now. It's trivial to change the template to point to more in-depth articles.
:#Duplicating the entire content of the [http://en.wikipedia.org/wiki/Quaternion Wikipedia article for quaternions] would be be mostly useless, as would duplicating the content from a standardised format specification.
:If it's possible, we should consider having an "overview" article that is used as the launching point for new comers to read about the data types.
:[[User:SignpostMarv Martin|SignpostMarv Martin]] 13:01, 13 February 2007 (PST)
 
==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. [[User:Strife Onizuka|Strife Onizuka]] 04:12, 6 February 2007 (PST)
:I disagree:
:# The current language in use is Linden Scripting Language.
:# The Mono VM has yet to be released on a publicly accessible grid (only Soma)
:# The function names will likely stay the same.
:The correct course of action would be to keep the articles LSL-centric, wait and see what happens when Mono is released on the Beta grid (it'll be rather odd if LL release it on the main grid first :-P), then consider whether to make the articles language-agnostic.
:I would imagine all that'll need to be done is to update the usage examples to include language-specific implementations.
:[[User:SignpostMarv Martin|SignpostMarv Martin]] 08:26, 11 February 2007 (PST)
::Seconded, the mono VM is going to run pure LSL into the forseeable future.  It's doubtful LL will ever realistically add new languages to it. [[User:Gigs Taggart|Gigs Taggart]]
:::Mono is the open source .Net VM. LSL is being compiled to CIL to run on Mono. This means given the proper class layout etc you could write code targeting it in any .Net language. Since CIL is language agnostic there will be no way for LL to know what programing language you wrote your script in (LSL is compiled by the client software). Sure LSL may be the official language but with mono, LSL will also be a class to inherit functions from (I assume). The question is, what do we do then? [[User:Strife Onizuka|Strife Onizuka]] 06:22, 13 February 2007 (PST)
::::You are assuming compiling will still be client side.  It might be, it might not be.  Does anyone know for sure?  They are going to definitely have server-side compilation so as to migrate the existing scripts to the CLI.  They might decide to just reuse that code instead of hacking up the client.  [[User:Gigs Taggart|Gigs Taggart]] 06:29, 13 February 2007 (PST)
:::::Having a centralized compiler is CPU intensive, it does not scale. It makes more sense to allow users to upload compiled bytecode. They already have the compiler written to output CLI and LSO. They would have to rewrite the client & sim to remove the compiler and place it elsewhere. Anyway it is there intention to support other languages (to put it bluntly, LL knowns that LSL is not the easiest to use language). [[User:Strife Onizuka|Strife Onizuka]] 07:44, 13 February 2007 (PST)
::::::I say just document LSL for now.  Any other libraries that happen later can get their own wiki. [[User:Gigs Taggart|Gigs Taggart]] 09:25, 13 February 2007 (PST)
:::::::Yes burning that bridge when we get to it might be a good idea.[[User:Strife Onizuka|Strife Onizuka]] 09:30, 13 February 2007 (PST)
 
== IRC? ==
 
Where can we chat about the Wiki and with Rob & the other Lindens whilst we work on this? [[User:Talarus Luan|Talarus Luan]] 15:03, 29 January 2007 (PST)
 
Try #opensl on EFNet. [[User:Celierra Darling|Celierra Darling]] 22:12, 30 January 2007 (PST)
 
== Function & Event Prefix for titles ==
 
Checkout any function of event page...<br/>
{{LSLG|sensor}} {{LSLG|llSensor}}<br/>
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.
[[User:Strife Onizuka|Strife Onizuka]] 18:13, 10 February 2007 (PST)
 
== Templates & Getting started ==
 
Are the templates too complex? We should probably have a page describing how to contribute and getting people started with the templates. [[User:Strife Onizuka|Strife Onizuka]] 07:48, 11 February 2007 (PST)
 
: Since the feedback seems to be that your design is more structured, I could clone & dive into the code to rewire things and give them that "Marvulous" touch :-P
: [[User:SignpostMarv Martin|SignpostMarv Martin]] 11:46, 16 February 2007 (PST)

Latest revision as of 06:11, 17 May 2008

Old Talk

Talk:LSL Function Style/Original Design Discussions -- All the conversations we had when things were first being made. Much of it not applicable since the style morphed to include some of the presented concerns.

Style

There has been some discussion on Jira about the style and the writing and it's been suggested that the style could use some tweaking. Since it's been over a year I thought it would be a great idea if we took the time to discuss the shortfalls and successes of the style along with any new ideas. What ever is decided I'll endeavor to implement be that a small rework or an entire refit. -- Strife Onizuka 07:08, 17 May 2008 (PDT)

Deep Notes

Deeps notes would be an section with advanced information about implementations, specifications, and highly technical details; not to mention tracking the history of the function and the state of specific bugs.

Retrieved from "https://wiki.secondlife.com/w/index.php?title=Talk:LSL_Function_Style&oldid=67774"