View source for WikiPages


{{TOCright}}

This page is an extension of the [[Help:Editing|Help:Editing]] page and gives common guidelines for writing and updating the LabRPS wiki documentation. It summarizes several discussions and brainstorming sessions

== Before starting == 

* This wiki documentation is based on [https://www.mediawiki.org/wiki/MediaWiki MediaWiki], the same software that powers [https://en.wikipedia.org/wiki/Main_Page Wikipedia]. If you have contributed to Wikipedia, editing LabRPS wiki pages should be easy.
* Contrary to Wikipedia, the LabRPS wiki is write-protected to avoid spam. You must request an account [http://forum.labrpsweb.org/viewtopic.php?f=21&t=6830 on the forum].
* If you have never used wiki software before, please read [[Help:Editing]] to become familiar with the markup that is used.
* For advanced use of the wiki software, see [https://www.mediawiki.org/wiki/Help:Contents MediaWiki Help:Contents]. Not all features of MediaWiki are available in this LabRPS wiki, but many are.
* We like to keep the documentation easy to read, so avoid using complex features. Keep it simple.

== General guidelines == 

=== Concise descriptions === 

When describing LabRPS try to be concise and to the point and avoid repetition. Describe what LabRPS ''does'', not what LabRPS ''does not do''. Also avoid colloquial expressions such as 'a couple'. Use 'some' when dealing with an indeterminate number, or specify the correct quantity.

; Bad description
: [[WindLab_Plugin|WindLab Plugin]]: the WindLab Plugin is a plugin for wind velocity that aims to provide tools for the simulation of wind velocity.

; Good description
: [[WindLab_Plugin|WindLab Plugin]]: aims to provide tools for the numerical simulation of random wind velocity.

=== Centralized information === 

Avoid duplicating the same information in different places. Insert the information in a new page, and link to this page from other pages that require this information.

=== Styling === 

Templates are used to style the help pages. They give the documentation a consistent look and feel. There is a template for menu commands, {{MenuCommand|File → Save}}, a template to style keys to be pressed, {{KEY|Shift}}, to show a Boolean value, {{TRUE}}, etc. Please get familiar with the [[#Templates|#Templates]] section before writing help pages.

=== Temporary flags === 

If you are working on a large page it is advisable to mark the page either as a work in progress or as unfinished. This assures that wiki admins don't mark your page as ready for translation while you are still changing it.

To flag a page add either <code><nowiki>{{Page in progress}}</nowiki></code> or <code><nowiki>{{UnfinishedDocu}}</nowiki></code> as the first line. With <code><nowiki>{{UnfinishedDocu}}</nowiki></code> you invite others to join you in finishing the page, while <code><nowiki>{{Page in progress}}</nowiki></code> indicates that you will do the work yourself and others should give you some time.

Once the work is done, please don't forget to remove the flags!

== Examples == 

<div class="mw-collapsible mw-collapsed toccolours">

== Structure == 

<div class="mw-collapsible-content">

The [[User_hub|User hub]] provides a [[Online_Help_Toc|Table of Contents]]. This is used as the main reference for automatically building the offline help you can reach from LabRPS, as well as the offline PDF documentation.

The [[Template:Docnav]] is used to sequentially link pages, following the structure of the [[Online_Help_Toc|Table of Contents]]. See [[#Templates|#Templates]] for a list of all templates.

=== Page names === 

Page names should be short and they should use title case: every word should begin with a capital letter, unless they are articles, prepositions, conjunctions, or other grammatical particles (f.e. 'of', 'on', 'in', 'a', 'an', 'and').


; Bad page name:
: Simulation of sea surface

; Good page name:
: Simulation of Sea Surface

The names of top level plugin pages must have this format: <code>XYZ Plugin</code>, where <code>XYZ</code> is the name of the plugin, for example [[windLab_Plugin|windLab Plugin]]. And the names of pages describing the commands (or tools) belonging to a plugin must have this format: <code>XYZ Command</code>, for example [[windLab_Spectrum|windLab Spectrum]]. Note that you should use the command name as it occurs in the source code.

=== Headings === 

Paragraph headings should be short and use sentence case: all words except the first one and proper names, should be in lowercase. You should not use <code><nowiki>H1</nowiki></code> headings (<code><nowiki>=&nbsp;Heading&nbsp;=</nowiki></code>) in your wiki markup since the page title is automatically added as the main <code><nowiki>H1</nowiki></code> heading.

=== Links === 

You should use the original link name for links whenever possible. This clarifies the referenced page in printed or offline documentation. Please avoid non-meaningful words for the link.

; Bad link
: For more information on the implementation of the kaimal Spectrum click [[windLab_Plugin|here]].

; Good link
: For more information on implementation of the kaimal Spectrum refer to the [[windLab_Plugin|windLab Plugin]].

The preferred format for a link is:

<code><nowiki>[[Name_of_Page|Name of Page]]</nowiki></code>

Note that for the part before the <code><nowiki>|</nowiki></code> character, the actual link, case is relevant. If your page name is <code><nowiki>Name_of_page</nowiki></code> the link will fail if you type <code><nowiki>Name_of_Page</nowiki></code> (upper case P). Before the <code><nowiki>|</nowiki></code> character all spaces should be replaced by underscores (<code><nowiki>_</nowiki></code>). This is to assist translators using translation software, without the underscores the link would be translated by the software which is undesirable.

To link to a certain paragraph add a <code><nowiki>#</nowiki></code> sign and its headings to the page name. Example:

<code><nowiki>[[WikiPages#Links|WikiPages]]</nowiki></code>

Within the same page you can omit the page name. Example:

<code><nowiki>[[#Links|Links]]</nowiki></code>

To link to the top of the page you can use:

<code><nowiki>&lt;/translate&gt;{{Top}}&lt;translate&gt;</nowiki></code>

This template should automatically display the correct text depending on the language of the page. A link to the top of the page is especially useful for long pages as it allows the user to quickly jump back to the table of content. You can put it at the end of each paragraph. Make sure there is an empty line before and after the template.

; Image link
: [[Image:windLab_Spectrum.svg|24px|Optional text that is shown when you hover the image|link=windLab_Spectrum]]

To use an image as a link:

<code><nowiki>[[Image:windLab_Spectrum.svg|24px|Optional text that is shown when you hover the image|link=windLab_Spectrum]]</nowiki></code>

; Image link + text link
: [[Image:windLab_Spectrum.svg|24px|link=windLab_Spectrum]] [[windLab_Spectrum|windLab Spectrum]]

If you leave out the optional text the link itself will be shown when the image is hovered, which is preferable, and you should also add a text link after the image link:

<code><nowiki>[[Image:Draft_Wire.svg|24px|link=Draft_Wire]] [[Draft_Wire|Draft Wire]]</nowiki></code>

=== Plugin pages === 

A top level plugin page should start with:
* A description of what the plugin is used for.
* An image to illustrate the description.

See [[#Screen_capture|#Screen capture]] for conventions on including images.

=== Tutorials === 

A well written tutorial should teach how to achieve certain practical results quickly. It shouldn't be too long, but should include sufficient step-by-step instructions and images to guide the user. As LabRPS evolves, tutorials may become obsolete, so it is important to mention the LabRPS version used in, or required for, a tutorial.

For examples visit the [[Tutorials|Tutorials]] page.

</div> <!-- End of collapsible element for Structure section. Do not remove! -->
</div> <!-- End of collapsible element for Structure section. Do not remove! -->

<div class="mw-collapsible mw-collapsed toccolours">

== Templates == 

<div class="mw-collapsible-content">

Styling of the LabRPS wiki pages is achieved through the use of templates ([[Help:Editing#Templates_and_transcluding_pages]]). They ensure a standardized look and feel across all pages, and also make it possible to re-style the wiki. You can see the complete list of defined templates by accessing [[Special:PrefixIndex/Template:]]. But please only use the templates listed in the tables below. Only in very special cases should you use HTML tags directly.

Click on the template link to see the usage instructions for a template, and to see its implementation. Templates are a powerful feature of the MediaWiki software. You should be an experienced wiki user if you wish to propose additions and modifications to existing templates. If implemented incorrectly, templates make it difficult to translate pages into other languages, so their use should be limited to text formatting, page transclusion should be avoided. See [https://www.mediawiki.org/wiki/Help:Templates MediaWiki Help:Templates] to learn more.

=== Simple templates === 

These templates accept a simple text parameter, and format it with a particular style.
	
{|{{Prettytable}}
!style="width:10%;"|Template
!style="width:20%;"|Appearance
!style="width:70%;"|Description

|--
|[[Template:Top|Top]]
|

{{Top}}

|Use it to add a link to the top of the page.

|--
|[[Template:Emphasis|Emphasis]]
|{{Emphasis|emphasis}}
|Use it to emphasize a piece of text.

|--
|[[Template:KEY|KEY]]
|{{KEY|Alt}}
|Use it to indicate a keyboard key that needs to be pressed.

|--
|[[Template:ASCII|ASCII]]
|{{ASCII|A}}
|Use it to indicate a ascii key in a image (.svg) that needs to be pressed. You must give the character desired or the number of the code ascii of the character.

|--
|[[Template:Button|Button]]
|{{Button|Cancel}}
|Use it to indicate a button in the graphical user interface that needs to be pressed.

|--
|[[Template:RadioButton|RadioButton]]
|{{RadioButton|Option}}
|Use it to indicate a radio button in the graphical user interface that needs to be {{RadioButton|TRUE|Selected}} or {{RadioButton|FALSE|Not}}.

|--
|[[Template:CheckBox|CheckBox]]
|{{CheckBox|Option}}
|Use it to indicate a checkbox in the graphical user interface that needs to be {{CheckBox|TRUE|Checked}} or {{CheckBox|FALSE|Not}}.

|--
|[[Template:SpinBox|SpinBox]]
|{{SpinBox|1.50}}
|Use it to indicate a spinbox in the graphical user interface that needs to be modified.

|--
|[[Template:ComboBox|ComboBox]]
|{{ComboBox|Menu 1}}
|Use it to indicate a combobox in the graphical user interface that needs to be modified.

|--
|[[Template:FALSE|FALSE]], [[Template:false|false]]
|{{FALSE}}, {{false}}
|Use it to indicate a False Boolean value, for example, as a property in the [[Property_editor|property editor]]. This is a shortcut. Since it is a value, prefer Template [[Template:Value|Value]] {{Value|false}}

|--
|[[Template:TRUE|TRUE]], [[Template:true|true]]
|{{TRUE}}, {{true}}
|Use it to indicate a True Boolean value, for example, as a property in the [[Property_editor|property editor]]. This is a shortcut. Since it is a value, prefer Template [[Template:Value|Value]] {{Value|true}}

|--
|[[Template:MenuCommand|MenuCommand]]
|{{MenuCommand|File → Save}}
|Use it to indicate the location of a command inside a particular menu.

|--
|[[Template:FileName|FileName]]
|{{FileName|File name}}
|Use it to indicate a name of a file or directory.

|--
|[[Template:SystemInput|SystemInput]]
|{{SystemInput|Type this text}}
|Use it to indicate user typed input text.

|--
|[[Template:SystemOutput|SystemOutput]]
|{{SystemOutput|Output text}}
|Use it to indicate text output from the system.

|--
|[[Template:Incode|Incode]]
|{{incode|#include "RPS.h"}}
|Use it to include in-line source code with a monospace font. It should fit in one line.

|--
|[[Template:PropertyView|PropertyView]]
|{{PropertyView|Color}}
|Use it to indicate a View property in the [[Property_editor|property editor]]. Examples of View properties include {{emphasis|Line Color}}, {{emphasis|Line Width}}, {{emphasis|Point Color}}, {{emphasis|Point Size}}, etc.

|--
|[[Template:PropertyData|PropertyData]]
|{{PropertyData|Position}}
|Use it to indicate a Data property in the [[Property_editor|property editor]]. Data properties are different for different types of objects.

|--
|[[Template:Properties Title|Properties Title]] / [[Template:TitleProperty|TitleProperty]]
|{{Properties_Title|Base}}
|Use it to indicate the title of a property group in the [[Property_editor|property editor]]. The title will not be included in the automatic table of contents.

|--
|[[Template:Obsolete|Obsolete]]
|{{Obsolete|0.004}}
|Use it to indicate that a feature became obsolete in the specified LabRPS version.

|--
|[[Template:Version|Version]]
|{{Version|0.003}}
|Use it to indicate that a feature was introduces in the specified LabRPS version.

|--
|[[Template:VersionMinus|VersionMinus]]
|{{VersionMinus|0.001}}
|Use it to indicate that a feature is available in the specified LabRPS version and earlier versions.

|--
|[[Template:VersionPlus|VersionPlus]]
|{{VersionPlus|0.002}}
|Use it to indicate that a feature is available in the specified LabRPS version and later versions.

|--
|[[Template:ColoredText|ColoredText]]
|{{ColoredText|Colored Text}}
|Use this template to color the background, text, or background and text. ([[Template:ColoredText|ColoredText]] page for more examples)

|--
|[[Template:ColoredParagraph|ColoredParagraph]]
|{{ColoredParagraph|Colored Paragraph}}
|Use this template to color the background, text, or background and text of an entire paragraph. [[Template:ColoredParagraph|ColoredParagraph]] page for more examples)
|}

=== Complex templates === 

These templates require more input parameters, or produce a block of text with a particular format.

{|{{Prettytable}}
!style="width:10%;"|Template
!style="width:45%;"|Appearance
!style="width:45%;"|Description

|--
|[[Template:Prettytable|Prettytable]]
|This table
|Use it to format tables such as this one. Additional table properties can be added.

|--
|[[Template:Caption|Caption]]
|<div style="width:400px;">{{Caption|Some caption for an image}}</div>
|Use it to add an explanation below an image. It can be left aligned or center aligned.

|--
|[[Template:Clear|Clear]]
|
|Use it to clear columns. Follow the definition of the template for a detailed explanation. It is often used to stop text from flowing next to unrelated images.

|--
|[[Template:Code|Code]]
|{{Code|lang=cpp|code=#include "RPS.h"}}
|Use it to include multi-line code examples with a monospace font. The default language is Python, but other languages can be specified.

[[Python|Python]] code should adhere to the general recommendations established by [https://www.python.org/dev/peps/pep-0008/ PEP8: Style Guide for Python Code]. In particular, parentheses should immediately follow the function name, and a space should follow a comma. This makes the code more readable

|--
|[[Template:Fake heading|Fake heading]]
|{{Fake heading|Heading|2}}
|Use it to create a heading that will not be automatically included in the table of contents.

|--
|[[Template:GuiCommand|GuiCommand]]
|See [[GuiCommand model|GuiCommand model]]
|Use it to create a box with useful information to document workbench commands (tools).

|--
|[[Template:TutorialInfo|TutorialInfo]]
|See for example [[Basic_modeling_tutorial|Basic modeling tutorial]]
|Use it to create a box with useful information to document [[Tutorials|tutorials]].

|--
|[[Template:Docnav|Docnav]]
|{{Docnav|Online Help Startpage|Feature list}}
|Use it to create a bar with the words 'next', 'previous', and 'index', and the appropriate links, which is useful for putting pages in a particular sequence.

|--
|[[Template:VeryImportantMessage|VeryImportantMessage]]
|{{VeryImportantMessage|Important Message}}
|Use it to create a highlighted box with a very important message. Use sparingly, only to indicate major problems in the functionality of the software, discontinuation of tools, and similar.

|--
|[[Template:Page in progress|Page in progress]]
|{{Page in progress|Page in progress}}
|Use this for pages that are still in progress or that are currently being reworked. Don't forget to remove this when the page is ready.

|--
|[[Template:UnfinishedDocu|UnfinishedDocu]]
|{{UnfinishedDocu}}
|Use it to create a highlighted box indicating an unfinished documentation page.

|--
|[[Template:Softredirect|Softredirect]]
|
|Use it instead of the normal redirect, when you are redirecting to a special page (such as Media: or Category:), in which cases the normal redirect is disabled.

|--
|[[Template:Quote|Quote]]
|{{Quote|text=Cry "Havoc" and let slip the dogs of war.|sign=William Shakespeare|source=''Julius Caesar'', act III, scene I}}
|Use it to create a box of text with a literal quote and reference.

|--
|[[Template:Userdocnavi|Userdocnavi]], [[Template:Powerdocnavi|Powerdocnavi]]
|
|Use them to create navigation boxes for the user documentation, the power user documentation, and the developer documentation. This allows quickly jumping between different sections of the documentation. They also place the corresponding page in the proper category.

|}

</div> <!-- end of collapsible div. Do not remove! -->
</div> <!-- end of collapsible div. Do not remove! -->

<div class="mw-collapsible mw-collapsed toccolours">

== Graphics == 

<div class="mw-collapsible-content">

Images and screenshots are necessary to produce a complete documentation of LabRPS. They are particularly useful to illustrate examples and tutorials. Images should be shown in their original size, so they present sufficient detail and are readable if they include text. [[bitmap|Bitmap]] images should not be resized.

Avoid animated pictures (GIF) in the general help pages. Animations and videos should be reserved for tutorials not intended to be used as offline PDF documentation.

Images can be uploaded through the [[Special:Upload|Special:Upload]] page.

=== Name === 

Give meaningful names to your images. If you have an image that showcases the characteristics of a particular function, you should use the name of that function with {{incode|_example}} at the end. For example for the command [[windLab_Simulate|windLab Simulate]] the image should be called {{incode|windLab_simulate_example.png}}.

=== Screen capture === 

Recommended sizes for screen captures are:
* Native 1024x768 (or width=1024 and height<=768), only for full screen images.
* Smaller sizes are possible when showing details.
* Avoid images with larger resolutions, as they won't be very portable to other kinds of displays or the printed PDF documentation.

You shouldn't depend on a custom configuration of your desktop or operating system when you create screenshots and you should use the visual defaults of the LabRPS interface whenever possible.

To create a screenshots you can use the options provided by your operating system.

</div> <!-- end of Graphics collapsible div. Do not remove! -->
</div> <!-- end of Graphics collapsible div. Do not remove! -->

== Create, rename and delete pages == 

=== Create pages === 

Before creating a new page you should first check if a similar page already exists. If that is the case it is usually better to edit that existing page instead. When in doubt please open a topic in the [https://labrps.com/boards/forum/5/wiki forum] first.

To create a new page do one of the following:
* Visit the URL with the desired page name, for example: <code><nowiki>https://wiki.labrps.com/My_new_page</nowiki></code>, and click on 'create this page'.
* Do a wiki search for the page name, and click on the red text in 'Create the page "My new page" on this wiki!'.

=== Rename pages === 

Since LabRPS is a project under permanent development, it is sometimes necessary to revise the content of the wiki. If the names of commands are changed in the source code, the wiki pages documenting them have to be renamed as well. This can only be done by wiki administrators. To inform them, open a topic in the [http://labrps.com/boards/forum/5/new-wiki wiki] and list the necessary renaming operation in this form:

<pre>
old name         new name
Old_page_name_1  New_page_name_1
Old_page_name_2  New_page_name_2
...
</pre>

=== Delete files and pages === 
In case you need to delete a file, go to its page (<code><nowiki>https://www.labrps.com/wiki/File:***.***</nowiki></code>) and edit it. No matter if the page is blank or not, add this as the first element: <code><nowiki>{{Delete}}</nowiki></code> and directly below it describe why the page should be deleted. Additionally, open a topic in the [https://labrps.com/boards/forum/5/wiki forum].

For pages the procedure is the same.

== Discussion == 
The [http://labrps.com/boards/forum/6/wiki-discussion subforum] in the [https://labrps.com/boards/forumgroup/3/labrps-wiki forum] provides a dedicated space for discussing wiki topics, the wiki appearance and anything else related to the wiki. Direct your questions and suggestions there.

== Terminology - naming policy == 

=== English === 
See [[Glossary|Glossary]].