Saisir des documents en reST

Auteur:	Sébastien Mengin sebastien@flibuste.net
Date:	18 juin 2003

Préambule

La saisie d'un document est un exercice devenu laborieux avec l'émergence des logiciels qui permettent à la fois d'éditer le texte (contenu) et de le présenter (traitement).

Ce cumul des fonctions n'est, en effet, pas souhaitable : on n'est pas en même temps l'architecte et le décorateur d'un édifice. On pose d'abord les fondations, on bâtit la structure, puis ensuite on se préoccupe de la décoration. Lorsque la première étape est bien pensée, elle permet à la seconde de s'épanouir facilement.

Il en va de même pour un texte : sa mise en forme ne doit intervenir qu'en dernier lieu. On évite ainsi l'écueil classique qui consiste à produire un texte très enrichi (couleur, graisse, italique, souligné, etc.), mais structurellement très fragile -- et, au final, peu compréhensible.

Notre objectif : saisir un document structuré pour permettre ensuite sa mise en forme de manière automatique en fonction de plusieurs types de supports (papier, écran, etc.)

Qu'est-ce que reST ?

Donner une structure à un texte c'est définir explicitement chaque élément qu'il contient. Par exemple, un texte peut contenir, selon sa nature (article, livre, tract, etc.) un titre, des titres de partie, des citations, des listes (ou énumération), etc. Il faudra donc un code pour chaque élément. Et, comme L'insertion de code au sein d'un texte parasite la rédaction et la relecture, il a fallu trouver un moyen de "coder discrètement", mais toujours de manière stricte et explicite : reST.

Définition : reST est un ensemble de règles de saisie dont l'objectif est de faciliter la structuration d'un document tout en conservant un texte lisible.

Quelles sont les règles de saisie ?

Le meilleur moyen d'en prendre connaissance est d'essayer. Mais, au préalable, voici une liste de précautions à prendre, et à toujours garder en mémoire pendant la rédaction de votre document :

respectez scrupuleusement les espaces :
1. entre les paragraphes (seule 1 ligne vide (au moins) entre deux paragraphes crée un nouveau paragraphe ; les retours chariot simples ne sont pas pris en compte) ;
2. la marge du document est "variable". Elle permet de distinguer plusieurs sections de textes qui n'ont pas le même statut dans la structure du document. Soyez-y particulièrement attentif.
prenez votre temps, reST demande peu d'efforts de compréhension dans son fonctionnement, mais vous aurez besoin, au début de votre pratique, de vous remémorez ses règles. En quelques jours de pratique, tout cela vous sera quasiment "naturel". C'est le but de reST. Si cela échoue, c'est soit que :
1. ce manuel est mal fait, auquel cas merci de nous adresser vos critiques ;
2. reST doit être amélioré -- idem ;
3. vous devez relire le manuel :-)

Attention!

Au moment de la rédaction de ce document nous considérons que les lecteurs sont, par exemple, des rédacteurs d'une équipe éditoriale. Pour tout ce qui concerne l'installation des programmes permettant la conversion des documents suite à leur saisie, nous considérons donc qu'un technicien fait partie de l'équipe et prend à sa charge cette partie strictement technique. En d'autres termes, nous nous adressons aux rédacteurs, et nous pensons qu'ils n'ont pas à acquérir des connaissances en informatique pour utiliser ce système.

Pour vous appuyer sur des exemples concrets, nous fournissons, ci-après, le code-source du document que vous êtes entrain de consulter. Il comporte la plupart des cas rencontrés au cours de la saisie d'un document.

Pour une liste exhaustive des règles de saisie en reST, consulter http://flibuste.net/pythreries/publy/doc