From Mageia wiki
(Redirected from Wiki and Documentation)
Jump to: navigation, search


Wiki setup

Mageia.org wiki will hold Mageia project info and documentation and manage several languages:

See Wiki requirements.

New wiki guidelines

In progress.

Teams contacts for wiki

  • triage: Marja van Waes, Leuhmanu
  • i18n: obgr_seneca, akien
  • packagers: andre999, doktor 5000
  • QA: Claire Robinson (MrsB), stormi, damsweb
  • marcom: trishf42
  • artwork: TeaAge
  • sysadmin: boklm
  • documentation: Akien
  • web: rda

What the wiki is 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 helping for both small and wide computer infrastructures.
    • Documenting about tools and programs that are delivered or that can be installed on Mageia.
    • Explaining the community architecture; to enable help for contributors and to join in and participate easily according to their competences 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 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.

Migrating stuff from old to new

All current wiki pages are here: http://mageia.org/wiki/doku.php?do=index

Migrating means:

  • port given page contents into the new wiki OR discard the page (because it's obsolete, or a duplicate of a more appropriate place)
  • replace the old wiki page contents by a redirection/link to the new page (in the English wiki) so that existing links are not broken
  • notify/leave webmasters the task of updating incoming links to the new pages
  • in the end, set Redirect rules so we can totally remove the old wiki

Who can do what?

  • Create a page/category: anyone with a Mageia account
  • Edit a page/category: anyone, except maybe for specific pages (case by case), later
  • Redirect/rename a page: anyone
  • Delete a page: members of the documentation team
  • Create/Edit/Delete a template page (specific namespace): members of the documentation team
  • Other?

New wiki structure

Organizing all this

  • Use direct, simple names for pages, describing what the article is about; no path or namespace in it: this is needed for a start;
  • Use categories for articles when appropriate: Teams, Policies, HowTo, Drafts, "For Packagers", "For Translators"; categories will be shown next to the beginning of an article, not at the bottom of it;
  • Use landing pages with crafted contents to list/introduce articles
  • Examples:
    • "Packaging policy" article, belongs to "Policies", "For Packagers" category
    • "Web team" article, belongs to "Teams" category
  • In doubt, ask the doc team
  • Categories to use already:
    • Teams
    • Policies
    • Tutorials
    • Organization (meetings, governance)
    • Ideas
    • Releases (for "Mageia 1 Release Notes" and "Mageia 1 Errata")
    • Development
    • Packaging
    • Translation (or I18N?)
    • Web
    • Documentation (Public Documentation)
    • Doc (Doc Team Internal documentation)
    • MageiaCookbook (sub-Category of Documentation)
    • Archive

Main landing page

aka Home page. Roles:

  • directing people within the wiki, routing to the right place
  • not duplicating what is on www

Wiki structure

End users docs

  • Install
  • KDE desktop
  • GNOME desktop
  • mcc
  • ...

Mageia current version

  • release notes
  • tour
  • errata

Mageia Next version

  • Planning
  • Features

Mageia oldish

  • Archives of old versions

Mageia News

  • weekly news
  • ...

Mageia organization

  • information about Mageia governance
  • council
  • board
  • financial

Mageia infrastructure

  • Servers list
  • Ldap organisation
  • ...

Mageia Contributers corner

  • Packaging
  • howto contribute
  • Security
  • policies
  • ...
  • Triage
  • QA
  • Translation
  • communication
  • i18n: transifex howto, teams organization, website translations, ...
  • documentation
  • artwork
  • marcomm
  • web: madb, user map, main site, ...
  • sysadmin
  • ...

Formal rules

Page naming

  • Do not nest pages in sub-folders, e.g. Topic/FAQ (The only exception to this is in the User: namespace, see below)
  • 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
    • Example: "Join the Foo Project"; "Setting up USB boot media"; "FAQ on SELinux"; "Standing in the middle of the field#With my eyes wide open".

Namespaces

A MediaWiki namespace is a special word followed by a colon, that puts the content in a different naming area in the wiki.

  • User: namespace. The User: namespace is somewhere you can put drafts and other personal material that you do not want searched and indexed by engines like Google. For instance, the user jpublic can build any wiki materials as desired under User:Jpublic, using subpages. If you need to know what pages you've built under your personal User: namespace, use the Special:Prefixindex page.
  • Archive: namespace Move old content to this namespace. This gets it out of the regular search index but keeps it available for future needs. This can be used for historical pages, like the list of Mageia founders, but also for pages that are no longer needed (e.g. pages about EOL Mageia versions) or no longer correct pages that will not be fixed. Put pages in an archive category.

No other namespace for now.

Categories

  • Use as many categories as needed that make sense
  • The category pages are the aggregation pages. Point to them prominently as the way to find all of something on a topic/within a category.
    • "Useful end-user docs are found in the Category:Documentation."
  • New category names should follow the same natural language rules as individual pages but are usually plural:
    • Docs project meeting logs
    • 2011 events
  • Place the Category tags at the VERY TOP of the page. The Category Style will place the resulting links at the BOTTOM of the page automatically. This avoids the tags being accidentally deleted when the page content is edited.

Translating

Initial wiki contents and structure are done in English to help design a basic default structure.

There will be a basic structure needed for all locales to follow (and cross-locales discussions will be done to improve this structure), and each locale may grow additional contents if needed.

Ideally, we would like to have a 1-1 match from English contents to other locales. How to do it exactly has still to be discussed (in media wiki, it's usually done through a [[fr:Accueil]] tag in the source to link to an Accueil page in the French-speaking wiki).

As we did in MDV wiki, the rule to open a new locale wiki will be: open as soon as there is at least one coordinator in this native language, reporting to the wiki/doc team (list to create then); this could happen within the i18n team.

Status

In development.

We are going to use [[1]] (1.16 branch) with a specific install to have per-locale instances (see http://wiki.mandriva.com for instance).

Inputs:

  • requirements
  • mediawiki code and doc

Outputs:

Possible app layout

  • wiki.mageia.org/
    • public/
      • base/
        • wiki/ (original mediawiki code)
        • default/ (http://wiki.mageia.org/ DocumentRoot)
        • fr/ (http://wiki.mageia.org/fr/ DocumentRoot)
          • LocalSettings.php (overrides some config variables from base/wiki/ settings)
          • this folder should not hold anything more than that)
    • var/
      • fr/
        • uploads/
        • cache/
      • en/
        • uploads/
        • cache/

Code

No code available at this time.

Issues

On Mageia bugzilla:

Who is in charge?

  • rda
  • obgr_seneca
  • TMKCodes
  • ennael

current status

  • index.php redirecting to language wiki according to browser setting: finished
  • LocalSettingsChanges.php: finished
  • rpm could be created (using one src.rpm for normal mediawiki and mageia-multilingual mediawiki)

Installation process

current:

  • install vanilla mediawiki (as there is no mandriva package) to /path/you/want/source (called MEDIAWIKI_SOURCEDIR afterwards)
  • create symlinks from language to source (like de -> ./source)
  • create databases, must have a naming schema like "wiki_db_name_<language_code>" (see bash script)
  • run mediawiki interactive setup for each language and throw away the resulting LocalSettings.php file (here the mediawiki schema in the respective database is created, have to find some way to do this automagically in database creation script)
  • run mediawiki interactive setup for english last and edit the LocalSettings.php file (see diff below) and move it from MEDIAWIKI_SOURCEDIR/conf/ to MEDIAWIKI_SOURCEDIR/
  • copy the Languages.php, LocalSettingsChanges.php and index.php to the appropriate directoris
  • edit Languages.php and LocalSettingsChanges.php conforming to Mageia names

Scripts / Commands

  • Database creation
 #!/bin/bash
 echo "Mediawiki Postgres database setup"
 echo ""
 echo "Please give the name prefix of the wiki database"
 read DATABASE_PREFIX
 echo ""
 echo "Please give the language code for this wiki"
 read LANGUAGE_CODE
 echo ""
 echo "Please give the wiki database user for this wiki"
 read WIKI_DB_USER
 echo ""
 
 DATABASE_NAME=$DATABASE_PREFIX"_"$LANGUAGE_CODE
 
 createdb -U postgres -O $WIKI_DB_USER $DATABASE_NAME
 createlang -U postgres plpgsql $DATABASE_NAME
 psql -U postgres -d $DATABASE_NAME -c "grant select on pg_ts_config to $WIKI_DB_USER;"
 psql -U postgres -d $DATABASE_NAME -c "grant select on pg_ts_config_map to $WIKI_DB_USER;"
 psql -U postgres -d $DATABASE_NAME -c "grant select on pg_ts_dict to $WIKI_DB_USER;"
 psql -U postgres -d $DATABASE_NAME -c "grant select on pg_ts_parser to $WIKI_DB_USER;"
 
 echo ""
 echo "Your database "$DATABASE_NAME" has be created."
 
  • index.php
 <?php
 include 'source/Languages.php';
 $langcodes = array_keys($languages);
 
 $langstring = explode(";", $_SERVER["HTTP_ACCEPT_LANGUAGE"]);
 foreach($langcodes as $langcode) {
        if(preg_match("/".$langcode."/", $langstring[0])) {
                header("Location: ./".$langcode."/");
        }

 }
 ?>
 
  • Languages.php
 <?php
 # define language specific things in an associative array
 $languages = array();
 $languages["en"] = array("sitename" => "English Testwiki");
 $languages["de"] = array("sitename" => "Deutsches Testwiki");
 $languages["fr"] = array("sitename" => "Testwiki Francais");
 $languages["es"] = array("sitename" => "Testwiki Espanol");
 ?>
 
  • LocalSettingsChanges.php
 <?php
 # include the languages table
 include './Languages.php';
 
 # get the language from the calling url
 $callingurl = strtolower($_SERVER['REQUEST_URI']); //get the calling url
 $langcode_array = explode("/", $callingurl);
 $langcode = $langcode_array[1]; # let's see if the http:// is counted, too...
 
 if(in_array($langcode, array_keys($languages))) {
        $wgSitename = $languages[$langcode]["sitename"];
        $wgDBname = "testwiki_" .$langcode;
        #$wgDBprefix = $languages[$langcode]["dbprefix"];
        $wgLanguageCode = $langcode;
        $wgScriptPath = "/" .$langcode;
 } else {
        # set default entries
        $wgSitename = $languages["en"]["sitename"];
        $wgDBprefix = "testwiki_en";
        $wgLanguageCode = "en";
        $wgScriptPath = "/en";
 }
 
 $wgStylePath        = $wgScriptPath."/skins";
 $wgLogo             = $wgStylePath."/common/images/wiki.png";
 $wgLocalInterwiki   = strtolower( $wgSitename );
 
 ?>
 
  • LocalSettings.php diff
  $wgDiff3 = "/usr/bin/diff3";
  
 +#LanguageSpecifics
 +include 'LocalSettingsChanges.php';
 +
  # When you make changes to this configuration file, this will make
  # sure that cached pages are cleared.
  $wgCacheEpoch = max( $wgCacheEpoch, gmdate( 'YmdHis', @filemtime( __FILE__ ) ) );
 

Conversion : dokuwiki -> mediawiki

See [Formating Help]

function dokuwiki (old) mediawiki (new)
bold **txt** '''txt'''
italic //txt// ''txt''
bold+italic **//txt//** or //**txt**// '''''txt'''''
underline __txt__ <u>txt</u>
strikeout <del>txt</del>
(not in tables)
<s>txt</s>
monospace ''txt'' <tt>txt</tt>
literal <code>txt</code>
(not in tables)
same (except allowed everywhere)

sometimes it's better to use <pre></pre>

force new line \\{space} or \\{end-of-line} <br>

Table conversion

table function dokuwiki (old) mediawiki (new)
more info at http://www.mediawiki.org/wiki/Help:Tables
wiki codes with <...> do not work in tables work in tables
table formats must start in column 1 may be preceded by spaces
begin table first line with table format {|
end table line just before first line
without table format
|}
default table format 1-pixel lines around cells no lines around cells
start of row cell in column 1 |- (optional for first row)
heading cell ^ + content
+ another cell or ^ or |
! + content (1st cell in physical line)

!! + content (subsequent cells in line)

default heading format bold text on light blue bold text only
data cell | + content

+ another cell or ^ or |

| + content (1st cell in physical line)

|| + content (subsequent cells in line)

multiple cells in row must be in same phyical line may be in multiple physical lines
multi-row cells start with | or ^ after first row html rowspan clause
(avoid if variable number of rows)
multi-column cells followed by 0-space cells
(e.g. || or ^^, etc)
html colspan clause
html codes in tables do not work most work

HTML in mediawiki tables

html codes in mediawiki tables  
after {| . . . applies to entire table
    e.g. lines around table {| style="border-collapse: collapse; border-width: 1px"
after |- . . . applies to entire row
    e.g. pale blue background for heading row |- style="background-color:#def"
code + | at beginning of cell . . . applies to single cell
    e.g. pale blue background for heading cell ! style="background-color:#def"| + content of cell

Other mediawiki features

images Use [[File:{name-of-image-file}|{format-options-list}|{optional-caption}]]

where the format options are separated by |.
These options include borders and positioning.
See details at: http://www.mediawiki.org/wiki/Help:Images

flowcharts
  1. Create a flowchart image using Libreoffice Draw
    • In the drawing bar, under flowchart (a box with rounded corners), click on the shape of box wanted
    • with the mouse, draw the size and position of the box
    • use the connector icon (2 boxes joined by a line) to link the boxes drawn (they automatically appear with arrows, which can be changed by editing the connector)
    • insert the comments wanted by editing the boxes. Comments of decision boxes can be inserted where wanted using the text icon ("T")
  2. export the flowchart to an image file (preferably .png)
  3. use gimp (or similar program) to reduce the image size to that wanted. Reduce the resolution as well. Save with maximum compression.
  4. embed the image in the wiki page