La syntaxe reStructuredText
---------------------------

Le format reStructuredText est développé et documenté indépendamment de
Glasnost dans le cadre du projet DocUtils de Python.

Les documents suivants sont les documents de référence mais n'existent
actuellement qu'en anglais :

* Une introduction (*A ReStructuredText Primer*) :

  http://docutils.sourceforge.net/docs/rst/quickstart.html

* Un récapitulatif (*Quick reStructuredText*) :

  http://docutils.sourceforge.net/docs/rst/quickref.html

* Les spécifications complètes (*reStructuredText Markup Specification*) :

  http://docutils.sourceforge.net/spec/rst/reStructuredText.html

* Les directives (*reStructuredText Directives*) :

  http://docutils.sourceforge.net/spec/rst/directives.html


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érisques :
``**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
''''''''

Un titre de section est une simple ligne de texte soulignée avec l'un
des caractères suivants : ``= - ` : ' " ~ ^ _ * + # < >``.

La ligne de caractères de soulignement doit être exactement aussi
longue que la ligne de titre.

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
'''''''''''''''''

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>`_.

Liens hypertextes à 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 syntaxe 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
=========  ========  =========


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


Texte brut
''''''''''

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'






