#language: fr
#title: Syntaxe ReStructuredText
#format: rst

Introduction
============

Le format ReStructuredText est développé et documenté indépendamment de
Glasnost dans le cadre du projet DocUtils de Python.  Les pages relevantes
pour la personne désirant écrire un texte au format ReStructuredText sont:

- http://docutils.sourceforge.net/docs/rst/quickstart.html
- http://docutils.sourceforge.net/docs/rst/quickref.html
- http://docutils.sourceforge.net/spec/rst/reStructuredText.html

Ces documents sont les documents de référence mais n'existent actuellement
qu'en anglais.  Pour faciliter au maximum l'utilisation de ce format, cette
page présente les grandes caractéristiques.

Paragraphes
===========

Pour créer des paragraphes, il suffit de laisser une ligne vide, un peu comme
on sépare les paragraphes dans un email (on « saute » une ligne).

Le fait de simplement « revenir à la ligne » (retour-chariot) sans séparer les
deux paragraphes par une ligne vide ne suffit pas pour provoquer un changement
de paragraphe (cela ne provoque même pas de retour à la ligne).

Gras, italique et caractères à chasse fixe
==========================================

On indique simplement du texte en *italique* en le plaçant entre des
astérisques: ``*italique*``.

On indique du texte en **gras** en le plaçant entre doubles astériques:
``**gras**``.

On indique du texte ``en caractères en chasse fixe`` en le plaçant entre
doubles *back-quotes* (le caractère \`): ````chasse fixe````.

Sections
========

Pour diviser le texte en section, il faut utiliser des « en-têtes de section ».
Il s'agit d'une simple ligne de text (d'un mot ou plus) avec une décoration qui
peut être un soulignement, ou un surlignement et soulignement, faits avec des
tirets "``--------``", des signes « égal » "``=========``" ou tout type de
caractère n'étant ni lettre ni chiffre (``= - ` : ' " ~ ^ _ * + # < >``). Les
caractères de soulignement (ou surlignement) doivent être au moins aussi long
que le texte.  Il est important d'utiliser les mêmes caractères tout le long du
document car ceux-ci détermineront les niveaux de titre.  Exemple::

  Chapitre 1  Introduction
  ========================

  1.1  La Patagonie inférieure
  ----------------------------

  1.1.1 La Patagonie inférieure occidentale
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  1.1.2 La Patagonie inférieure occidentale
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  1.2 La patagonie supérieure
  ---------------------------

  Chapitre 2  Historique de la recherche
  ======================================


Liens hypertextes
=================

Vers des adresses quelconques
-----------------------------

Les adresses se trouvant dans le texte ``http://glasnost.entrouvert.org/about``
sont automatiquement converties en lien: http://glasnost.entrouvert.org/about

Il est également possible de faire des liens un utilisant le format suivant:
```Le projet Glasnost <http://glasnost.entrouvert.org>`_`` donnera `Le projet
Glasnost <http://glasnost.entrouvert.org>`_.

À l'intérieur du site
---------------------

Le même système de lien peut être utilisé à l'intérieur du site.  La seule
subtilité consiste à repérer le numéro de l'article, de l'élection, de la
rubrique... vers lequel le lien hypertexte doit pointer.

C'est ce numéro qu'il faut ensuite indiquer dans le lien, par exemple ```Un
article intéressant <article 1>`_`` donnera `Un article intéressant <article
1>`_.


Listes et énumérations
======================

On peut fabriquer des listes de la même manière que dans un email: il suffit
de revenir à la ligne et de commencer la nouvelle ligne avec un tiret, un signe
« plus » ou un astérisque.

Il est possible d'imbriquer des sous-listes dans des listes en faisant précéder
le symbole d'un nombre approprié d'espace. Exemple::

  - rouge
  
    + carreau
	
      * 7
      * 8
      * 9
      * valet
      * ...
	  
    + coeur
	
  - noir
  
    + pique
    + trèfle

Produira:

- rouge

  + carreau
  
    * 7
    * 8
    * 9
    * valet
    * ...
	
  + coeur
  
- noir

  + pique
  + trèfle

Il n'est pas nécessaire d'alterner les symboles (``+ - *``), seuls les espaces
les précédant comptent.

Il est possible de faire des listes numérotées en remplaçant les symboles par
des chiffres (éventuellement romains) ou des lettres. Exemple::

  1. Avec un numéro

  2. Un deuxième point.

     I. et une sous-énumération avec des chiffres romains
     II. yep

Le rendu dépendra cependant de la façon dont le navigateur interprète les
différents codes générés. Pour cette liste:

1. Avec un numéro

2. Un deuxième point.

   I. et une sous-énumération avec des chiffres romains
   II. yep


Tableaux
========

Il existe deux syntaxes pour créer des tableaux: une simple (mais avec quelques
limitations quant à ce qu'elle peut produire) et une plus complexe (mais
permettant de créer des tableaux de tout genre).  La simple::

  ===========  ==============  ===========
  Nom          Prénom          Âge
  ===========  ==============  ===========
  Marso        Ben             23 ans
  Capitaine                    non connu
  Philant      Philippe        46 ans
  Cadoc        Bébé            4 mois
  ===========  ==============  ===========
  

===========  ==============  ===========
Nom          Prénom          Âge
===========  ==============  ===========
Marso        Ben             23 ans
Capitaine                    non connu
Philant      Philippe        46 ans
Cadoc        Bébé            4 mois
===========  ==============  ===========

Et la plus complexe::

  +------------------------+------------+-----------+--------------+
  | En-tête de colonne 1   | En-tête 2  | En-tête 3 | Et 4         |
  +========================+============+===========+==============+
  | la première ligne      | colonne 2  | colonne 3 | colonne 4    |
  +------------------------+------------+-----------+--------------+
  | la deuxième ligne      | Des cellules peuvent s'étendre...     |
  +------------------------+------------+--------------------------+
  | la troisième ligne     | Dans les   | - Et les cellules        |
  +------------------------+ deux sens. | - peuvent contenir       |
  | la quatrième ligne     |            | - d'autres constructions |
  +------------------------+------------+--------------------------+


+------------------------+------------+-----------+--------------+
| En-tête de colonne 1   | En-tête 2  | En-tête 3 | Et 4         |
+========================+============+===========+==============+
| la première ligne      | colonne 2  | colonne 3 | colonne 4    |
+------------------------+------------+-----------+--------------+
| la deuxième ligne      | Des cellules peuvent s'étendre...     |
+------------------------+------------+--------------------------+
| la troisième ligne     | Dans les   | - Et les cellules        |
+------------------------+ deux sens. | - peuvent contenir       |
| la quatrième ligne     |            | - d'autres constructions |
+------------------------+------------+--------------------------+


Lors de l'écriture de tableau, il faut faire très attention à bien aligner
les cellules car un tableau malformé produira une erreur.


Code informatique
=================

Certains utilisateurs de Glasnost veulent parfois afficher du code informatique
dans leurs pages.  C'est possible en terminant le paragraphe précédent par
"``::``". Par exemple::

  Un bout de code::

    def print_hello():
        print 'hello'

pour afficher:

Un bout de code::

  def print_hello():
      print 'hello'

Il est également possible de créer un paragraphe uniquement composé de
"``::``", dans ce cas ce « faux » paragraphe sera supprimé pour ne laisser que
le texte non-formatté.  Exemple::

  ::

    def print_bye():
        print 'bye'

permet de produire:

::

  def print_bye():
      print 'bye'


