SDB:Comment utiliser SDB
Sommaire
Situation
Cet article explique comment écrire des articles pour la base de données SDB.
Procedure
Principe
Les articles de SDB sont écrits pour donner des solutions pour SUSE Linux, mais aussi pour donner des explications plus détaillées à des problèmes avec SUSE Linux.
Si vous avez des problèmes avec SUSE Linux, SDB doit être le premier endroit où chercher de l'aide.
Un article SDB doit être subdivisé de la façon suivante :
- Situation
- Procédure
- Liens
ou
- Symptômes
- Causes
- Solutions
- Liens
Notez que les articles de SDB doivent toujours -si possible- décrire la solution la plus simple.
Cependant, il est aussi utile d'indiquer la solution la plus rapide utilisant la ligne de commande ou la modification des fichiers de configuration. Dans ce cas, la section "Solutions" devrait être divisée en plusieurs sous-sections.
Avant d'entrer dans les détails de syntaxe, voici un exemple (en syntaxe mediawiki. Pour voir cet exemple comme un article, voyez SDB:Changing NTP Server - SDB Example.)
Exemple d'article
<!-- SDB information SDB:title: Changing NTP Server - SDB Example SDB:author: mlasars SDB:date: 2005-10-17 --> Version: 9.0 [[Category:SDB:Network|N]] [[Category:SDB:9.0|N]] This article is an example for writing SDB articles. == Situation == You set the clock on your computer using ntp, but the server you are using is no longer working. == Procedure == This article describes several solutions: === with YaST2 === Start YaST2, select "Network Services" and start the module "NTP Client". In "Select" choose "public server". Choose your country from the list, or one that is closest to you, and in the second panel choose a different server. Then click "Test", and if the test was successful, "Ok". Complete the configuration with "Finish". === on the command line === Open the file <code>/etc/sysconfig/ntp</code> and change the variable <code>NTPD_INITIAL_NTPDATE=""</code> to the server of your choice. Then restart ntp with rcntpd restart == Links == [[SDB:Time Synchronization Through the Network]] <keyword>ntp,xntp,time,synchronize</keyword> [[en:SDB:ntp_server_change(example)]]
Créer un nouvel article
Un nouvel article de SDB est simplement une nouvelle page du wiki, dont le nom est précédé de "SDB:", par exemple
[[SDB:Historique]]
Comme vous devez être enregistré et connecté pour écrire sur le wiki, vous avez de ce fait même une page personnelle. Vous pouvez atteindre cette page en cliquant sur votre nom en haut de n'importe quelle page du wiki.
Pour que vous puissiez suivre la page que vous allez créer, la modifier au besoin, le plus simple est de la créer sur votre page personnelle, en tapant son nom entre crochets comme ci-dessus.
Si vous êtes pressé, vous pouvez court-circuiter cette étape en modifiant la barre d'URL pour y mettre le nom voulu (n'oubliez pas SDB:).
En cliquant sur le lien dans votre page ou en validant la barre d'URL, vous allez être directement renvoyé dans la nouvelle page en mode édition.
Si l'article existe déjà, il va se présenter ou apparaitre en bleu sur votre page (il est en rouge sur votre page s'il n'existe pas).
N'oubliez pas qu'il est préférable d'utiliser un titre en "bon français", avec les accents et les espaces.
Conclusion
Historique
Quand vous avez fini d'éditer votre article, prenez la peine de l'ajouter à l'Historique.
Utilisez cette syntaxe
AAAAMMJJ [[SDB:<nom article>]]
C'est à dire :
20051016 [[SDB:Howto]]
Utilisez, s'il vous plaît le format de date international. La liste est triée en ordre descendant, afin que la date la plus récente soit toujours en haut de la liste
Si vous faites une modification conséquente à un article, comme le mettre à jour pour une nouvelle version, mentionnez-le dans l'historique. Ne le faites pas pour des changements mineurs
Traductions
A présent, le wiki openSUSE supporte le français, l'anglais, l'allemand et l'espagnol. Si vous le voulez et si vous connaissez une de ces langues, merci de traduire votre article. Si vous ne savez pas ou que vous n'êtes pas sûr de maitriser suffisamment la langue en question, merci d'envoyer un mail à la mailing-list openSUSE-wiki pour demander à quelqu'un d'autre de traduire l'article.
Si vous avez traduit un article, merci d'ajouter le lien "interwiki" à la fin de l'article. Si vous avez traduit un article français en anglais, ajoutez ceci à la fin de l'article français :
[[en:SDB:<nom anglais>]]
A la version anglaise, ajoutez :
[[fr:SDB:<nom français>]]
Pour l'instant les raccourcis suivants sont supportés :
de Allemand en Anglais fr Français es Espagnol
Changer les articles existants
Avec l'intégration de SDB dans le wiki openSUSE, il est maintenant possible de modifier tous les articles. Si vous voulez modifier un article de façon importante, il est sans doute bon d'en discuter d'abord avec les auteurs originaux. Merci d'utiliser à cet effet la page "discussion" jointe à chacun des articles.
Ce n'est pas obligatoire, mais cela rends la collaboration plus facile et plus agréable. Si vous n'êtes pas d'accord avec une solution, un mail à la liste opensuse-wiki peut vous aider à clarifier la situation.
Les changement minimes peuvent se faire sans discussion.
Balises SDB
Table des matières
Dès lors qu'un article contient au moins trois sections === Section ===, le wiki génrère automatiquement une table des matières. Donc si vous utilisez l'organisation standard SDB "Situation, Procédure, Liens", cela se produit automatiquement.
Meta-informations SDB
Merci d'inclure les meta-informations suivantes au début de chaque article. Elles ne seront pas affichées.
<!-- SDB information SDB:title: Changing NTP Servers - SDB Example SDB:author: mlasars SDB:date: 2005-10-17 -->
Si vous faites des modifications importantes à un article, ajoutez votre nom à la ligne "author" (auteur, en anglais), séparé par une virgule. Ne changez aucune autre meta-information, surtout pas la date (SDB:date). Tous les changements dans un article peuvent être vus dans l'historique de l'article. Les meta-informations sont destinées à conserver les informations essentielles dans l'article lui-même en cas de future réorganisation du système.
Version
Au début de l'article, merci de définir la version de SUSE Linux pour laquelle l'article est valide. Il y a plusieurs possibilités :
Version: 8.0 Version: - 8.0 Version: 8.0 - Version: 8.0 - 8.1
Si l'article n'est pas spécifique à une version particulière, contentez-vous de ne pas mettre d'indication de version. Si il n'est applicable qu'à une architecture ou une variante de SUSE Linux, indiquez-le également.
Version: 9.2 x86_64 Version: 9.1 DVD Version: 10.0 ppc
Pour l'instant, SUSE Linux supporte les architectures suivantes : i386, x86_64 (64bit, AMD64 and Intel EM64T) and ppc (PowerPC (Mac)).
Vous pouvez spécifier également l'une des variantes suivantes : Box (la version du commerce), FTP, CD, DVD et OSS.
Merci de n'ajouter cette indication que si le problème est réellement spécifique à cette variante.
Note: Pour avoir un joli cadre autour de l'indication de version, commencez toujours la ligne par un espace.
Catégories
Tout article de SDB devrait être accessible à travers les catégories. Vous trouverez une liste des catégories disponibles là : Category:SDB
Ajoutez la catégorie au début de l'article ainsi :
[[Categorie:SDB:8.0|C]] [[Categorie:SDB:Network|C]]
"Categorie:" indique au wiki que l'on veut traiter d'une catégorie ; le nom lui-même commence par "SDB:" ; après le nom se trouve le caractère "|" appelé pipe en anglais et souvent en français (en vrai français "tube") suivi de l'initiale du titre de l'article, dans l'exemple ci-dessus, un "C".
Comme vous pouvez le voir, le nom réel de la catégorie est soit le numéro de version de la distribution soit le sujet de l'article réduit à un mot clé. Il est possible de mettre le même article dans plusieurs catégories (c'est le cas ci-dessus). Il est possible de créer une nouvelle catégorie (il suffit de mettre un nouveau nom), n'en abusez pas.
Keywords
Ajoutez tous les mots-clés auxquels vous voulez associer votre article à la fin de l'article :
<keyword>ntp,time,xntp,synchronize</keyword>
Vous pouvez utiliser tout ce que vous voulez comme mots clés.
Syntaxe
Base
A part sa syntaxe spécifique (Wikipédia), MediaWiki supporte aussi les balises html standard (à l'exception marquante des balises<a>. Chaque fois que possible, utilisez les balises Wiki, qui sont plus faciles à comprendre et à corriger. Les éléments les plus importants sont donnés ci-dessous.
Pour des instructions plus détaillées, voir :
http://fr.wikipedia.org/wiki/Wikipédia:Syntaxe_wikipédia
Sections
- Niveau 1: == Titre de niveau 1 == (pour Situation, Procédure, Liens)
- Niveau 2: === Sous-titre === (par exemple pour "YaST2", "Ligne de commande")
- Niveau 3: ==== Un niveau plus bas ==== (sous-section supplémentaire, par exemple pour des versions différentes)
(NOTA: la balise =Titre de page= est réservée au titre de la page. S'il est bien choisi, il est explicite. On peut prendre n'importe quel titre ou presque, y compris avec des accents, des espaces blancs... éviter quand même les signes de ponctuation.
Spécialité française
En français, contrairement à d'autres langues comme l'anglais, nous avons des accents. Mediawiki est codé en UTF-8, c'est à dire qu'il peut coder tous les caractères utilisables.
Il nous suffit donc de taper les caractères accentués directement.... quand ils sont au clavier.
Et ceux qui n'y sont pas ? Si vous êtes obligés d'utiliser Windows pour écrire ici, utilisez dans un moteur de recherche, il existe un pilote clavier français gratuit écrit par Denis Liégeois qui résoudra votre problème.
Pour les autres, sachez que si vous pressez la touche de verrouillage majuscules (en général indiquée par un cadenas, juste au dessus de la touche majuscule de gauche), elle reste activée et un voyant s'allume.
Dans cette position, les touches accentuées sont prises en majuscule.
ÉÈÂÎÛÔÀÙ
et j'en oublie certainement.
Sachez aussi que, contrairement à ce que beaucoup croient, l'usage officiel réclamé par l'Académie Française est de mettre les accents sur les majuscules..
De plus, les caractères de ponctuation "hauts", c'est à dire
: ; ! ?
prennent une espace fine insécable devant.
Cette espace fine insécable (c'est bien au féminin) existe en html et pour Mediawiki, elle s'écrit  . L'espace mot insécable ordinaire (un peu plus large) s'écrit : .
(n'oubliez pas le point virgule à la fin).
également tout ce qui ressemble à une parenthèse ouvrante
([{-
prend un espace devant et pas d'espace après :
tout ce qui ressemble à une parenthèse fermante :
)]}-
prends un espace après mais rien avant.
Mise en page
Il n'est pas nécessaire de marquer les paragraphes avec <p>paragraph</p> comme en HTML, les paragraphes sont simplement séparés par une ligne blanche. Par contre, du coup, il est indispensable de laisser une ligne blanche dans le texte source si on veut séparer deux paragraphes, sinon les lignes sont montrées à la suite l'une de l'autre.
| Texte saisi dans la fenêtre d'édition | Résultat affiché |
Ceci est le premier paragraphe qui peut être écrit sur plusieurs lignes. Ceci est le second paragraphe |
Ceci est le premier paragraphe qui peut être écrit sur plusieurs lignes. Ceci est le second paragraphe |
Texte (bold, italic, code)
Pour mettre en évidence un paragraphe ou un mot, utilisez la syntaxe suivante :
| Style | Texte à saisir | Résultat affiché |
| gras | '''Merci de ne l'utiliser que rarement et seulement pour des paragraphes ou des mots importants.''' | Merci de ne l'utiliser que rarement et seulement pour des paragraphes ou des mots importants. |
| italiques | ''Example d'italiques'' | Example d'italiques |
| code | Pour des commandes ou des variables, utilisez : <code>rcapache2</code> | Pour des commandes ou des variables, utilisez : rcapache2
|
Énumérations / listes
Exemples d’énumérations :
| Texte à saisir | Résultat affiché |
* Planetes ** Mars ** Terre *** Lune |
|
#Déplacement ## Avion ## Voiture ### Taxi |
|
Pour les liens en fin d'article, utilisez * Link sans autre subdivision.
Extraits de fichiers de commande et de configuration
Les lignes contenant une seule commande peuvent simplement commencer par un espace, ce qui entraine la mise en encadré.
rcapache2 restart
Les commandes inclues dans le texte peuvent utiliser <code>commande</code>.
Pour lister des fichiers entiers, utilisez la syntaxe suivante :
| Texte à saisir | Résultat affiché |
<pre> ## Path: Network/Remote access/SSH ## Description: SSH server settings ## Type: string ## Default: "" ## ServiceRestart: sshd # # Options for sshd # SSHD_OPTS="" <nowiki></nowiki> </pre> |
## Path: Network/Remote access/SSH ## Description: SSH server settings ## Type: string ## Default: "" ## ServiceRestart: sshd # # Options for sshd # SSHD_OPTS="" |
nowiki
Dans certaines situations vous pouvez avoir besoin de désactiver la mise en page faite par le wiki :
| Texte à saisir | Résultat affiché | Sans nowiki |
|
<nowiki>ni '''Gras''', ni ''Italiques''</nowiki> |
ni '''Gras''', ni ''Italiques'' |
ni Gras, ni Italiques |
Liens
Les liens vers d'autres articles de SDB commencent par SDB: [[SDB:howto]], mais il n'est pas nécessaire d'inclure un label explicite. Il est aussi possible de sauter à une position spécifique dans l'article, c'est à dire :
[[SDB:howto#Stil]]
Qui sera affiché
SDB:howto#Stil
Si vous utilisez ces liens directs vers une section d'un article, ajouter le label du lien peut être utile.
[[SDB:howto#Stil|Stil]]
Sera affiché comme
Stil
Les liens extérieurs devraient avoir un label si il n'est pas évident de voir vers où ils pointent ou pour rendre le lien affiché plus court.
[http://www.suse.de SUSE]
Sera affiché :
SUSE
Dans ce cas il n'y a qu'un crochet ouvrant et un fermant et le lien est simplement séparé du label par un espace au lieu d'un |.
Notez que, dans certains pays, des liens extérieurs peuvent être une violation de la loi locale. Par exemple, en Allemagne il est illégal de mettre un lien vers un logiciel utilisé pour détourner une technologie de protection contre la copie. Cette loi est en cours de discussion de France (en Février 2006).
Si vous n'êtes pas sûr de savoir si vous pouvez utiliser certains liens, posez la question sur la liste opensuse-wiki (voir Communicate) et- en attendant, abstenez-vous.
Tableaux
Vous pouvez regarder comment est écrite la présente page ou aller voir http://fr.wikipedia.org/wiki/Aide:Tableau
Images
Jusqu'à présent, SDB n'a pas utilisé d'images. Ne les utilisez que quand c'est vraiment nécessaire, pour ne pas perturber la lecture de l'article.
Cependant, si vous utilisez la génération de vignettes, comme dans l'exemple ci-contre, l'image sera réduite et placée à droite, et le texte sera écrit à gauche.
L'image ci-contre a été insérée tout en haut du paragraphe, avec le code :
[[Image:Image_exemple_SDB.jpg|thumb|Un accessoire disparu]]
Voir :
- http://fr.wikipedia.org/wiki/Wikipédia:Description_d'une_image
- http://fr.wikipedia.org/wiki/Wikipédia:Règles_d'utilisation_des_images
- http://fr.wikipedia.org/wiki/Aide:Comment_insérer_une_image
Style
Comment s'adresser à vos lecteurs
Il est préférable de garder un ton neutre, ni trop pédant ni trop familier (évitez le tutoiment). Evitez la polémique, résistez à l'envie de faire un mauvais jeux de mots sur les concurrents :-).
Terminologie
Il est parfois difficile de se passer du terme anglais dans les parties techniques. Si vous dites qu'une application a une bogue, vous risquez d'être mal compris, alors que dire qu'il y a un bug est plus courant. Essayez d'écrire pour le plus grand nombre. Cependant, quand le terme français est pertinent ou que son sens ne peut faire de doute, il vaut mieux l'utiliser. IL peut-être utile de mettre le terme anglais entre parenthèses si le terme français est malheureux et réciproquement. En bash, "|" est a pipe ; ne pas traduire et laisser "une pipe" est malsonnant, utiliser "un tuyau" n'est pas forcément idéal.
Utilisez la page glossaire d'équivalences entre l'anglais et le français si vous avez de bonnes idées ou si vous en manquez :-).
Faites simple et facile!
Même si parfois l'utilisation du shell semble plus simple, particulièrement pour vous, essayez de penser aux débutants sous Linux et expliquez aussi comment un problème peut être résolu avec Yast ou un autre outils.
Un bon article SDB doit décrire toutes les étapes. Aussi, n'écrivez pas :
Dans /etc/inittab, changez le niveau d'exécution par défaut pour 3
Mais :
Connectez vous comme root (administrateur) et ouvrez le fichier /etc/inittab avec l'éditeur de votre choix (par exemple vi ou pico). Changez la ligne id:5:initdefault: pour id:3:initdefault: ainsi le système ne démarrera plus en mode graphique
Ne prenez pas ça comme une règle formelle, mais n'oubliez pas que beaucoup de débutants aussi, utilisent SUSE Linux :-).
Maintenance
Il est fréquemment nécessaire d'adapter des articles de SDSB à une nouvelle version de SUSE Linux, ou même d'en écrire de nouveaux si les changements sont trop fondamentaux.
Essayez de maintenir vos articles SDB. Par exemple, si vous remarquez que votre article ne s'applique plus à la dernière version de SUSE Linux, changez la ligne "version"