From Mageia wiki
Revision as of 09:33, 12 October 2020 by Cmoifp (talk | contribs) (mageia's online repository)
Jump to: navigation, search


Drakconf multiflag.png
Other languages
Deutsch ; English ; ‎español ; français ; português (Brasil) ; Português (Portugal) ; Türkçe ;

Introduction

This page is written to help anyone wanting to write, modify or translate pages in the Mageia Wiki. They must join the Mageia docteam

Mageia uses this wiki to meet three main needs :

  1. Helping Mageia teams coordinate their actions (reports, schedules, rules, todo lists, ...). All such pages belong to the "Doc" category.
  2. Provide information about the releases to the Mageia end-users - mostly Errata and Release Notes for each release. These pages belong to the "Mageia n" category. i.e. Mageia 6 Errata.
  3. Provide extra documentation to the Mageia end-users. All such pages belong to the "Documentation" category.

So far the wiki is English only, nevertheless a multi-language extension is hopefully going to be ready soon (see the section not yet written below :) ).

Requirements

Generalities

To be able to write, modify or translate pages in the Mageia wiki, follow these simple rules:

  1. Ask for credentials here
  2. Join the Mageia docteam
  3. Subscribe to the mailing list doc-discuss@ml.mageia.org and say what you are intending to do. It is the easiest way to coordinate our actions, share ideas and get some help. You can also use the IRC channel: #mageia-doc on Freenode.
  4. Take care with your writing/spelling/syntax. Don't hesitate to ask for help or advice if needed.
  5. Try to have a nice layout. Screenshots must be readable but not too big (600px is often enough)
  6. Read and respect the Mageia Code of conduct

What the wiki is used for

  • Good quality collaborative documentation about the Mageia projects:
    • Exposing the Mageia project, it's spirit and goals, the included tools, teams and inner processes.
    • Offering some clear technical documentation about the installation/migration processes and setup for both small and wide computer infrastructures.
    • Documenting tools and programs that are delivered with, or that can be installed on Mageia.
    • Explaining the community structure; to enable help for contributors to join in and participate easily according to their interests, abilities and needs.
  • Useful information and tips within articles.
  • For both end-users and advanced users/administrators.
  • For desktop and server applications.
  • For the community.

What the wiki is not to be used for

  • Duplicating information from existing resources such as :
  • A place for hosting the pages of individual projects,
  • An F.A.Q, Question and Answer site or any kind of support platform (see official website or dedicated website for such tools),
  • Official online or offline documentation.

Features of a wiki page

Before logging in

This is how a wiki page will look prior to logging in:

Wiki-en-1.png

Keys:

  1. The wiki page itself,
  2. The discussion page, where writers can explain their work, share ideas and solve their problems
  3. Normal reading mode
  4. View the actual source 'markup language' used to create a particular page
  5. A chronological list of all edits to the wiki, and option to revert them
  6. You need to be logged in to the wiki in order to make any edits
  7. The wiki search-engine
  8. In this toolbox, "Special pages" is useful as it provides many statistics and "Categories" lists all existing categories (see below how to add categories to a page).

After logging in

Once you have entered your login and password, new tools become available:

Wiki-en-2.png

Keys:

  1. Configuration options. <login> ("cmoifp" in the screenshot) is your own user-page, a place where you can introduce yourself - or even as a place for testing your wiki work. "My talk" is the discussion page of your own page. "My preferences" allows you to customize the interface (i.e. preferred language). The remaining entries are self-explanatory.
  2. Drop-down list with two options, "Move" and "Watch"/"Unwatch"
  3. In the Toolbox, "Upload file" to upload files (generally pictures or screenshots) in the wiki. It is strongly recommended to read what this page says.

Main syntax

Generalities

Here are the basic commands to start a page and/or make some slight modifications. For more information, see the links below and Google is your friend. We remind you this wiki is powered by MediaWiki.

Titles

In our wiki the name of the page automatically appears as a title to the page (currently as "Wiki » Page Name"). However, if you want a (somewhat) different title, then limit the use of a 1st level Paragraph "=" to the page title only. In that case, use 2nd level "==" and below for your page content instead of 1st level "=" and below. It's up to you if you use white space between the tags and the content. The wiki will ignore the spaces when rendering the page.

What you write What you get
= Level one Title = Level one Title
== Level two Title == Level two Title
=== Level three Title === Level three Title
==== Level four Title ==== Level four Title
===== Level five Title ===== Level five Title
====== Level six Title ====== Level six Title

Text formatting

Note:
There is special formatting for commands, menus, packages, programs and files.
What you write What you get
' 'italic' ' italic
' ' 'bold' ' ' bold
' ' ' ' 'italic and bold' ' ' ' ' italic and bold
tags <s> and </s> to cross the text tags <s> and </s> to strikethrough the text
{{cmd|command name}} command name
{{menu|menu -> submenu}} menu -> submenu
{{file|file name}} file name
{{pkg|package name}} Template:Pkg
{{prog|program name}} program name
{{core}} core repositories
{{nonfree}} nonfree repositories
{{tainted}} tainted repositories
{{backports}} Template:Backports
<pre> text in presentation mode</pre>
 text in presentation mode

The lines
:can be
::indented
:::on several levels

The lines

can be
indented
on several levels
<span style="color: red;">some text in red</span> some text in red
<span style="color: blue;">some text in blue</span> some text in blue
<span style="color: green;">some text in green</span> some text in green
<span style="color: orange;">'''some text in bold and orange'''</span> some text in bold and orange
<span style="color:#FF00FF;">some text in any color</span> some text in any color
Insert the right tag <br> to have a line break Insert the right tag
to have a line break

Links and anchors

What you can do What you write What you get
Link to a Mageia wiki page (i.e.: the wiki welcome page).
(1) Without name
(2) With the name "Welcome"

[[Main_Page]]
[[Main_Page|Welcome]]

[1]
Welcome
Link to a URL (i.e.: the Mageia official doc.).
(1) Without name
(2) With the name "Documentation"

[http://www.mageia.org/fr/doc/]
[http://www.mageia.org/fr/doc/ Documentation]

[2]
Documentation
Add an anchor named "anchor1" to the word "text" some existing <span id="anchor1">text</span> in a page some existing text in a page
Create a link to "anchor1" click [[#anchor1|here]] to go to the anchor1 click here to go to the anchor1
Create a link to the anchor "Hardware" in the wiki page "Documentation" see [[Documentation#Hardware|here]] see here
Note:
Each title is an anchor by default. Its name is the title itself.

Lists

What you write What you get

* unordered list, first line
* unordered list, second line
** unordered list, third line
** unordered list, fourth line

  • unordered list, first line
  • unordered list, second line
    • unordered list, third line
    • unordered list, fourth line

# ordered list, first line
# ordered list, second line
## ordered list, third line
## ordered list, fourth line
##* both, fifth line
# back ordered list

  1. ordered list, first line
  2. ordered list, second line
    1. ordered list, third line
    2. ordered list, fourth line
      • both, fifth line
  3. back ordered list

Tables

There are many options in MediaWiki for drawing tables (see this page for more information). However, for a simple table, you can use this example below.

  • In the first line, replace the "1" after "border=" by the border thickness you want (in pixels), replace "center" by "left" or "right" (without the ") and replace "800" for your desired width.
  • In the second line, you can optionally include column titles, separated by "!!".
  • In the remainder, add or remove table cells (denoted as "|"). The "|-" is used to create an actual row.

What you write (you can use copy/paste to create such a table in your page):

{|border="1" class="wikitable" style="text-align:center; width:800px;"
! First column!! Second column!!Third column
|-
|column1 - cell1
|column2 - cell1
|column3 - cell1
|-
|column1 - cell2
|column2 - cell2
|column3 - cell2
|-
|column1 - cell3
|column2 - cell3
|column3 - cell3
|}

What you get:

First column Second column Third column
column1 - cell1 column2 - cell1 column3 - cell1
column1 - cell2 column2 - cell2 column3 - cell2
column1 - cell3 column2 - cell3 column3 - cell3

Images

Note:
About screen-shots, we recommend them being 800 pixels wide. Legend is highly desirable.
What you write What you get
[[image:wiki3.png]] Wiki3.png
[[image:wiki3.png|100px]] Wiki3.png
[[image:wiki3.png|center|100px]] Wiki3.png
[[image:wiki3.png|right|80px]] Wiki3.png
[[image:wiki3.png|center|100px|thumb|none|Legend here]]
(Without the "none" option, the text is floating around the image.)
Legend here

Templates

Among other uses, templates can be used to highlight something important. Templates allow you to do this in a quick and consistent way.

Note:
To write a note, write {{note|Text ...}}
Warning!
To write a warning, write {{warning|Text ...}}
Dragon-head.png Here be dragons!
To give a trick, write {{dragons|Text ...}}

Template:Information

To mark a page as a draft, write {{draft}} at the top of a page, and you will obtain this banner:

this page is a draft.
It requires improvements. If you want to improve it, simply log in and click on the Edit tab.

Please remove this {{Draft}}template, when you're sure the page is complete and correct.


View the other draft pages, or other pages to improve and maintain.


Template:Root console

Konsole.png
[user@computer ~]$ To show a command to be typed in a console as a normal user, write {{Console|command line}}


Categories

The special tag you'll use most is a Category tag:

Syntax: [[Category:category name]]

Example: [[Category:Documentation]]

The wiki is configured so that if you place that tag anywhere in your markup, a link to the Documentation Category index page appears automatically at the BOTTOM of your wiki page enclosed in a pretty box. Your page also automatically appears in the "Documentation" index page. No extra work on your part. We use "Doc" for internal Doc Team documents, "Documentation" for general public documents and there are also several sub-categories. It is best to always use "Doc" or "Documentation" and add other Categories as required.

Note:
Whilst it is possible to place the Category tags anywhere, it is best to place them at the very top - yes, the TOP of the document, with a bit of white space before you start writing the page. This is important as it avoids the tags being accidentally deleted when the page content is edited and makes it easier to find them when you have a long wiki page.

Use as many categories as needed that make sense. A list of available Categories can be found here.

Signing

There's actually no need to sign a page as it's all in the edit history, but sometimes you may wish to sign something off. It is for example very helpful in the discussion tab. It's also a convenient way to link to your own User: page (where you can test your pages before unleashing them on the wiki).

What you write What you get
~~~ lebarhon
~~~~ lebarhon 17:32, 23 June 2014 (UTC)
~~~~~ 17:32, 23 June 2014 (UTC)

Useful links

http://en.wikipedia.org/wiki/Help:Wiki_markup

http://www.mediawiki.org/wiki/Help:Tables/fr

http://www.mediawiki.org/wiki/Help:Images

http://en.wikipedia.org/wiki/Help:Table

http://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style


How to modify a page

Generalities

All you have to do is to click on the Edit link at the top of the page (making the whole page editable at once) or click the Edit to the right of each section title (to edit that section only). This link brings you to the edit page and shows you the wiki code of the current page.

At the top left of the page, there is a menu for basic formatting.
Wiki4.png
A help message pops up when the mouse hovers over an icon.

At the bottom of the page, there is a Summary section for you to comment about your changes. Please fill in this space, so that other contributors can more easily follow what has been done when in the page's history.

You can also specify two options:

  • This is a minor edit to let others know that the changes you have made are minor (basically, anything which does not fundamentally alter the meaning or appearance of a page).
  • Watch this page allows you to be informed by e-mail of modifications to the page (except minor modifications).

And finally 3 buttons:

  • Save page to save your work (keyboard shortcut : Alt-Shift-S)
  • Show preview to have an idea of how the page will look like before saving (Alt-Shift-P)
  • Show changes to see clearly the differences between the saved page and the one you are editing.

It is highly recommended to always preview your page BEFORE saving the modifications you just made, to avoid errors.

Do not hesitate to add some comments in the "Discussion" tab.

Cancelling a modification and return to a former state

This is called reverting.

How to create a page

1. Be sure that the page, or a similar page that could be expanded/completed, does not already exist
2. Inform the Mailing-list - maybe somebody has worked or plans to work on a such a page
3. Find a good title (see the subsection below). This is important, as renaming pages is not trivial.
4. Log in to the wiki
5. Write your title in the search area (key 7 see this screen-shot) and click on "Search", accept to create the page with a click on the title.
6. The new page is opened in edit mode. If you like, you can copy/paste this sample in the new page:


{{draft}}

[[Category:Documentation]]

== Introduction ==

7. Add other categories and/or remove "Documentation" if necessary
8. Always have a "presentation"/"Introduction" section to explain what the page deals with
9. See How to modify a page

Page and section naming

  • Try to put accurate keywords in the search-engines
  • Try not to make page titles any longer than necessary
  • Write the title with usual spaces between words, (let the wiki manage the " _ ")
  • Do not nest pages in sub-folders, e.g. Topic/FAQ
  • Use natural language naming (as opposed to nesting)
  • Use capital letters only for the initial word in a title or section title: "Like this"
    • Exceptions: proper nouns, and the titles/chapters of formal, full documentation guides that are converting to XHTML/XML
    • Examples: "Join the Foo Project"; "Setting up USB boot media"; "FAQ on SELinux"

How to translate a page

In the absence of a multilingual wiki

In this case, there is only the [en] namespace and it houses all the languages.

  • Warn the Mailing-list to say you are going to translate a wiki page
  • Create a new page with a title that is composed of the translated original title followed by -xy. xy being the language symbolic letters,
    • Example: The title for this very page translated in French should be "Comment écrire une page wiki-fr", in German "Erstellen einer Wiki Seite-de",
  • Add a link to each existing translated page to your new translated page and vice-versa. These different language names must be written in their own language. That means for example: English, Español, Français, Deutsch, ... For English, Spanish, French and German pages, a banner exists.
  • Make screen-shots as near as possible to the original ones. Add text if necessary,
  • Add the language category if already existing, if not ask the Mailing-list, and the other categories as well.

Once we have a multilingual wiki

To be written after such wiki update lebarhon 12:59, 8 June 2014 (UTC)

Wiki management

To be written by a wiki manager lebarhon 13:00, 8 June 2014 (UTC)

  • How to archive a page?
  • How to delete pictures?
  • How to rename a page?
  • About maintaining the wiki:
    • tips on how to see if a page was imported from somewhere else and how to check its original license
    • when to move or remove a page
    • what to do with all the "Draft" pages
    • etc.