Note: You are currently viewing documentation for Moodle 2.4. Up-to-date documentation for the latest stable version of Moodle may be available here: Style guide.

MoodleDocs:Style guide: Difference between revisions

From MoodleDocs
m (→‎PHP syntax highlighting: line numbering feature)
(DE-Link)
 
(10 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Help}}
{{Help}}
== Categories ==
== Categories ==
A Category is an index of documentation pages.
A category is an index of documentation pages.


*A page can be added to a category by typing <code><nowiki>[[Category:Category name]]</nowiki></code>, for example <code><nowiki>[[Category:Teacher]]</nowiki></code>, at the bottom of the page. You can add several complete category tags to include a page in different categories, but you can't put several categories in one tag. Example:
* A page can be added to a category by typing <code><nowiki>[[Category:Category name]]</nowiki></code>, for example <code><nowiki>[[Category:Site administration]]</nowiki></code>, at the bottom of the page. Many templates automatically categorise pages using the template, for example <code><nowiki>[[Template:Forum]]</nowiki></code> categorises pages into [[:Category:Forum]].
<code><nowiki>[[Category:Teacher]]</nowiki></code>
* For '''linking to a category''' you have to add another colon like so: <code><nowiki>[[:Category:FAQ]]</nowiki></code> which will show as [[:Category:FAQ]].
<code><nowiki>[[Category:Student]]</nowiki></code>
* [[Special:Categories|Categories]] lists all Moodle Docs categories. This can be found in the Toolbox Special pages link.
*To ensure that pages in the Development namespace are listed in alphabetical order on a category page, the page name should be include in the category link i.e. <code><nowiki>[[Category:Developer|New page name]]</nowiki></code>.
* For '''further information''' about categories and how they work in MediaWiki, please refer to the [[Wikipedia:Wikipedia:Categorization|Wikipedia:Categorization]].
*[[Special:Categories|Categories]] lists all Moodle Docs categories. This can be found in the Toolbox Special pages link.
*To improve the browsing of Moodle Docs by category, please categorize category pages too. This will result in subcategories being created. For example, [[:Category:Capabilities]] is categorized as "Administrator" and "Roles", and appears as a subcategory in [[:Category:Administrator]] and [[:Category:Roles]]. 
*It is not necessary to categorize pages in a subcategory with the same category as the category page. For example, none of the pages in [[:Category:Capabilities]] need to be categorized as "Administrator" or "Roles".
*For further information about categories and how they work in MediaWiki, please refer to the [[Wikipedia:Wikipedia:Categorization|Wikipedia:Categorization]].
 
* For linking to a category you have to add another colon like so: <code><nowiki>[[:Category:FAQ]]</nowiki></code> which will show as [[:Category:FAQ]].


== Screenshots ==
== Screenshots ==
Line 20: Line 14:
* Screenshots can be uploaded using the toolbox [[Special:Upload|Upload file]] link.
* Screenshots can be uploaded using the toolbox [[Special:Upload|Upload file]] link.
* Please name screenshots descriptively to avoid confusion.
* Please name screenshots descriptively to avoid confusion.
* To include the screenshot in an article, use a link in the form <code><nowiki>[[Image:Screenshot.png|thumb|alt text]]</nowiki></code>.
* To include the screenshot in an article, use a link in the form <code><nowiki>[[
File:Screenshot.png|thumb|alt text]]</nowiki></code>.
* Please do not apply effects such as borders, watermarks or drop shadows to screenshots. This will allow others to add or replace screenshots over time and still maintain a consistent look and feel to articles.
* Please do not apply effects such as borders, watermarks or drop shadows to screenshots. This will allow others to add or replace screenshots over time and still maintain a consistent look and feel to articles.
* For help on image placement and adding an image caption, please refer to the [[Wikipedia:Wikipedia:Picture_tutorial|Wikipedia Picture tutorial]].
* For help on image placement and adding an image caption, please refer to the [[Wikipedia:Wikipedia:Picture_tutorial|Wikipedia Picture tutorial]].
Line 30: Line 25:
==Templates==
==Templates==
* In MediaWiki, a template is a page which can be inserted into another page. For example, the Moodle Docs help block on this page is a template.
* In MediaWiki, a template is a page which can be inserted into another page. For example, the Moodle Docs help block on this page is a template.
* A template may be added to a page by typing <code><nowiki>{{Name}}</nowiki></code> for Template:''Name''.
* A template may be added to a page by typing <code><nowiki>{{Name}}</nowiki></code> for Template:''Name'' (template names are case sensitive).
* [https://docs.moodle.org/en/index.php?title=Special%3AAllpages&from=&namespace=10 All pages (Template namespace)] lists all Moodle Docs templates.
* [https://docs.moodle.org/en/index.php?title=Special%3AAllpages&from=&namespace=10 All pages (Template namespace)] lists all Moodle Docs templates.
* Please refer to the [http://meta.wikimedia.org/wiki/Help:Template MediaWiki Template help] for further information.
* Please refer to the [http://meta.wikimedia.org/wiki/Help:Template MediaWiki Template help] for further information.
Line 36: Line 31:
==Moodle Docs editing tags==
==Moodle Docs editing tags==
*[[MoodleDocs:Deletion|Deletion]] - If you find any page requiring deletion, type <code><nowiki>{{Deletion}}</nowiki></code> at the top of the page.  Use the page comments if necessary to state the reason for deletion.
*[[MoodleDocs:Deletion|Deletion]] - If you find any page requiring deletion, type <code><nowiki>{{Deletion}}</nowiki></code> at the top of the page.  Use the page comments if necessary to state the reason for deletion.
*[[MoodleDocs:Update|Update]] - Features increase with each Moodle version. If you find a page requiring updating, type <code><nowiki>[[Template:Update]]</nowiki></code> at the top of the page.
*[[MoodleDocs:Update|Update]] - Features increase with each Moodle version. If you find a page requiring updating, type <code><nowiki>{{Update}}</nowiki></code> at the top of the page.
*[[:MoodleDocs:Stub|Stub]] - Developers and Moodle Docs administrators may add a new page with a <nowiki>{{Stub}}</nowiki> tag at the top, requesting help in adding content.
*[[:MoodleDocs:Stub|Stub]] - Developers and Moodle Docs administrators may add a new page with a <code><nowiki>{{Stub}}</nowiki></code> tag at the top, requesting help in adding content.
*You can also use the [[Help:Editing#Edit_summary|edit summary]] to communicate the need for more editing. For example in the page history you might see: "Added section, needs more work, see page comments".
*You can also use the [[Help:Editing#Edit_summary|edit summary]] to communicate the need for more editing. For example in the page history you might see: "Added section, needs more work, see page comments".


Line 45: Line 40:
<pre><nowiki><code php>... Some PHP code here...</code></nowiki></pre>
<pre><nowiki><code php>... Some PHP code here...</code></nowiki></pre>


* For long code examples you can even add line numbering like so:  
That will be rendered as:
 
<code php>
<?php
require_once(dirname(__FILE__) . '/../../config.php');
 
$cmid = required_param('cmid', 0, PARAM_INT);
if (!$cm = get_coursemodule_from_id('quiz', $id)) {
    print_error('invalidcoursemodule');
}
...
</code>
 
* For long code examples you can even add '''line numbering''' like so:  
<pre><nowiki><code php n>... A lot of PHP code here...</code></nowiki></pre>
<pre><nowiki><code php n>... A lot of PHP code here...</code></nowiki></pre>
That will be rendered as:
<code php n>
<?php
require_once(dirname(__FILE__) . '/../../config.php');
$cmid = required_param('cmid', 0, PARAM_INT);
if (!$cm = get_coursemodule_from_id('quiz', $id)) {
    print_error('invalidcoursemodule');
}
...
</code>
But beware, line numbering makes copying & pasting of code examples more cumbersome!


[[Category:MoodleDocs|Style guide]]
[[Category:MoodleDocs|Style guide]]
[[de:MoodleDocs:StyleGuide]]
[[de:Moodle Docs StyleGuide]]
[[es:MoodleDocs:Guía de Estilo]]
[[es:MoodleDocs:Guía de Estilo]]
[[fr:MoodleDocs:Guide de style]]
[[fr:MoodleDocs:Guide de style]]
[[ja:MoodleDocs:スタイルガイド]]
[[ja:MoodleDocs:スタイルガイド]]
[[zh:MoodleDocs:风格指引]]
[[zh:MoodleDocs:风格指引]]

Latest revision as of 14:19, 15 April 2012


Categories

A category is an index of documentation pages.

  • A page can be added to a category by typing [[Category:Category name]], for example [[Category:Site administration]], at the bottom of the page. Many templates automatically categorise pages using the template, for example [[Template:Forum]] categorises pages into Category:Forum.
  • For linking to a category you have to add another colon like so: [[:Category:FAQ]] which will show as Category:FAQ.
  • Categories lists all Moodle Docs categories. This can be found in the Toolbox Special pages link.
  • For further information about categories and how they work in MediaWiki, please refer to the Wikipedia:Categorization.

Screenshots

  • You are encouraged to illustrate documentation with screenshots. Please use the official Moodle demo site, or any other site or course using one of the standard themes, and ensure that the screenshot is as small as possible.
  • Screenshots should be GIF, JPEG or PNG format, with 72ppi resolution, and maximum width 800px.
  • To fit more into a screenshot, select a smaller text size for the web page via the View > Text size menu in your web browser.
  • Screenshots can be uploaded using the toolbox Upload file link.
  • Please name screenshots descriptively to avoid confusion.
  • To include the screenshot in an article, use a link in the form [[ File:Screenshot.png|thumb|alt text]].
  • Please do not apply effects such as borders, watermarks or drop shadows to screenshots. This will allow others to add or replace screenshots over time and still maintain a consistent look and feel to articles.
  • For help on image placement and adding an image caption, please refer to the Wikipedia Picture tutorial.

Screencasts

  • You might also consider using screencasts, the dynamic cousins to static screenshots.
  • For more information see Screencasts.

Templates

  • In MediaWiki, a template is a page which can be inserted into another page. For example, the Moodle Docs help block on this page is a template.
  • A template may be added to a page by typing {{Name}} for Template:Name (template names are case sensitive).
  • All pages (Template namespace) lists all Moodle Docs templates.
  • Please refer to the MediaWiki Template help for further information.

Moodle Docs editing tags

  • Deletion - If you find any page requiring deletion, type {{Deletion}} at the top of the page. Use the page comments if necessary to state the reason for deletion.
  • Update - Features increase with each Moodle version. If you find a page requiring updating, type {{Update}} at the top of the page.
  • Stub - Developers and Moodle Docs administrators may add a new page with a {{Stub}} tag at the top, requesting help in adding content.
  • You can also use the edit summary to communicate the need for more editing. For example in the page history you might see: "Added section, needs more work, see page comments".

PHP syntax highlighting

  • To highlight PHP syntax, enclose the code in tags:
<code php>... Some PHP code here...</code>

That will be rendered as:

<?php require_once(dirname(__FILE__) . '/../../config.php');

$cmid = required_param('cmid', 0, PARAM_INT); if (!$cm = get_coursemodule_from_id('quiz', $id)) {

   print_error('invalidcoursemodule');

} ...

  • For long code examples you can even add line numbering like so:
<code php n>... A lot of PHP code here...</code>

That will be rendered as:

<?php require_once(dirname(__FILE__) . '/../../config.php');

$cmid = required_param('cmid', 0, PARAM_INT); if (!$cm = get_coursemodule_from_id('quiz', $id)) {

   print_error('invalidcoursemodule');

} ...

But beware, line numbering makes copying & pasting of code examples more cumbersome!