La syntaxe SPIP
---------------

Ces règles typographiques de Glasnost sont tirées de celles de SPIP
[#_]. Cette documentation est d'ailleurs basée sur celle de SPIP.

Typographie française
'''''''''''''''''''''

Glasnost ne respecte pas automatiquement la typographie française.
C'est le travail du rédacteur. Par contre, il apporte une aide
précieuse sur certains petits détails. Ainsi il remplace
automatiquement les espaces situés avant les ``:``, ``;``, ``!``,
``?`` et ``«`` par des espaces insécables. Il procède de même pour les
espaces situés après les et ``»``.

Paragraphes
'''''''''''

Pour créer des paragraphes, il suffit de laisser une ligne vide, un
peu comment on sépare les paragraphes dans un courriel (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 & caractères de chasse fixe
''''''''''''''''''''''''''''''''''''''''''

On indique simplement du texte en italique en le plaçant entre des
accolades simples ``{`` et ``}``.

On indique du texte en gras en le plaçant entre des accolades doubles
``{{`` et ``}}``.

On indique du texte en caractères de chasse fixe en le plaçant entre
des parenthèses doubles ``((`` et ``))``.

Intertitres
'''''''''''

Les intertitres sont des titres à l'intérieur d'un texte permettant
d'en indiquer la structure. On les indique très simplement en les
plaçant entre des accolades triples : ``{{{Un titre de partie}}}``.

Trait de séparation horizontal
''''''''''''''''''''''''''''''

Il suffit de placer une ligne contenant une succession d'au moins
quatre tirets ``----`` ou soulignés ``____``.

Les liens hypertextes
'''''''''''''''''''''

On fabrique facilement un lien hypertexte avec le code suivant : ::

	[Glasnost->http://www.entrouvert.org/rubrics.py/2] s'inspire
	beaucoup de [SPIP->http://www.uzine.net/spip]

L'adresse du lien peut être une adresse absolue (commençant, comme
ici, par ``http://``, une adresse relative (vers une autre page du
même site), un lien vers un document utilisant un protocole de
l'internet ( ``ftp://`` ), une adresse courriel...

Le nom du lien (la partie située entre le crochet ouvrant ``[`` et la
flèche ``->`` n'est pas obligatoire. S'il est absent, il est remplacé
par l'adresse du lien.


Liens hypertextes à l'intérieur du site
'''''''''''''''''''''''''''''''''''''''

Ce même système de liens hypertextes permet aussi le création de liens
à l'intérieur du site : il suffit de repérer le numéro de l'Article,
de la Rubrique, etc vers lequel vous voulez faire un lien.

Par exemple ``[lien->article 17]`` est un lien vers l'article 17.

``[->article 17]`` affiche le titre de l'Article 17 avec un lien
vers cet Article.

Pour les Élections, les Groupes, les images, les Personnes, les Rubriques, etc,
le principe est le même : il suffit de remplacer le mot ``article`` par
``election`` pour les élections, ``group`` pour les groupes, ``image`` ou
``file`` pour les images ou Fichiers, ``person`` pour les Personnes,
ou ``rubric`` pour les Rubriques.

Images dans le texte
''''''''''''''''''''

Plutôt que d'afficher un lien vers une image comme dans l'exemple
précédent, il est souvent préférable d'afficher directement l'image
dans le texte.

Pour ce faire, il suffit d'indiquer le numéro ou l'url de l'image
entre ``<`` et ``>``, précédée du mot clef ``image``.


Notes de bas de page
''''''''''''''''''''

Une note de bas de page est, habituellement, signalée par un numéro
placé à l'intérieur du texte, numéro repris en bas de page et
proposant un complément d'information.

Dans Glasnost, cette fonctionnalité (assez lourde à gérer manuellement
en HTML) est automatisée : les notes sont numérotées par Glasnost, qui
gère également des liens hypertextes à l'intérieur du document pour
passer directement de l'appel de note au texte de la note
correspondante, et vice-versa.

Une note de bas de page est indiquée, dans Glasnost, en étant placée
entre doubles crochets ``[[`` et ``]]``. Par exemple, 
``[[Voici un complément d'information`` donnera : [#]_

Listes ou énumérations
''''''''''''''''''''''

On peut fabriquer des listes de la même manière que dans un courriel : il
suffit de revenir à la ligne et de commencer la nouvelle ligne avec un
tiret  ``-``.

Notez : ici un simple retour à la ligne suffit (on peut faire des
énumérations dans le même paragraphe).

Il est aussi possible de créer des sous-listes (et des
sous-sous-listes, ...) à l'intérieur des listes. Il suffit de précéder
les tirets du nombre approprié d'espaces.

Si le tiret est immédiatement suivi d'un des caractères « 0 », « 1 »,
« 2 », « 3 », « 4 », « 5 », « 6 », « 7 », « 8 », « 9 », « a », « A »,
« i » ou « I », lui-même suivi d'un point, chaque élément de la liste
sera précédé d'un numéro calculé automatiquement.

Par exemple, ::

	- rouge
	 - carreau
	  -1. 7
	  -2. 10
	  -3. As
	 - coeur
	- noir
	 - pique
	 - trèfle

sera affiché ainsi :

* rouge

  - carreau

    1. 7
	
	2. 10

	3. As

  - coeur

* noir

  - pique
  - trèfle


Tableaux
''''''''

Pour réaliser des tableaux très simples dans Glasnost, il suffit de
faire des lignes dont les « cases » sont séparées par le symbole « | »
(pipe, un trait vertical), lignes commençant et se terminant par des
traits verticaux. Par exemple, le tableau :

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

se code ainsi : ::

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

Note : La première ligne du tableau apparaît différemment des autres
lignes, si et seulement si, toutes les cases de la première ligne sont
en gras (i.e. commencent par « {{ » et se terminent par « }} »).

Caractères spéciaux
'''''''''''''''''''

Certains caractères ont des rôles particuliers :

* le caractère ``\`` (antislash) indique que le caractère suivant
  doit être préservé, sans chercher à tenir compte de son rôle
  éventuel.
* le caractère ``~`` (tilde) indique un espace insécable.
* la séquence ``\n`` force un saut de ligne. Cela peut-être utile,
  par exemple à l'intérieur d'une liste ou d'une cellule de
  tableau.

Court-circuit des raccourcis de Glasnost
''''''''''''''''''''''''''''''''''''''''

Dans certains cas, il peut être utile d'indiquer à Glasnost que
certaines parties d'un document ne doivent pas être "traitées" par
le filtre des raccourcis typographiques et soient considérées comme du
HTML pur.

Le code de ce raccourci est : ::

	<html>texte à ne pas transformer, contenant un mot en <b>gras</b></html>


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

Pour afficher du texte brut (sans aucune mise en forme, et
généralement dans une police à chasse fixe), il suffit d'encadrer ce
texte par ``<code>`` et ``</code>``.
Par exemple, cet extrait du code source de Glasnost : ::

	def handle_antislash(self, group):
	  character = group[1]
	  if character in ['<', '&']:
	    return self.handle_htmlEntity(character)
	  return character

a été écrit de la manière suivante : ::

	<code>
	def handle_antislash(self, group):
	  character = group[1]
	  if character in ['<', '&']:
	    return self.handle_htmlEntity(character)
	  return character
	</code>


.. [#] : La très grande majorité des raccourcis typographiques de SPIP
   s'appliquent sans changement. Toutefois, le moteur de SPIP ne
   convenant pas pour Glasnost, il a été complètement réécrit. Certaines
   fonctionnalités présentes dans SPIP n'ont pas été (encore ?)
   implémentées, d'autres absentes de SPIP ont été ajoutées et certaines
   règles typographiques identiques peuvent conduire à de légères
   différences d'affichage.

.. [#] : Voici un complément d'information.

