Marqueurs reStructuredText

author:	William Dode
Contact:	wilk at flibuste.net
Copyright:	Ce texte est placé dans le domaine public.

Documentation des marqueurs de reStructuredText, d'après quickref de Tibs et David Goodger.

Sommaire

Styles

Emphase

L'emphase peut être simple ou forte. (italique ou gras):

*italique* **gras**

italique gras

Attention!

les marqueurs doivent coller au texte (pas d'espace)

Littéral

Un texte entre doubles apostrophes inversées `` ne sera pas analysé (les marqueurs qu'il peut contenir ne seront pas traité):

``texte littéral contenant des marqueurs *non interprétés*``

texte littéral contenant des marqueurs *non interprétés*

Le rendu peut-être différent selon la feuille de style.

Caractère d'échappement

Pour forcer l'affichage d'un marqueur, on peut :

utiliser le mode Littéral
le faire précéder d'un \
```
Les étoiles vont être \*affichées\*
```

Les étoiles vont être *affichées*

Sections

Les titres de sections sont identifiés en soulignant (et surlignant, éventuellement) la phrase ;
Le soulignement doit être au moins aussi long que la phrase ;
La phrase doit se trouver sur une seule ligne ;
Le niveau des sections est identifié par un signe de soulignement différent ;
Si le document commence par un titre et un sous-titre, ceux-ci seront considérés comme titre et sous-titre de document et non comme titre et sous-titre de section

Les signes de soulignement possibles sont

"``= - ` : ' " ~ ^ _ * + # < >``".

=================
Titre du document
=================
----------------------
Sous-titre du document
----------------------

Titre de la première partie
===========================

texte...

Titre de la première section
----------------------------

texte...

Titre de la seconde partie
==========================

Titre de la première section de la deuxième partie
--------------------------------------------------

etc.

Paragraphes et mise en forme

Paragraphes simples

Pour changer de paragraphe il est nécessaire de laisser une ligne vide:

Premier paragraphe.

Deuxième paragraphe,
sur plusieurs lignes
qui seront automatiquement
mises en forme.

Premier paragraphe.

Deuxième paragraphe, sur plusieurs lignes qui seront automatiquement mises en forme.

Paragraphes décalés

Il est possible de décaler un paragraphe à l'aide d'espaces réguliers à gauche:

Premier paragraphe.

  Deuxième paragraphe,
  décalé de deux espaces
  à gauche

Premier paragraphe.

Deuxième paragraphe, décalé de deux espaces à gauche

Ce décalage sert à mettre de côté un paragraphe au niveau de la mise en forme, mais est aussi utilisé pour les listes, les directives et tout ce qui fait qu'un paragraphe doit être considéré différemment.

Paragraphes non mis en forme

Pour empêcher la mise en forme automatique, nous utilisons :: puis un paragraphe décalé, cela est utile pour les poèmes, par exemple:

::

  ceci
      est un
  paragraphe
            dont
  la
    mise en forme ne sera pas automatique. Les *balises* ne sont pas *interprétées*

ceci
    est
paragraphe
          dont
la
  mise en forme ne sera pas automatique. Les *balises* ne sont pas *interprétées*

Note

La présentation d'un paragraphe non mis en forme dépend de la feuille de style.

Il est également possible d'utiliser les directives bloc-textuel ou code-interprété. Ces directives permettent d'interpréter les balises au sein d'un paragraphe non mis en forme (l'emphase etc.)

Transition

Pour effectuer une transition entre deux paragraphes sans changer de section:

Au moins 4 traits d'union

----

Une transition doit impérativement être suivie d'un paragraphe

Au moins 4 traits d'union

Une transition doit impérativement être suivie d'un paragraphe

Commentaires

Tout paragraphe commençant par .. sur une ligne vide sera traité comme un commentaire à ne pas afficher dans la version finale:

..   Ce paragraphe
     est un commentaire

..

     Ce paragraphe ne sera pas traité comme un commentaire
     en raison de la ligne vide suivant les ..

Listes

Puces

Les listes à puce sont définies par un des caractères -, * ou + au début de chaque lignes, en décalant les lignes comme les paragraphes décalés:

- première puce
- deuxième puce
- troisième puce
  sur plusieurs
  lignes

première puce
deuxième puce
troisième puce sur plusieurs lignes

Note

Les listes doivent impérativement être précédées et suivies d'une ligne vide.

Numérotées

De la même manière, les listes peuvent être numérotées:

1. un
2. deux
   sur deux lignes

un
deux sur deux lignes

Définitions

Définitions de mots, utilisant des paragraphes décalés:

Un
  Première définition

Deux
  Deuxième définition
  sur plusieurs lignes

Un: Première définition
Deux: Deuxième définition sur plusieurs lignes

Options

Pour documenter les options de lignes de commandes (de programmes):

-a            option "a"
-b file       option avec paramètres
              et une description sur
              plusieurs lignes
--long        option longue
--input=file  option longue avec
              paramètres
/V            options style DOS/VMS

`-a`	option "a"
`-b file`	option avec paramètres et une description sur plusieurs lignes
`--long`	option longue
`--input=file`	option longue avec paramètres
`/V`	options style DOS/VMS

Champ / valeur

Les champs servent à afficher des définitions et peuvent parfois être analysés par le programme pour servir de données:

:auteur: Nom de l'auteur
:date: Date du document

auteur:	Nom de l'auteur
date:	Date du document

Tables

Deux possibilités:

+------------+------------+-----------+
| Entête 1   | Entête 2   | Entête 3  |
+============+============+===========+
| ligne 1    | colonne 2  | colonne 3 |
+------------+------------+-----------+
| ligne 2    | texte sur 2 colonnes   |
+------------+------------+-----------+
| ligne 3    | texte sur  | - blocs   |
+------------+ 2 lignes   | - dans    |
| ligne 4    |            | - cellule |
+------------+------------+-----------+

Entête 1	Entête 2	Entête 3
ligne 1	colonne 2	colonne 3
ligne 2	texte sur 2 colonnes
ligne 3	texte sur 2 lignes	blocs dans cellule
ligne 4	texte sur 2 lignes	blocs dans cellule

Ou plus simple:

=====  =====  ======
   Entrée     Sortie
------------  ------
  A      B    A ou B
=====  =====  ======
Non    Non    Non
Oui    Non    Oui
Non    Oui    Oui
Oui    Oui    Oui
=====  =====  ======

Entrée		Sortie
A	B	A ou B
Non	Non	Non
Oui	Non	Oui
Non	Oui	Oui
Oui	Oui	Oui

Notes

Notes numérotés

La numérotation peut être automatique avec un # ou forcée avec un nombre:

Ceci est une note auto-numérotée [#]_ (attention à l'espace entre le mot précédent l'appel de note et le crochet)

Ceci est une note forcée [4]_

En fin de paragraphe ou de texte on trouve la note : 

.. [#] Première note
.. [4] Deuxième note
       sur plusieurs lignes

Ceci est une note auto-numérotée¹ (attention à l'espace entre le mot précédent l'appel de note et le crochet)

Ceci est une note forcée⁴

En fin de paragraphe ou de texte on trouve la note :

[1]	Première note

[4]	Deuxième note sur plusieurs lignes

Notes numérotée avec label

Ceci est une note [#première]_

.. [#première] Première note

Un lien peut être relié avec première_

Ceci est une note²

[2]	Première note

Une note avec label peut avoir un lien : première

Notes avec symbole

Ceci est une note [*]_ et une autre [*]_

.. [*] Première note
.. [*] Deuxième note

Ceci est une note [*]_ et une autre [*]_

.. [*] 1ere note
.. [*] 2eme note

Citations

 Ceci est une [citation]_, ou ceci citation_

.. [citation] texte de la citation

Ceci est une [citation], ou ceci citation

[citation]

texte de la citation

Liens

Les liens de la forme http://www.domaine.tld et mailto:nom@domaine.tld sont automatiquement reconnus.

Liens externes

Lien court_, `lien long`_

.. _court:  http://www.domaine.tld
.. _lien long: http://www.domaine.tld

Lien court, lien long

Autre solution :

`Texte du lien <http://www.domaine.tld>`_

Texte du lien

Liens internes

Pour créer un lien vers un titre de section:

Ceci est un lien vers le titre Liens_ avec des ` pour un
titre long `Liens externes`_

Ceci est un lien vers le titre Liens avec des ` pour un titre long Liens externes

Pour créer un lien vers un endroit du texte:

Mettre une référence dans le texte

.. _référence:

Créer le lien référence_

Mettre une référence dans le texte

Créer le lien référence