Wiki Style Guide
Were you looking for the
LSL styleguide?
Edit this page! If you see something that's not done, needs clarification, has changed or is just plain wrong,
fix it.
Page Creation/Editing
- The SecondLife Terms Of Service and Community Standards apply to the wiki.
- The wiki is PG (as defined in the Community Standards).
- Capitalize the page's title and use 5 "=" signs to indicate it's a title.
- Use 3 "=" for subtitles and capitalize the first letter: Functions, Events, Constants, etc.
- Creating a new page: write the title using CamelCase. "WikiStyleGuide", for example. The actual page title can be written according to normal English conventions.
- Naming a page for a function, event, or constant: name it and link to it as the element appears in the code itself. "llSetScale", not "LLSetScale" or anything else.
- Linking to another page from text within the body of a page: linking in CamelCase is unnecessary (especially in titles/headers). For example:
- Expressing a short element of code, such as a function or variable name: use the monospaced tags. (##monospaced tags##). When embedding a larger script, contain it within code tags. See more at WikiFormatting.
- Make sure your new page links back to the relevant sections, and only the relevant sections. You don't need to place a link at the bottom of llSetColor linking it to the money() event.
- Spell check the page. IE: IESpell, Firefox: SpellBound
- Check to make sure any changes do not break pre-existing formatting on the page.
- Similarly, only place a link to the new page on relevant pages. There doesn't need to be a link to "ExampleFrogScript" on a texturing page.
- Contributing to the Examples or Library: name the new page in the form "ExampleFrogScript", or "LibraryFrogScript". This allows us to easily sort pages into categories.
- If in doubt about what fits where, find a similar page and copy the layout.
- Do not create pages for/as feature suggestions. There are proper places for feature suggestions, see: LSLFunctionRequest.
- If a feature suggestion is to be included on a wiki page it should be at the bottom of the page, in it's own box. In the box, text at the top declaring it a feature suggestion with Vote or Forum threads discussion it and finaly a simple explination as to how it would work. If the box has more content then the rest of the page (excluding comments and bottom links) the page will be considered as having been created for/as a feature suggestion and in violation of the previous rule.
- Pages for functions that do not exist should be clearly marked at the top, such marking should be devoid of comments (and opinions).
- Do not post content on a page to which there is little or no relevence.
- Do not put syntax for functions that do not exist on the wiki (this will only lead to confusion).
- Do not revert a page if you disagree with an edit, unless the edit entirely conflicts with one or more of the editing guide lines found here, WikiFormatting or WikiEtiquette.
- Stylesheet overriding should only be done on user pages.
- If an author wishes to implement a new style, they must first add it to this page (or to the page for the style guidelines for the group); unless it only effects a small subset of the pages in a specific group on the wiki and does not conflict with existing style guidelines. An example group is the ScriptLibrary. +
- Don't get mad if people edit your page; that's the point of a wiki.
Function/Event Format
integer llDoSomething(vector where, string what, integer why, integer really)
This function does something. You can define where, what and why to do it.
The boolean parameter really determines if it will be executed (TRUE) or not (FALSE).
It returns a boolean value that determines if something was successfully done (TRUE) or not (FALSE).
Example:
llDoSomething(<1.0, 1.0, 1.0>, "hey ya", 23, TRUE)
The above code does something really interesting.
Functions | (other sections of the Wiki this relates to) |
Q: It seems 'other sections' is currently interpreted in various ways, sometimes referring to general areas (e.g. references to functions, rotation, constants), related concepts (e.g. the big list on rotation), other times as an 'see also these pages' (e.g. the links on and towards LIFO). Was this meant purely as categories or is this essentially up for 'what makes sense for you?'
Q: There indeed seems to be a style difference, using either | or / to split these. Looking at the some of them, such as the list on llRequestAgentData, it seems these are not meant as trees, which / suggests to me - and of course, categories will sometimes work out as rough trees, which can be nice. But is there a central idea to this, or is this an as-you-see-fit thing too?
Code Example Text Boxes
Text boxes should be used for
code examples. For
LSL code, use %%(lsl), for PHP code use %%(php), and for everything else use just %%. This saves you from the horrors of escaping parts of the code that the Wiki would interpret as formatting instructions and keeps pages easy to edit.
Examples
Keep examples short and to the point. You probably don't need to include things like
variable declarations and the such for most snippets.
Single Wiki Name Linking
Link the same
WikiName only once per entry. Example:
The
object with the
script does move objects and can also
link your object with other objects.
Instead of:
I think this should read: Link the same WikiName only once per entry per screen of information. As it makes for easier for the reader as they don't have to page up to find a link for the key word. So it would be OK to have 3 links to "object" as long as you couldn't see any two of the links at any one time. I remember reading this on another wiki as an acceptable linking standard.
It's a nice theory but how does one know what screen resolution, font size, etc the viewer has? 1024x768 resolution and Trebuchet MS font will be different than 1280x1024 and Times New Roman font. A better rule might be to reuse a link after x number of characters/words/paragraphs--perhaps an average "screenful" interval could be determined. Regardless, upkeeping such formatting would be more annoying than only linking to a term once per entry. -
EepQuirk
I believe fonts are specified by the meta data and tags. Overriding these would be in conflict with the standard. So your example of different fonts is irrelevant. It is safe to assume the average user uses 1024x768 as there resolution. More importantly it doesn't have to be perfect. -BW
I override this site's stylesheets because I don't like it. Standards are relative; relative to MY standard, this site's "meta data and tags" (stylesheets) conflict with my tastes. This site needs alternate styles. -
EepQuirk
Push for support for MediaWiki. As has been stated in the past, WakkaWiki, the internal engine running this wiki, sucks. This style guide is for writing pages tailored to the original style sheet layout of this wiki. If you override the original wiki style sheets to better your viewing experince, please don't make modifications to pages to custom tailor them to your particular style sheet layout. Everyone else will see them using the wiki's original style sheets. -
Chris
Self-Linking
Don't link a page to itself. If a page is named WikiStyleGuide, it shouldn't have any links that lead to WikiStyleGuide. Put
CamelCase words in double quotes to avoid automatic linking where it's not wanted.
Monospace Variable Names
Use the monospace font (##) for writing variable/event/function names. It helps to separate the actual code from the rest of the text.
In some cases, the combination of bad markup and poor choices when naming variables can be somewhat...confusing:
Bad: "The variable the is an integer. and is a float."
Better: "The variable the is an integer. and is a float."
Also, stick to a consistent style of markup. If an entry uses
bold (**) text in addition to monospace for its variables, stick to that layout. It keeps the page readable and consistent.
Singular Wiki Names
Always use singular for wiki names; never plural. Yes, we already f*cked that up on many pages, but there's no need to carry on that bad habit. Why do it? It makes formatting easier ([[function]]s is better than [[functions function]]). If all entries are singular, you won't have to guess anymore if the page you want to link to was [[types]] or [[type]].
Notes
If you want to comment about something on a page that you want added or changed, edit the page and leave a
note, (see
WikiFormatting) not a comment, as
CommentDeletion is currently not very comfortable. It is probably a good idea to indicate who is leaving the note. If you "fix" a page as a note requests, it is probably a good idea to delete the note.
There doesn't seem to be a clear cut answer to using plural links to singular pages. [[function]]s vs. [[function functions]] obviously it's wrong to doctor LSL keyword link names.
I dont think it matters much, IMO I like seeing [[function functions]] more then [[function]]s because it just... looks better :) The only confusion I can see occuring is if someone does something like [[if while]]-Chris
Note:
notes are not the same as notes about things that require special attention--like this note.
Note:
- Multiple notes can be formatted like this.
- If stylesheets are disabled, notes won't appear any different than normal text. This should be changed... -EepQuirk
Use Line Separators Sparingly
Try to use the "----" full-width line separator (also called linerules) only once per page to separate the bottom links from the rest of the page. Too many linerules are confusing and disorientating--like that used to be on this page. If in doubt, use this HTML to specify specific-width linerules:
"<hr width=50%>":
I don't jive with this one, i think full breaks should stay. On this page i don't think the 50%'s give enough seperation between the sections -BW
Well, you can always set the % greater if you want, but any wider and it will detract from the bottom linerule even more... -
EepQuirk
Seperate Relevant Sections with Whitespace
People tend to be overwhelmed if they're presented with a BIG glob of text, especially one that doesn't even respect paragraph rules. Group information together, and seperate it into 3-5 line chunks.
Direct Linden Quotes
Direct linden quotes are highlighted in
sienna, as this color is the default used by lindens in the
SecondLife forum.
To highlight text in sienna, place "<font color=sienna>" before it and "</font>" after it.
Wiki Formatting |
LSLWiki