Index: jrst2/doc/fr/Todo.rst diff -u /dev/null jrst2/doc/fr/Todo.rst:1.1 --- /dev/null Wed May 30 17:07:10 2007 +++ jrst2/doc/fr/Todo.rst Wed May 30 17:07:05 2007 @@ -0,0 +1,24 @@ +==== +Todo +==== + +Voici la liste des tâches qui reste à faire. Si quelqu'un souhaite aider, ou +a une idée à proposer il ne faut pas hésiter. + +- intégrer une date multiformat +- faire une feuille de style de conversion de xhtml -> xdoc + +- la documentation en anglais +- faire une règle ant pour aider à la génération + + destination est le répertoire destination + extension est la modification de l'extension des fichiers sources avec + cette extension + +- un export vers pretion, magic, ou autre outil de présentation. + +- finir l'export en rst (tableau) +- permettre l'import de d'autre format que rst, par exemple .sxw + ce qui permettra de convertir simple du .sxw en rst. + +- Faire une doclet qui permette d'écrire les Javadocs en RST Index: jrst2/doc/fr/fonctionnalites.rst diff -u /dev/null jrst2/doc/fr/fonctionnalites.rst:1.1 --- /dev/null Wed May 30 17:07:10 2007 +++ jrst2/doc/fr/fonctionnalites.rst Wed May 30 17:07:05 2007 @@ -0,0 +1,248 @@ +========================= +Fonctionnalités proposées +========================= + +La DTD de Docutils : http://docutils.sourceforge.net/docs/ref/doctree.html + +.. contents:: Sommaire + +Fonctionnalités implantées +========================== + +Element racine +-------------- + +- document_ + +Elements titre +-------------- + +- subtitle_ +- title_ + +Elements bibliographiques +------------------------- + +- docinfo_ +- author_ +- authors_ +- organization_ +- address_ +- contact_ +- version_ +- revision_ +- status_ +- date_ +- copyright_ + +Elements de décoration +---------------------- + +- decoration_ +- footer_ +- header_ + +Elements structurels +-------------------- + +- section_ +- topic_ +- sidebar_ +- transition_ + +Elements du corps +----------------- + +- admonition_ +- attention_ +- block_quote_ +- bullet_list_ +- caution_ +- classifier_ +- danger_ +- definition_ +- definition_list_ +- definition_list_item_ +- description_ +- doctest_block_ +- enumerated_list_ +- error_ +- field_ +- field_body_ +- field_list_ +- field_name_ +- footnote_ +- hint_ +- image_ +- important_ +- line_ +- line_block_ +- list_item_ +- literal_block_ +- note_ +- option_ +- option_argument_ +- option_group_ +- option_list_ +- option_list_item_ +- option_string_ +- paragraph_ +- term_ +- tip_ +- warning_ + +Elements des tableaux +--------------------- + +- table_ +- tbody_ +- entry_ +- row_ +- colspec_ +- thead_ +- tgroup_ + +Elements de la ligne +-------------------- + +- emphasis_ +- strong_ +- literal_ +- reference_ +- footnote_reference_ + +Fonctionnalités non-implantées +============================== + +- abbreviation_ +- acronym_ +- attribution_ +- caption_ +- citation_ +- citation_reference_ +- comment_ +- compound_ +- container_ +- figure_ +- generated_ +- inline_ +- label_ +- legend_ +- pending_ +- problematic_ +- raw_ +- rubric_ +- subscript_ +- substitution_definition_ +- substitution_reference_ +- superscript_ +- system_message_ +- target_ +- title_reference_ + +.. _abbreviation: http://docutils.sourceforge.net/docs/ref/doctree.html#abbreviation +.. _acronym: http://docutils.sourceforge.net/docs/ref/doctree.html#acronym +.. _address: http://docutils.sourceforge.net/docs/ref/doctree.html#address +.. _admonition: http://docutils.sourceforge.net/docs/ref/doctree.html#admonition +.. _attention: http://docutils.sourceforge.net/docs/ref/doctree.html#attention + +.. _attribution: http://docutils.sourceforge.net/docs/ref/doctree.html#attribution +.. _author: http://docutils.sourceforge.net/docs/ref/doctree.html#author +.. _authors: http://docutils.sourceforge.net/docs/ref/doctree.html#authors +.. _block_quote: http://docutils.sourceforge.net/docs/ref/doctree.html#block-quote +.. _bullet_list: http://docutils.sourceforge.net/docs/ref/doctree.html#bullet-list +.. _caption: http://docutils.sourceforge.net/docs/ref/doctree.html#caption +.. _caution: http://docutils.sourceforge.net/docs/ref/doctree.html#caution +.. _citation: http://docutils.sourceforge.net/docs/ref/doctree.html#citation +.. _citation_reference: http://docutils.sourceforge.net/docs/ref/doctree.html#citation-reference + +.. _classifier: http://docutils.sourceforge.net/docs/ref/doctree.html#classifier +.. _colspec: http://docutils.sourceforge.net/docs/ref/doctree.html#colspec +.. _comment: http://docutils.sourceforge.net/docs/ref/doctree.html#comment +.. _compound: http://docutils.sourceforge.net/docs/ref/doctree.html#compound +.. _contact: http://docutils.sourceforge.net/docs/ref/doctree.html#contact +.. _container: http://docutils.sourceforge.net/docs/ref/doctree.html#container +.. _copyright: http://docutils.sourceforge.net/docs/ref/doctree.html#copyright +.. _danger: http://docutils.sourceforge.net/docs/ref/doctree.html#danger +.. _date: http://docutils.sourceforge.net/docs/ref/doctree.html#date + +.. _decoration: http://docutils.sourceforge.net/docs/ref/doctree.html#decoration +.. _definition: http://docutils.sourceforge.net/docs/ref/doctree.html#definition +.. _definition_list: http://docutils.sourceforge.net/docs/ref/doctree.html#definition-list +.. _definition_list_item: http://docutils.sourceforge.net/docs/ref/doctree.html#definition-list-item +.. _description: http://docutils.sourceforge.net/docs/ref/doctree.html#description +.. _docinfo: http://docutils.sourceforge.net/docs/ref/doctree.html#docinfo +.. _doctest_block: http://docutils.sourceforge.net/docs/ref/doctree.html#doctest-block +.. _document: http://docutils.sourceforge.net/docs/ref/doctree.html#document +.. _emphasis: http://docutils.sourceforge.net/docs/ref/doctree.html#emphasis + +.. _entry: http://docutils.sourceforge.net/docs/ref/doctree.html#entry +.. _enumerated_list: http://docutils.sourceforge.net/docs/ref/doctree.html#enumerated-list +.. _error: http://docutils.sourceforge.net/docs/ref/doctree.html#error +.. _field: http://docutils.sourceforge.net/docs/ref/doctree.html#field +.. _field_body: http://docutils.sourceforge.net/docs/ref/doctree.html#field-body +.. _field_list: http://docutils.sourceforge.net/docs/ref/doctree.html#field-list +.. _field_name: http://docutils.sourceforge.net/docs/ref/doctree.html#field-name +.. _figure: http://docutils.sourceforge.net/docs/ref/doctree.html#figure +.. _footer: http://docutils.sourceforge.net/docs/ref/doctree.html#footer + +.. _footnote: http://docutils.sourceforge.net/docs/ref/doctree.html#footnote +.. _footnote_reference: http://docutils.sourceforge.net/docs/ref/doctree.html#footnote-reference +.. _generated: http://docutils.sourceforge.net/docs/ref/doctree.html#generated +.. _header: http://docutils.sourceforge.net/docs/ref/doctree.html#header +.. _hint: http://docutils.sourceforge.net/docs/ref/doctree.html#hint +.. _image: http://docutils.sourceforge.net/docs/ref/doctree.html#image +.. _important: http://docutils.sourceforge.net/docs/ref/doctree.html#important +.. _inline: http://docutils.sourceforge.net/docs/ref/doctree.html#inline +.. _label: http://docutils.sourceforge.net/docs/ref/doctree.html#label + +.. _legend: http://docutils.sourceforge.net/docs/ref/doctree.html#legend +.. _line: http://docutils.sourceforge.net/docs/ref/doctree.html#line +.. _line_block: http://docutils.sourceforge.net/docs/ref/doctree.html#line-block +.. _list_item: http://docutils.sourceforge.net/docs/ref/doctree.html#list-item +.. _literal: http://docutils.sourceforge.net/docs/ref/doctree.html#literal +.. _literal_block: http://docutils.sourceforge.net/docs/ref/doctree.html#literal-block +.. _note: http://docutils.sourceforge.net/docs/ref/doctree.html#note +.. _option: http://docutils.sourceforge.net/docs/ref/doctree.html#option +.. _option_argument: http://docutils.sourceforge.net/docs/ref/doctree.html#option-argument + +.. _option_group: http://docutils.sourceforge.net/docs/ref/doctree.html#option-group +.. _option_list: http://docutils.sourceforge.net/docs/ref/doctree.html#option-list +.. _option_list_item: http://docutils.sourceforge.net/docs/ref/doctree.html#option-list-item +.. _option_string: http://docutils.sourceforge.net/docs/ref/doctree.html#option-string +.. _organization: http://docutils.sourceforge.net/docs/ref/doctree.html#organization +.. _paragraph: http://docutils.sourceforge.net/docs/ref/doctree.html#paragraph +.. _pending: http://docutils.sourceforge.net/docs/ref/doctree.html#pending +.. _problematic: http://docutils.sourceforge.net/docs/ref/doctree.html#problematic +.. _raw: http://docutils.sourceforge.net/docs/ref/doctree.html#raw + +.. _reference: http://docutils.sourceforge.net/docs/ref/doctree.html#reference +.. _revision: http://docutils.sourceforge.net/docs/ref/doctree.html#revision +.. _row: http://docutils.sourceforge.net/docs/ref/doctree.html#row +.. _rubric: http://docutils.sourceforge.net/docs/ref/doctree.html#rubric +.. _section: http://docutils.sourceforge.net/docs/ref/doctree.html#section +.. _sidebar: http://docutils.sourceforge.net/docs/ref/doctree.html#sidebar +.. _status: http://docutils.sourceforge.net/docs/ref/doctree.html#status +.. _strong: http://docutils.sourceforge.net/docs/ref/doctree.html#strong +.. _subscript: http://docutils.sourceforge.net/docs/ref/doctree.html#subscript + +.. _substitution_definition: http://docutils.sourceforge.net/docs/ref/doctree.html#substitution-definition +.. _substitution_reference: http://docutils.sourceforge.net/docs/ref/doctree.html#substitution-reference +.. _subtitle: http://docutils.sourceforge.net/docs/ref/doctree.html#subtitle +.. _superscript: http://docutils.sourceforge.net/docs/ref/doctree.html#superscript +.. _system_message: http://docutils.sourceforge.net/docs/ref/doctree.html#system-message +.. _table: http://docutils.sourceforge.net/docs/ref/doctree.html#table +.. _target: http://docutils.sourceforge.net/docs/ref/doctree.html#target +.. _tbody: http://docutils.sourceforge.net/docs/ref/doctree.html#tbody +.. _term: http://docutils.sourceforge.net/docs/ref/doctree.html#term + +.. _tgroup: http://docutils.sourceforge.net/docs/ref/doctree.html#tgroup +.. _thead: http://docutils.sourceforge.net/docs/ref/doctree.html#thead +.. _tip: http://docutils.sourceforge.net/docs/ref/doctree.html#tip +.. _title: http://docutils.sourceforge.net/docs/ref/doctree.html#title +.. _title_reference: http://docutils.sourceforge.net/docs/ref/doctree.html#title-reference +.. _topic: http://docutils.sourceforge.net/docs/ref/doctree.html#topic +.. _transition: http://docutils.sourceforge.net/docs/ref/doctree.html#transition +.. _version: http://docutils.sourceforge.net/docs/ref/doctree.html#version +.. _warning: http://docutils.sourceforge.net/docs/ref/doctree.html#warning + Index: jrst2/doc/fr/DiagrammeClass.png Index: jrst2/doc/fr/DiagrammeSequance.png Index: jrst2/doc/fr/docDeveloppeur.rst diff -u /dev/null jrst2/doc/fr/docDeveloppeur.rst:1.1 --- /dev/null Wed May 30 17:07:10 2007 +++ jrst2/doc/fr/docDeveloppeur.rst Wed May 30 17:07:05 2007 @@ -0,0 +1,92 @@ +========================= +Documentation développeur +========================= + +.. contents:: Sommaire + +Le diagramme de Class +===================== + +|classDiagramme| + +La Class **AdvancedReader** a pour fonction de faciliter la lecture du fichier RST grâce à différentes méthodes : + - String readLine() : renvoie une ligne + - String[] readLines(int nombresLigne) : renvoie un certain nombre de lignes + - Stringn[] readWhile(Pattern p) : renvoie les lignes tant qu'elles correspondent au pattern + +... + +La Class **JRSTLexer** utilise **AdvancedReader** pour construire un fichier XML, il va parcourir l'ensemble du document pour isoler les types de données, leurs paramètres et leurs contenus, donc rassembler toutes les informations utiles à la mise en forme du XML final. Il va commencer par l'entête du document (peekHeader(), peekDocInfo()) pour ensuite s'intéresser au corps (peekBody()). + +La Class **JRSTReader** utilise **JRSTLexer**, il interprète le XML qui lui est renvoyé pour construire le XML final. Celui-ci est conforme à la DTD définie par DocUtils_. Cette Class a parfois besoin de s'appeler elle même lorsque une partie du document doit être interprétée indépendamment du reste. Par exemple, s'il y a une liste dans une case d'un tableau, l'on extrait les informations de la case et on les interprètes, le contenu d'une admoniton (une note) doit lui aussi être considéré comme un document indépendant. Lorsque la génération est terminée, la Class compose le sommaire (composeContent()) puis s'occupe de toutes les spécificités « inline » (inline()), comme par exemple les mots en italique ou gras, les références, les footnotes... Tout ce qui peut apparaître à l'intérieur d'une ligne. + +La Class **reStructuredText** référence toutes les variables nécessaires à la génération du XML final. + +La Class **JRST** contient la méthode main(), elle gère les options, la lecture et l'écriture des fichiers. Elle lit le document, le parse grâce à la class **JRSTReader** puis applique le XSL désiré (si besoin) grâce à la class **JRSTGenerator**. + +Exemple d'utilisation +===================== + +L'on souhaite convertir le document rst (text.rst) suivant en html (text.html) : + +:: + + ===== + Titre + ===== + + :Author: Letellier Sylvain + + .. Attention:: texte à être réinterprété comme un fichier rst indépendant + +On utilise donc la commande suivante : + +:: + + JRST -t html -o text.html text.rst + +Ce diagramme de séquence décrit le fonctionnement du parseur tout au long de la génération : + +|sequanceDiagramme| + +La Classe JRSTGenerator, grace au fichier XSL rst2xhtml.xsl, renvoie le fichier html suivant:: + + + + + + + Titre + + +

Titre

+ + + + + + + + + +
author :Letellier Sylvain
+
+

attention :

+

+

texte à être réinterprété comme un fichier rst indépendant

+

+
+ + + +Qui affiche la page (un CSS à été ajouté pour la mise en forme) : + +.. topic:: Titre + + :Author: Letellier Sylvain + .. Attention:: texte à être réinterprété comme un fichier rst indépendant + + +.. _DocUtils: http://docutils.sourceforge.net/docs/ref/doctree.html +.. |classDiagramme| image:: DiagrammeClass.png +.. |sequanceDiagramme| image:: DiagrammeSequance.png \ No newline at end of file Index: jrst2/doc/fr/docExterne.rst diff -u /dev/null jrst2/doc/fr/docExterne.rst:1.1 --- /dev/null Wed May 30 17:07:10 2007 +++ jrst2/doc/fr/docExterne.rst Wed May 30 17:07:05 2007 @@ -0,0 +1,11 @@ +===================== +Documentation externe +===================== + +Le site de docUtils : http://docutils.sourceforge.net/rst.html + +La DTD reStructured text : http://docutils.sourceforge.net/docs/ref/doctree.html + +Un XSL permetant de convertir le XML en RST : http://www.merten-home.de/FreeSoftware/xml2rst/ + +Pour la génération de la javaDoc en RST : http://java.sun.com/j2se/1.3/docs/tooldocs/javadoc/overview.html \ No newline at end of file Index: jrst2/doc/fr/librairies.rst diff -u /dev/null jrst2/doc/fr/librairies.rst:1.1 --- /dev/null Wed May 30 17:07:11 2007 +++ jrst2/doc/fr/librairies.rst Wed May 30 17:07:05 2007 @@ -0,0 +1,30 @@ +==================================== +Les différentes librairies utilisées +==================================== + +.. contents:: Sommaire + +dom4j_ +====== + +Dom4j_ est une API Open Source Java permettant de travailler avec XML, XPath et XSLT. Cette bibliothèque est compatible avec les standards DOM, SAX et JAXP. + +javax.xml.transform_ +==================== + +Librairie permettant la transformation XSL. + +SDoc_ +===== + +SDoc_ fournit des composants Swing qui inclut la coloration syntaxique pour de nombreux langages. + +Xmlunit_ +======== + +Xmlunit_ permet de comparer deux fichiers XML pour mettre en évidences les différences. + +.. _dom4j: http://www.dom4j.org +.. _javax.xml.transform: http://java.sun.com/j2se/1.4.2/docs/api/javax/xml/transform/package-summary.html +.. _SDoc: http://sdoc.sourceforge.net/wiki/pmwiki.php +.. _Xmlunit: http://xmlunit.sourceforge.net/ \ No newline at end of file Index: jrst2/doc/fr/presentationRST.rst diff -u /dev/null jrst2/doc/fr/presentationRST.rst:1.1 --- /dev/null Wed May 30 17:07:11 2007 +++ jrst2/doc/fr/presentationRST.rst Wed May 30 17:07:05 2007 @@ -0,0 +1,368 @@ +Introduction à ReStructuredText +=============================== + +Document adaptée du document de Richard Jones : http://docutils.sourceforge.net/sandbox/wilk/french/quickstart-fr.html + +.. contents:: Sommaire + + +Ce texte contient des liens de la forme "(quickref__)". Ils sont +relatifs au manuel de référence utilisateur `Quick reStructuredText`_. +S'ils ne fonctionnent pas, référez vous au document `master quick +reference`_. + +__ http://docutils.sourceforge.net/docs/rst/quickref.html +.. _Quick reStructuredText: http://docutils.sourceforge.net/docs/rst/quickref.html +.. _master quick reference: http://docutils.sourceforge.net/docs/rst/quickref.html + + +Structure +--------- + +Pour commencer, il me semble que "Structured Text" n'est pas tout à fait la +bonne appellation. Nous devrions plutôt le nommer "Relaxed Text" qui contient +quelques schémas logiques. Ces schémas sont interprétés par un convertisseur +HTML pour produire "Very Structured Text" (un texte très structuré) qui pourra +être utilisé par un navigateur web. + +Le schéma le plus simple est le **paragraphe** (quickref__). +C'est un bloc de texte séparé par des lignes vides (une seule suffit). +Les paragraphes doivent avoir le même décalage -- c'est à dire des espaces +à gauche. Ces paragraphes produiront un texte décalé. Par exemple:: + + Ceci est un paragraphe. + Très court. + + Le texte de ce paragraphe sera décalé, + généralement utilisé pour des citations. + + En voilà un autre + +Le résultat donne : + + Ceci est un paragraphe. + Très court. + + Le texte de ce paragraphe sera décalé, + généralement utilisé pour des citations. + + En voilà un autre + +__ http://docutils.sourceforge.net/docs/rst/quickref.html#paragraphs + +Styles de texte +--------------- + +(quickref__) + +__ http://docutils.sourceforge.net/docs/rst/quickref.html#inline-markup + +Dans les paragraphes et le corps du texte, nous pouvons utiliser +des marqueurs pour *italique* avec "`` *italique* ``" ou **gras** +avec "`` **gras** ``". + +Notez qu'aucun traitement supplémentaire n'est apporté entre deux +doubles apostrophes inversées -- les astérisques, comme dans "`` * ``", +sont donc conservées en l'état. + +Si vous souhaitez utiliser un de ces caractères "spéciaux" dans +le texte, il n'y a généralement pas de problème -- reStructuredText +est assez malin. +Par exemple, cet astérisque ``*`` est traité correctement. Si vous +souhaitez par contre ``*``entourer un texte par des astérisques``*`` +**sans** qu'il soit en italique, il est nécessaire d'indiquer que +l'astérisque ne doit pas être interprété. Pour cela il suffit de placer +une barre oblique inversée juste avant lui, comme ça "``\*``" (quickref__), ou +en l'entourant de doubles apostrophes inversées (litteral), comme cela :: + + ``\*`` + +(``\*`` n'est pas implanté dans le JRST seul les `` fonctionnent) + + +__ http://docutils.sourceforge.net/docs/rst/quickref.html#escaping + +Listes +------ + +Il y a trois types de listes: **numérotées**, **avec puces** et +de **définitions**. Dans chaque cas, nous pouvons avoir autant +de paragraphes, sous-listes, etc. que l'on souhaite, tant que +le décalage à gauche est aligné sur la première ligne. + +Les listes doivent toujours démarrer un nouveau paragraphe +-- c'est à dire qu'il doit y avoir un saut de ligne juste avant. + +Listes **numérotées** (par des nombres, lettres, chiffres romains; +quickref__) + +__ http://docutils.sourceforge.net/docs/rst/quickref.html#enumerated-lists + + En démarrant une ligne avec un numéro ou une lettre suivie d'un + point ".", une parenthèse droite ")" ou entouré par des parenthèses + -- comme vous préférez. Toutes ces formes sont reconnues:: + + 1. nombres + + A. Lettres en majuscule + qui continue sur plusieurs ligne + + avec deux paragraphes et tout ! + + a. lettres minuscules + + 3. avec une sous-liste qui démarre à un nombre différent + 4. faites attention à garder une séquence de nombre correcte ! + + I. majuscules en chiffres romains + + i. minuscules en chiffres romains + + (1) des nombres à nouveau + + 1) et encore + + Le résultat (note : Tous les styles de listes ne sont pas toujours + supportés par tous les navigateurs, vous ne verrez donc pas forcément + les effets complets) : + + 1. nombres + + A. Lettres en majuscule + qui continue sur plusieurs ligne + + avec deux paragraphes et tout ! + + a. lettres minuscules + + 3. avec une sous-liste qui démarre à un nombre différent + 4. faites attention à garder une séquence de nombre correcte ! + + I. majuscules en chiffres romains + + i. minuscules en chiffres romains + + (1) des nombres à nouveau + + 1) et encore + +Listes **à puces** (quickref__) + +__ http://docutils.sourceforge.net/docs/rst/quickref.html#bullet-lists + + De la même manière que pour les listes numérotées, il faut démarrer + la première ligne avec une puce -- soit "-", "+" ou "*":: + + * une puce "*" + + - une sous-liste avec "-" + + + à nouveau une sous-liste + + - une autre option + + Le résultat: + + * une puce "*" + + - une sous-liste avec "-" + + + à nouveau une sous-liste + + - une autre option + +Les listes de **définitions** (quickref__) + +__ http://docutils.sourceforge.net/docs/rst/quickref.html#definition-lists + + Comme les deux autres, les listes de définitions consistent en un + terme et la définition de ce terme. Le format est le suivant:: + + Quoi + Les listes de définitions associent un terme avec une définition. + + *Comment* + Le terme est une phrase d'une ligne, et la définition est d'un + ou plusieurs paragraphes ou éléments, décalés par rapport au terme. + Les lignes vides ne sont pas autorisées entre le terme et la définition. + + Le résultat: + + Quoi + Les listes de définitions associent un terme avec une définition. + + *Comment* + Le terme est une phrase d'une ligne, et la définition est d'un + ou plusieurs paragraphes ou éléments, décalés par rapport au terme. + Les lignes vides ne sont pas autorisées entre le terme et la définition. + +Préformatage +------------ +(quickref__) + +__ http://docutils.sourceforge.net/docs/rst/quickref.html#literal-blocks + +Pour inclure un texte préformaté sans traitement +il suffit de terminer le paragraphe par "``::``". Le texte préformaté est +terminé lorsqu'une ligne retombe au niveau du décalage précédent. Par exemple:: + + Un exemple:: + + Espaces, nouvelles lignes, lignes vides, et toutes sortes de marqueurs + (comme *ceci* ou \cela) sont préservés dans les bloc préformatés. + + Regardez ici, je suis descendu d'un niveau. + (mais pas assez) + + Fin de l'exemple + +Le résultat: + + Un exemple:: + + Espaces, nouvelles lignes, lignes vides, et toutes sortes de marqueurs + (comme *ceci* ou \cela) sont préservés dans les bloc préformatés. + + Regardez ici, je suis descendu d'un niveau. + (mais pas assez) + + Fin de l'exemple + +Notez que si le paragraphe contient seulement "``::``", il est ignoré. + + :: + + Ceci est un texte préformaté, + le paragraphe "::" est ignoré. + +Sections +-------- +(quickref__) + +__ http://docutils.sourceforge.net/docs/rst/quickref.html#section-structure + +Pour diviser un texte en plusieurs sections, nous utilisons des +**en-têtes de section**. C'est à dire une seule ligne de texte (d'un +ou plusieurs mots) avec un ornement : juste en dessous et éventuellement +dessus aussi, avec des tirets "``-----``", égal "``=====``", tildes +"``~~~~~``" ou n'importe quel de ces caractères ``= - ` : ' " ~ ^ _ * + # < >`` +qui vous semble convenir. Un ornement simplement en dessous n'a pas la +même signification qu'un ornement dessus-dessous avec le même caractère. +Les ornements doivent avoir au moins la taille du texte. Soyez cohérent, +les ornements identiques sont censés être du même niveau:: + + Chapitre 1 + ========== + + Section 1.1 + ----------- + + Sous-section 1.1.1 + ~~~~~~~~~~~~~~~~~~ + + Section 1.2 + ----------- + + Chapitre 2 + ========== + +Le résultat de cette structure, sous la forme pseudo-XML:: + +
+ + Chapitre 1 + <section> + <title> + Section 1.1 + <section> + <title> + Sous-section 1.1.1 + <section> + <title> + Section 1.2 + <section> + <title> + Chapitre 2 + +(Pseudo-XML utilise une indentation et n'as pas de balises finale. Il +n'est pas possible de montrer le résultat, comme dans les autres exemples, +du fait que les sections ne peuvent être utilisées à l'intérieur d'un +paragraphe décalé. Pour un exemple concret, comparez la structure de +ce document avec le résultat.) + +Notez que les en-têtes de section sont utilisable comme cible de liens, +simplement en utilisant leur nom. Pour créer un lien sur la section Listes_, +j'écris "``Listes_``". Si le titre comporte des espaces, il est nécessaire +d'utiliser les doubles apostrophes inversées "```Styles de texte`_``". + +Pour indiquer le titre du document, utilisez un style d'ornement unique +en début de document. Pour indiquer un sous-titre de document, utilisez +un autre ornement unique juste après le titre. +Par exemple:: + + ================= + Titre du document + ================= + ---------- + Sous-titre + ---------- + + Titre de la section + =================== + + ... + +Notez que "Titre du document" et "Titre de la section" utilisent le signe +égal, mais sont différents et sans relation. Le texte et l'ornement peuvent +être de la même taille pour des questions d'esthétisme. + + +Images +------ +(quickref__) + +__ http://docutils.sourceforge.net/docs/rst/quickref.html#directives + +Pour inclure une image dans votre document, vous devez utiliser la directive__ +``image``. +Par exemple:: + + .. image:: images/biohazard.png + +Le résultat: + +.. image:: images/biohazard.png + +La partie ``images/biohazard.png`` indique le chemin d'accès au fichier +de l'image qui doit apparaître. Il n'y a pas de restriction sur l'image +(format, taille etc). Si l'image doit apparaître en HTML et que vous +souhaitez lui ajouter des informations:: + + .. image:: images/biohazard.png + :height: 100 + :width: 200 + :scale: 50 + :alt: texte alternatif + +Consultez la documentation__ complète de la directive image pour plus d'informations. + +__ http://docutils.sourceforge.net/spec/rst/directives.html +__ http://docutils.sourceforge.net/spec/rst/directives.html#images + + +Et ensuite ? +------------ + +Cette introduction montre les possibilités les plus courantes de reStructuredText, +mais il y en a bien d'autres à explorer. Le manuel de référence utilisateur +'Quick reStructuredText`_ est recommandé pour aller plus loin. Pour les détails complets +consultez `reStructuredText Markup Specification`_ [#]_. + + +.. [#] Si ce lien relatif ne fonctionne pas, consultez le document principal: + http://docutils.sourceforge.net/spec/rst/reStructuredText.html. + +.. _reStructuredText Markup Specification: http://docutils.sourceforge.net/spec/rst/reStructuredText.html +.. _poster un message: mailto:docutils-users@lists.sourceforge.net +.. _Docutils-Users mailing list: http://lists.sourceforge.net/lists/listinfo/docutils-users +.. _Docutils project web site: http://docutils.sourceforge.net/ Index: jrst2/doc/fr/presentationXSL.rst diff -u /dev/null jrst2/doc/fr/presentationXSL.rst:1.1 --- /dev/null Wed May 30 17:07:11 2007 +++ jrst2/doc/fr/presentationXSL.rst Wed May 30 17:07:05 2007 @@ -0,0 +1,146 @@ +======================================== +Le XSL (Extensible Stylesheets Language) +======================================== + +.. contents:: Sommaire + +Présentation +============ + +XML est un langage de structuration des données, et non de représentation des données. Ainsi XSL (eXtensible StyleSheet Language) est un langage recommandé par le W3C pour effectuer la représentation des données de documents XML. XSL est lui-même défini avec le formalisme XML, cela signifie qu'une feuille de style XSL est un document XML bien formé. + +XSL est un langage permettant de définir des feuilles de style pour les documents XML au même titre que les CSS (Cascading StyleSheets) pour le langage HTML ou bien DSSSL (Document Style Semantics and Specification Language) pour le SGML. XSL est d'ailleurs inspiré de DSSSL dont il reprend beaucoup de fonctionnalités et est compatible avec les CSS (il s'agit d'un sur-ensemble des CSS). + +Toutefois, contrairement aux CSS, XSL permet aussi de retraiter un document XML afin d'en modifier totalement sa structure, ce qui permet à partir d'un document XML d'être capable de générer d'autres types de documents (PostScript, HTML, Tex, RTF, ...) ou bien un fichier XML de structure différente. + +Ainsi la structuration des données (définie par XML) et leur représentation (définie par un langage tel que XSL) sont séparées. Cela signifie qu'il est possible à partir d'un document XML de créer des documents utilisant différentes représentations (HTML pour créer des pages web, WML pour les mobiles WAP, ...). + +|presentationxsl| + + +Structure d'un document XSL +=========================== + +Un document XSL étant un document XML, il commence obligatoirement par la balise suivante:: + + <?xml version="1.0" encoding="ISO-8859-1"?> + + +D'autre part, toute feuille de style XSL est comprise entre les balises <xsl:stylesheet ...> et </xsl:stylesheet>. + +La balise xsl:stylesheet encapsule des balises xsl:template définissant les transformations à faire subir à certains éléments du document XML. + +:: + + <?xml version="1.0" encoding="ISO-8859-1"?> + <xsl:stylesheet + xmlns:xsl="http://www.w3.org/TR/WD-xsl" + xmlns="http://www.w3.org/TR/REC-html40" + result-ns=""> + <xsl:template ... > + <!-- traitements à effectuer --> + </xsl:template > + </xsl:stylesheet> + + +Association d'une feuille XSL à un document XML +=============================================== + +Une feuille de style XSL (enregistré dans un fichier dont l'extension est .xsl) peut être liée à un document XML (de telle manière à ce que le document XML utilise la feuille XSL) en insérant la balise suivante au début du document XML:: + + <?xml version="1.0" encoding="ISO-8859-1"?> + <?xml-stylesheet href="fichier.xsl" type="text/xsl"?> + + +Les template rules (règles de gabarit) +====================================== + +Les template rules sont des balises XSL permettant de définir des opérations à réaliser sur certains éléments du document XML utilisant la page XSL, c'est-à-dire généralement de transformer un tag XML en au moins un tag HTML (généralement plusieurs). + +Ainsi le tag XML suivant:: + + <personne> + <nom>Pillou</nom> + <prenom>Jean-François</prenom> + </personne> + <personne> + <nom>VanHaute</nom> + <prenom>Nico</prenom> + </personne> + <personne> + <nom>Andrieu</nom> + <prenom>Seb</prenom> + </personne> + +pourra être transformé en les tags HTML suivants:: + + <ul> + <li>Pillou - Jean-François</li> + <li>VanHaute - Nico</li> + <li>Andrieu - Seb</li> + </ul> + +L'attribut "match" de la balise <xsl:template> permet de définir (grâce à la notation XPath) le ou les éléments du document XML sur lesquels s'applique la transformation. + +La notation Xpath permet de définir des patterns, c'est-à-dire des chaînes de caractères permettant de repérer un noeud dans le document XML. Les principaux patterns sont : + +======= ============= ================================================================= +Pattern Exemple Signification +======= ============= ================================================================= +``|`` Gauche|Milieu Indique une alternative (un noeud ou bien l'autre (ou les deux)) +/ personne/nom Chemin d'accès aux éléments (personne/bras/gauche) +* * Motif "joker" désignant n'importe quel élément +// //personne Indique tous les descendants d'un noeud +. . Caractérise le noeud courant +``..`` ``..`` Désigne le noeud parent +@ @valeur Indique un attribut caractéristique +======= ============= ================================================================= + +La transformation peut être réalisée : + +- soit par ajout de texte, +- soit en définissant des éléments de transformation, c'est-à-dire des éléments permettant de définir des règles de transformation à appliquer aux éléments sélectionnés par l'attribut match + +Voici un exemple de feuille XSL permettant d'effectuer la transformation XML vers HTML décrite ci-dessus:: + + <?xml version="1.0" encoding="ISO-8859-1"?> + <xsl:stylesheet + xmlns:xsl="http://www.w3.org/TR/WD-xsl" + xmlns="http://www.w3.org/TR/REC-html40" + result-ns=""> + <xsl:template match="/"> + <HTML> + <HEAD> + <TITLE>Titre de la page + + + + + + + +
    +
  • + + - + +
    • +
+ + + + +Voici la signification de cette feuille XSL + +* Le premier tag permet d'appliquer une transformation à l'ensemble du document (la valeur "/" de l'attribut match indique l'élément racine du document XML). Ce tag contient des balises HTML qui seront transmises dans l'arbre résultat +* L'élément indique le traitement de tous les enfants directs de la racine. +* La balise permet d'aller traiter les éléments de type personne +* Enfin les deux éléments et permettent de recuperer les valeurs des balises nom et prenom + +Références +========== + +- Article : http://www.commentcamarche.net/xml/xmlxsl.php3 +- Schéma : http://fr.wikipedia.org/wiki/Extended_stylesheet_language_transformations + +.. |presentationxsl| image:: presentationXSL.png \ No newline at end of file