Style Guide

From Multiverse

The following are guidelines when writing for the Multiverse Developer Wiki, not hard and fast rules. They are meant to make the information in the wiki consitent and easy to understand.

Also, see Documentation Conventions.

General writing guidelines

Follow these guidelines as much as possible:

• Use correct grammar and spelling. Use US (not British) spelling; for example, "behavior" not "behaviour", "color" not "colour", and so on. That being said, accuracy and ease of understanding are the top priority.

• Avoid awkward links; try to make hyperlinks read as proper English sentences. For example, instead of "...for more information, go here," say "...for more information on Wiki policies, see Standards and Policies."

Discussion

Each article in the wiki has a special "discussion" page for user discussion (see the discussion tab at the top of the page). Use this if you have questions or comments on an article.

When discussing an article, please sign your name after each post. You can do so with ~~~~. Using four tildes (as shown) will render like this: Quamquam 20:24, 30 October 2007 (PST). You may use three tildes instead to show only your name: Quamquam

Documentation for unreleased features

f it is a totally new feature/document:

• Create the document by addng a link in the "Platform Release (version number)" page, then click on the link to edit the new page. If such a page doesn't exist yet, just create a new page without linking to it.
• Put the special template code {{Future feature}} at the very top of the document. This will automatically insert a disclaimer saying that the feature is not in the current release.

If it is a change to an existing feature/document, it's a little more complicated and requires a judgment call:

• If it's a major overhaul of an existing feature/doc, then copy the existing doc into a temporary version-specific doc, and add the version number to the title. Then follow the steps above for a new doc.
• If it's an ADDITION to an existing feature/doc, then just edit the existing doc, but put the {{Future feature}} at the top of the section you are adding.
• If it's a CHANGE to an existing feature/doc, you can just copy the existing section but add the version number to the subsection heading and {{Future feature}} at the top of the text.
• If it's a really small change/addition (e.g. a new row in a table or a new sentence), then you put the text "in line" in the existing doc and use the {{Nyi}} template code to indicate that its "Not Yet Implemented" (in the current release).

Titles

• Make titles as descriptive as possible. For example, "How the Proxy Server Works" rather than just "Proxy Server". Often, using active verbs is a good way to indicate the task being performed; for example, "Exporting Models" rather than "Model Export".

• Page titles: capitalize all words except conjunctions (and, or), articles (the, a), and prepositions (to, from), unless the conjunction preposition, or article is the first word in the title. Examples:
  • Updating the Server
  • A Quick Explanation of the Code
  • Creating a Mob that Can Do Something

• Section titles: use "sentence punctutation," that is, capitalize the first word and proper nouns (names) only. For example:
  • Exporting from Maya
  • Installing the Maya plugin
  • Example export options

Formatting

• Use <code> tags to indicate file and directory names. For example, multiverse.sh.

• Use <pre> tags for code samples. For example:

effect = new HealEffect("heal effect");
effect.setMinInstantHeal(20);

Guidelines for tutorials

Follow these special guidelines when writing tutorials:

• Begin the tutorial with a high-level overview. State any prerequisite knowledge or software.

• Start each section with a brief paragraph or two describing what you're going to do and what the end result will be. Don't go into too much detail.

• The bulk of each subsection should consist of an ordered list of steps that the user follows. To create an ordered list element in wikitext, start the line with a pound sign (#).

NOTE: If you need to use a code sample (in <pre> tags), within a numbered list, you can't use wikitext, because it restarts the item numbering after the code block (This appears to be a bug in MediaWiki). The workaround is to use HTML.

• In each step, use active commands, e.g. "Edit the file", "Click on the button", etc. In general, imagine yourself giving the reader commands to do what you are describing.
  • You choose a menu item (Use File | Foobar for menu commands). For example, "...choose File | Save to save your file"
  • You click a button, icon, etc. For example, "...click OK to submit your changes."

Special tags and styles

We've defined a few special tags and styles for the Multiverse wiki. Use them as needed.

Server API links

There are some special custom tags you can use to link to server API Javadoc:

• <class>
• <innerclass>
• <method>
• <package>

Classes

Use the <class> tag to link to the API Javadoc for a particular server class. Enter this:

<class>fully-qualified-classname</class>

To create a hyperlink to the class in the API Javadocs, formatted in fixed-pitch font (code font).

For example:

<class>multiverse.mars.core.MarsEffect</class>

creates this: multiverse.mars.core.MarsEffect. You must use the fully-qualified class name (including all packages).

If you don't want to use the fully-qualified class name in the text, then use the "name" attribute to specify just the class name:

<class name="MarsEffect">multiverse.mars.core.MarsEffect</class>

Which yields: MarsEffect.

Inner classes can be linked by using a "|" at the inner-class boundary:

<class>multiverse.server.plugins.InventoryClient|ItemInfo</class>

Which yields: multiverse.server.plugins.InventoryClient.ItemInfo

Inner classes

Inner (nested) classes are a special case; use the <innerclass> tag. For example:

<innerclass>multiverse.server.plugins.ObjectManagerClient.GenerateObjectMessage</innerclass>

creates this: multiverse.server.plugins.ObjectManagerClient.GenerateObjectMessage.

As with <class>, if you don't want to put the fully-qualified class name in the text, use the "name" attribute. For example

<innerclass name="GenerateObjectMessage">multiverse.server.plugins.ObjectManagerClient.GenerateObjectMessage</innerclass>

creates this: GenerateObjectMessage

Methods

You can link directly to a specific method with the <method> tag. Because of the way that Javadoc identifies methods within pages, you must specify the full signature of the method (this is necessary because there might be multiple methods of the same name, but different signatures).

Use the <method> tag as follows:

<method name="methodName()">foo.bar.myClass#methodName(datatype1, datatype2, ...)</method>

For example:

<method name="apply()">multiverse.mars.core.MarsEffect#apply(multiverse.mars.core.MarsEffect.EffectState)</method>

Which yields: apply().

You can also use it without the "name" attribute, though it is likely to be pretty verbose; for example:

multiverse.mars.core.MarsEffect#apply(multiverse.mars.core.MarsEffect.EffectState).

Inner-class methods can be addressed by using a "|" at the inner-class boundary:

<method>multiverse.server.plugins.ObjectManagerClient|GenerateObjectMessage#getTemplateName()</method>

Which yields: multiverse.server.plugins.ObjectManagerClient.GenerateObjectMessage#getTemplateName()

Packages

Use <package> when you want to link to an entire package API Javadoc. Enter this:

<package>package-name</package>

To create a hyperlink to the package in the API Javadocs, formatted in fixed-pitch font (code font).

For example:

<package>multiverse.mars.core</package>

creates this: multiverse.mars.core.

Client API links

There is one special tag defined for client API: <capi>. This tag automatically creates a link to the corresponding class, and formats the text in fixed-pitch font. For example:

<capi>AnimableValue</capi>

creates AnimableValue.

You can link to a specific method by simply following the class with a period and the method name. For example:

<capi>Animation.Play()</capi>

creates Animation.Play().

The convention is to use the empty parentheses following the method name, although the link will work without them, too.

Linking to MARS scripting library classes

You can link to MARS scripting library clasess and methods similarly to Client API methods with the <mars> tag. For example:

<mars>MarsAbility</mars>

creates MarsAbility. And

<mars>MarsAbility.GetNumAbilities()</mars>

creates MarsAbility.GetNumAbilities().

Tables

We have a special "mvtable" style class for tables. Use it like this:

{| class="mvtable"
! Column headings
...
|---
| Table cells
...
|}

For example:

Templates

Templates are a great MediaWiki feature that lets you copy in another document by reference. The fancy term for this is transclusion. It's kind of like a #include in some programming languages, where it just copies in the current content of the file.

Use a basic template like this:

{{template-name}}

Some templates take parameters, either named or implicit, like this:

{{template-name|Value of first param|Value of second param|...}}

Very complex templates may have named parameters:

{{template-name|param1=Value of first param|param2=Value of second param|...}}

The Multiverse Developer Wiki has the following kinds of templates:

• Style templates - Display specially-styled text such as notes or comments
• Navigation templates - Display a navigation box to group articles
• Specialized templates - Display specific text

There is a special page that lists all the defined templates: Show All Templates.

Style templates

Questions and comments for reviewers

When you are writing, you often encounter places where you know you need more information, or are not sure of something. You should mark these places with specific questions for tech. reviewers. Use the following special style:

{{ReviewNote|Need more information.}}

This will be displayed like this:

Need more information.

Of course, substitute the text of your question or comment.

Drafts

For a work in progress, use this tag to mark it as a draft:

{{Draft}}

This will be displayed like this:

Preliminary Draft!

Important note

Use the mv-important class to create a colored box containing an important note.

{{Important|Use this style for important notes that the user should not overlook.}}

Which looks like this

Note

This style class is for a note. It is somewhat less strident than the "mvimportant" style:

{{Note|This is the note text.  This is the note text....}}

Navigation Templates

Tutorials:

• Template:Platform Tutorial Nav
• Template:Tutorial Nav

Client:

• Template:Clientui
• Template:Client
• Template:ClientScripting - May want to add a template for all the CSAPI classes(?)
• Template:ClientRenderingScripts - This is for material, particle, dompositor scripts and shaders

Server:

• Template:Server
• Template:ServerPlugins
• Template:MARS

Tools:

• Template:MVTools
• Template:3DAssets
• Template:AssetManagement

Generic Quick Navigation:

• Template:QuickNav - This template takes a variable number of parameters:
  • First parameter is title of nav box
  • Second, third, fourth, ... parameters on are links to articles in the group. These are optional.

Specialized templates

• Template:Nyi

NOTE: This feature is not yet implemented. It will be in a future release.

• Template:WIP

• Template:NavNote

• Template:ClientScripting Caveat

• Template:OgreCC

Deprecated API

Use Template:Deprecated API to mark deprecated methods, properties, or objects in the Client Scripting API. First argument is wiki name of object, method, or property; second is display name.

For example:

{{Deprecated API|<capi>Camera.Dispose</capi>}}

Yields: