Difference between revisions of "Instructions to Wiki Editors"

From ScummVM :: Wiki
Jump to navigation Jump to search
(Start writing instructions for wiki editors)
 
(→‎Extensions: Add GoogleDocs4MW in the list of extensions)
(15 intermediate revisions by 5 users not shown)
Line 1: Line 1:
These instructions are written mainly with the edition of the User Manual in mind. Some of the points might also be valid for other parts of the wiki though.
These instructions are written mainly with the editing of the User Manual in mind. Some of the points might also be valid for other parts of the wiki though.
 
= General Rules =


== No controversial material ==
== No controversial material ==
Line 5: Line 7:


== Spelling and grammar ==
== Spelling and grammar ==
# For consistency sake it is better to use the '''american spelling''' everywhere rather than mix english and american spellings. That means that you should prefer ''color'' and ''finalize'' over ''colour'' and ''finalise''.
# For consistency sake it is better to use the '''American English spelling''' everywhere rather than mix British and American English spellings. That means that you should prefer ''color'' and ''finalize'' over ''colour'' and ''finalise''.
# Please '''do not use contractions''' (e.g ''If you've navigated'' for ''If you have navigated''). They are usually used in spoken english but not much in written english, although there are some exceptions (e.g. ''It doesn't work'' is fine for non formal written english, as is the expended form ''It does not work''). If in doubt use the expended form. Also the User Manual is a bit more formal than for example an e-mail; and as such contractions that might be fine in an e-mail are not necessarily fine in the User Manual.
# Please '''do not use contractions''' (e.g. ''If you've navigated'' for ''If you have navigated''). They are usually used in spoken English but not much in written English, although there are some exceptions (e.g. ''It doesn't work'' is fine for non-formal written English, as is the expanded form ''It does not work''). If in doubt, use the expanded form. Also the User Manual is a bit more formal than for example an e-mail; and as such contractions that might be fine in an e-mail are not necessarily fine in the User Manual.
# '''Do not use very complex grammatical structure or abstruse words''' (''abstruse'' meaning ''difficult to comprehend'' and being an example of words to avoid). Keep in mind that many ScummVM users are not native english speaker and many may not speak english as well as you do.
# '''Do not use very complex grammatical structure or abstruse words''' (''abstruse'' meaning ''difficult to comprehend'' and being an example of words to avoid). Keep in mind that many ScummVM users are not native English speakers and may not speak English as well as you do.


== User Manual content ==
== User Manual content ==
# Try to place yourself in the head of a complete newbie and make very explicit some information that might not be obvious for everybody. For example, instead of ''Navigate to the correct directory'' you might want to write ''Navigate to the directory that contains the game files''.
# Try to place yourself in the head of a complete newbie and make very explicit some information that might not be obvious for everybody. For example, instead of ''Navigate to the correct directory'' you might want to write ''Navigate to the directory that contains the game files''.
# ScummVM is distributed on many platforms. When giving instructions on encoding audio or similar tasks try to cover at least Linux, Windows and MacOS X. Most of the users will have one of these operating system.
# ScummVM is distributed on many platforms. When giving instructions on encoding audio or similar tasks, try to cover at least Linux, Mac OS X and Windows. Most of the users will have one of these operating system.
 
== Translation ==
* To translate a page into a different language, create a new page by adding the ''/lang'' postfix, where lang is the language code for the translation. For example, the translation of [[User Manual/Introduction]] in German is in [[User Manual/Introduction/de]].
 
* At the top of the page, add the ''<nowiki>{{Languages}}</nowiki>'' template (see [[Template:Languages]]). If it is the first translation for that page, you will also need to add the template to the english page.
 
'''Note:''' There seems to be a small bug in the template for the moment with the detection of the page. If the bar does not have the correct list of languages, you can specify the page explicitly in the template:
<nowiki>{{Languages|User Manual/Introduction}}</nowiki>
The page name given to the template should always be the english page.
 
* If your translated page points to a page that is not yet translated, you might want to link to the not yet existing translated page, create that page and redirect to the english page. That way you will not have to change all the links when you decide to translate the page. For example, if you want to link to [[User Manual/ScummVM Interface]] from a German page, but [[User Manual/ScummVM Interface]] has not yet been translated to German, you might want to point to [[User Manual/ScummVM Interface/de]] anyway and create that page with the following content:
<nowiki>#REDIRECT [[User Manual/ScummVM Interface]]</nowiki>
 
== Trusted User Group ==
As a normal user there are things you cannot do on the wiki. For example you cannot delete and undelete pages or edit the wiki interfaces (e.g. modify the [[MediaWiki:Sidebar|Sidebar]]). A group of users with slightly more powers than normal user exists. Membership to this group is decided on a case by case basis by the project leaders. If you want to be added to the group then contact them (e.g. by e-mail or on IRC) and they might accede to your request.
 
= Extensions =
There are several wiki extensions installed to help you in the editing task.
 
== SyntaxHighlight ==
This extension can be used to present source code with syntax highlighting. As you can guess for us it is mainly useful for C++ code, but it can also be used with other languages.
 
'''Link:''' https://www.mediawiki.org/wiki/Extension:SyntaxHighlight
 
'''Syntax:'''
 
<pre>
<source lang="cpp">
#include <foo.h>
 
class MyClass {
public:
    MyClass();
    ~MyClass();
};
</source>
</pre>
 
Which gives the following result:
 
<source lang="cpp">
#include <foo.h>
 
class MyClass {
public:
    MyClass();
    ~MyClass();
};
</source>
 
The extension also now supports using the ''syntaxhighlight'' tag instead of ''source'', which can help if the code itself contains the source tag:
 
<pre>
<syntaxhighlight lang="xml">
    <header path="include/foo.h" />
    <source path="src/foo.cpp" />
</syntaxhighlight>
</pre>
 
== SimpleMathJax ==
This extension can be used to generate formulas using the LaTeX math syntax. It replaces MediaWiki's regular TeX based math support (that we cannot use due to server limitations) and the old jsMath and MathJax extensions. It uses the same syntax as all of these, which is [http://meta.wikimedia.org/wiki/Help:Formula described here].
 
For inline equation use <code>\(...\)</code> and  for display style math use instead  <code>&lt;math&gt;...&lt;/math&gt;</code>.
 
MathJax produces nice and scalable mathematics, see their website (http://www.mathjax.org/) for a demonstration.
 
'''Link:''' https://www.mediawiki.org/wiki/Extension:SimpleMathJax
 
'''Syntax:'''
 
<pre>
&lt;math>
Skewness(X) = \frac{N}{(N-1)*(N-2)*\sigma(X)^3} * \sum_{i=1}^{N}{(X_i - E(X))^3}
&lt;/math>
</pre>
 
Which gives the following result:
 
<math>
Skewness(X) = \frac{N}{(N-1)*(N-2)*\sigma(X)^3} * \sum_{i=1}^{N}{(X_i - E(X))^3}
</math>
 
== GoogleDocs4MW ==
 
This extension can be used to embed Google spreadsheet into a wiki page.
 
'''Link:''' https://www.mediawiki.org/wiki/Extension:GoogleDocs4MW
 
'''Syntax:'''
 
<pre>
<googlespreadsheet width="600" height="200" style="width: 50%">Google Docs' key goes here</googlespreadsheet>
</pre>
 
'''Note:''' To actually embed a spreadsheet, the spreadsheet needs to be published with Google's ''File > Publish to Web...'' option. It is not sufficient to just have a shareable link.
 
== Cite ==
This extension can be used to create footnotes on a wiki page.
 
'''Link:''' http://www.mediawiki.org/wiki/Extension:Cite/Cite.php
 
'''Syntax:'''
 
You need to use the &lt;ref> tag to define a reference:
 
<pre>
This is an example of use of the Cite extension<ref>Criezy, ScummVM wiki, 2009</ref>.
</pre>
 
And then to use the &lt;references /> tag as a placeholder (e.g. at the bottom of the page for a footnote):
 
<pre>
--- Notes ---
<references />
</pre>
 
This example gives:
 
This is an example of use of the Cite extension<ref>Criezy, ScummVM wiki, 2009</ref>.
 
--- Notes ---
<references />
 
== ParserFunctions and StringFunctions ==
This extension adds logical functions and functions that operate on strings to the wiki parser.
 
'''Link:''' http://www.mediawiki.org/wiki/Extension:ParserFunctions
 
'''Syntax:''' See http://www.mediawiki.org/wiki/Help:Extension:ParserFunctions and http://www.mediawiki.org/wiki/Extension:StringFunctions for a list of functions and their syntax.
 
== Dynamic Page List ==
This extension is quite complex. Basically it can be used to display content from other pages into a wiki page.
 
'''Link:''' http://semeb.com/dpldemo/index.php?title=Dynamic_Page_List
 
'''Syntax:''' This extension is invoked with the parser function {&zwj;{#dpl: .... }} or parser tag &lt;DPL>. See the link above for more details and examples.

Revision as of 08:31, 28 April 2017

These instructions are written mainly with the editing of the User Manual in mind. Some of the points might also be valid for other parts of the wiki though.

General Rules

No controversial material

The basic rule is to keep in mind that we do not want problems with right holders and therefore we do not want to have links to illegal content or to document steps that might be illegal. An obvious example is links to so-called abandonware sites. Another less obvious example is instructions on how to jailbreak an iPhone or a Wii so that we can install ScummVM. We should write the instructions starting from the assumption that the device is already jail-broken.

Spelling and grammar

  1. For consistency sake it is better to use the American English spelling everywhere rather than mix British and American English spellings. That means that you should prefer color and finalize over colour and finalise.
  2. Please do not use contractions (e.g. If you've navigated for If you have navigated). They are usually used in spoken English but not much in written English, although there are some exceptions (e.g. It doesn't work is fine for non-formal written English, as is the expanded form It does not work). If in doubt, use the expanded form. Also the User Manual is a bit more formal than for example an e-mail; and as such contractions that might be fine in an e-mail are not necessarily fine in the User Manual.
  3. Do not use very complex grammatical structure or abstruse words (abstruse meaning difficult to comprehend and being an example of words to avoid). Keep in mind that many ScummVM users are not native English speakers and may not speak English as well as you do.

User Manual content

  1. Try to place yourself in the head of a complete newbie and make very explicit some information that might not be obvious for everybody. For example, instead of Navigate to the correct directory you might want to write Navigate to the directory that contains the game files.
  2. ScummVM is distributed on many platforms. When giving instructions on encoding audio or similar tasks, try to cover at least Linux, Mac OS X and Windows. Most of the users will have one of these operating system.

Translation

  • At the top of the page, add the {{Languages}} template (see Template:Languages). If it is the first translation for that page, you will also need to add the template to the english page.

Note: There seems to be a small bug in the template for the moment with the detection of the page. If the bar does not have the correct list of languages, you can specify the page explicitly in the template:

{{Languages|User Manual/Introduction}}

The page name given to the template should always be the english page.

  • If your translated page points to a page that is not yet translated, you might want to link to the not yet existing translated page, create that page and redirect to the english page. That way you will not have to change all the links when you decide to translate the page. For example, if you want to link to User Manual/ScummVM Interface from a German page, but User Manual/ScummVM Interface has not yet been translated to German, you might want to point to User Manual/ScummVM Interface/de anyway and create that page with the following content:
#REDIRECT [[User Manual/ScummVM Interface]]

Trusted User Group

As a normal user there are things you cannot do on the wiki. For example you cannot delete and undelete pages or edit the wiki interfaces (e.g. modify the Sidebar). A group of users with slightly more powers than normal user exists. Membership to this group is decided on a case by case basis by the project leaders. If you want to be added to the group then contact them (e.g. by e-mail or on IRC) and they might accede to your request.

Extensions

There are several wiki extensions installed to help you in the editing task.

SyntaxHighlight

This extension can be used to present source code with syntax highlighting. As you can guess for us it is mainly useful for C++ code, but it can also be used with other languages.

Link: https://www.mediawiki.org/wiki/Extension:SyntaxHighlight

Syntax:

<source lang="cpp">
#include <foo.h>

class MyClass {
public:
    MyClass();
    ~MyClass();
};
</source>

Which gives the following result:

#include <foo.h>

class MyClass {
public:
    MyClass();
    ~MyClass();
};

The extension also now supports using the syntaxhighlight tag instead of source, which can help if the code itself contains the source tag:

<syntaxhighlight lang="xml">
    <header path="include/foo.h" />
    <source path="src/foo.cpp" />
</syntaxhighlight>

SimpleMathJax

This extension can be used to generate formulas using the LaTeX math syntax. It replaces MediaWiki's regular TeX based math support (that we cannot use due to server limitations) and the old jsMath and MathJax extensions. It uses the same syntax as all of these, which is described here.

For inline equation use \(...\) and for display style math use instead <math>...</math>.

MathJax produces nice and scalable mathematics, see their website (http://www.mathjax.org/) for a demonstration.

Link: https://www.mediawiki.org/wiki/Extension:SimpleMathJax

Syntax:

<math>
Skewness(X) = \frac{N}{(N-1)*(N-2)*\sigma(X)^3} * \sum_{i=1}^{N}{(X_i - E(X))^3}
</math>

Which gives the following result:

[math]\displaystyle{ Skewness(X) = \frac{N}{(N-1)*(N-2)*\sigma(X)^3} * \sum_{i=1}^{N}{(X_i - E(X))^3} }[/math]

GoogleDocs4MW

This extension can be used to embed Google spreadsheet into a wiki page.

Link: https://www.mediawiki.org/wiki/Extension:GoogleDocs4MW

Syntax:

<googlespreadsheet width="600" height="200" style="width: 50%">Google Docs' key goes here</googlespreadsheet>

Note: To actually embed a spreadsheet, the spreadsheet needs to be published with Google's File > Publish to Web... option. It is not sufficient to just have a shareable link.

Cite

This extension can be used to create footnotes on a wiki page.

Link: http://www.mediawiki.org/wiki/Extension:Cite/Cite.php

Syntax:

You need to use the <ref> tag to define a reference:

This is an example of use of the Cite extension<ref>Criezy, ScummVM wiki, 2009</ref>.

And then to use the <references /> tag as a placeholder (e.g. at the bottom of the page for a footnote):

--- Notes ---
<references />

This example gives:

This is an example of use of the Cite extension[1].

--- Notes ---

  1. Criezy, ScummVM wiki, 2009

ParserFunctions and StringFunctions

This extension adds logical functions and functions that operate on strings to the wiki parser.

Link: http://www.mediawiki.org/wiki/Extension:ParserFunctions

Syntax: See http://www.mediawiki.org/wiki/Help:Extension:ParserFunctions and http://www.mediawiki.org/wiki/Extension:StringFunctions for a list of functions and their syntax.

Dynamic Page List

This extension is quite complex. Basically it can be used to display content from other pages into a wiki page.

Link: http://semeb.com/dpldemo/index.php?title=Dynamic_Page_List

Syntax: This extension is invoked with the parser function {‍{#dpl: .... }} or parser tag <DPL>. See the link above for more details and examples.