GoalsThe primary goal of reStructuredText is to define a markup syntax for -use in Python docstrings and other documentation domains, that is -readable and simple, yet powerful enough for non-trivial use. The -intended purpose of the reStructuredText markup is twofold:the establishment of a set of standard conventions allowing the -expression of structure within plaintext, andthe conversion of such documents into useful structured data -formats.The secondary goal of reStructuredText is to be accepted by the Python -community (by way of being blessed by PythonLabs and the BDFL 1) as -a standard for Python inline documentation (possibly one of several -standards, to account for taste).1Python's creator and "Benevolent Dictator For Life", -Guido van Rossum.To clarify the primary goal, here are specific design goals, in order, -beginning with the most important:Readable. The marked-up text must be easy to read without any -prior knowledge of the markup language. It should be as easily -read in raw form as in processed form.Unobtrusive. The markup that is used should be as simple and -unobtrusive as possible. The simplicity of markup constructs -should be roughly proportional to their frequency of use. The most -common constructs, with natural and obvious markup, should be the -simplest and most unobtrusive. Less common constructs, for which -there is no natural or obvious markup, should be distinctive.Unambiguous. The rules for markup must not be open for -interpretation. For any given input, there should be one and only -one possible output (including error output).Unsurprising. Markup constructs should not cause unexpected output -upon processing. As a fallback, there must be a way to prevent -unwanted markup processing when a markup construct is used in a -non-markup context (for example, when documenting the markup syntax -itself).Intuitive. Markup should be as obvious and easily remembered as -possible, for the author as well as for the reader. Constructs -should take their cues from such naturally occurring sources as -plaintext email messages, newsgroup postings, and text -documentation such as README.txt files.Easy. It should be easy to mark up text using any ordinary text -editor.Scalable. The markup should be applicable regardless of the length -of the text.Powerful. The markup should provide enough constructs to produce a -reasonably rich structured document.Language-neutral. The markup should apply to multiple natural (as -well as artificial) languages, not only English.Extensible. The markup should provide a simple syntax and -interface for adding more complex general markup, and custom -markup.Output-format-neutral. The markup will be appropriate for -processing to multiple output formats, and will not be biased -toward any particular format.The design goals above were used as criteria for accepting or -rejecting syntax, or selecting between alternatives.It is emphatically not the goal of reStructuredText to define -docstring semantics, such as docstring contents or docstring length. -These issues are orthogonal to the markup syntax and beyond the scope -of this specification.Also, it is not the goal of reStructuredText to maintain compatibility -with StructuredText or Setext. reStructuredText shamelessly steals -their great ideas and ignores the not-so-great.Author's note:Due to the nature of the problem we're trying to solve (or, -perhaps, due to the nature of the proposed solution), the above -goals unavoidably conflict. I have tried to extract and distill -the wisdom accumulated over the years in the Python Doc-SIG -mailing list and elsewhere, to come up with a coherent and -consistent set of syntax rules, and the above goals by which to -measure them.There will inevitably be people who disagree with my particular -choices. Some desire finer control over their markup, others -prefer less. Some are concerned with very short docstrings, -others with full-length documents. This specification is an -effort to provide a reasonably rich set of markup constructs in a -reasonably simple form, that should satisfy a reasonably large -group of reasonable people.David Goodger (goodger@python.org), 2001-04-20

HistoryreStructuredText, the specification, is based on StructuredText and -Setext. StructuredText was developed by Jim Fulton of Zope -Corporation (formerly Digital Creations) and first released in 1996. -It is now released as a part of the open-source "Z Object Publishing -Environment" (ZOPE). Ian Feldman's and Tony Sanders' earlier Setext -specification was either an influence on StructuredText or, by their -similarities, at least evidence of the correctness of this approach.I discovered StructuredText in late 1999 while searching for a way to -document the Python modules in one of my projects. Version 1.1 of -StructuredText was included in Daniel Larsson's pythondoc. Although -I was not able to get pythondoc to work for me, I found StructuredText -to be almost ideal for my needs. I joined the Python Doc-SIG -(Documentation Special Interest Group) mailing list and found an -ongoing discussion of the shortcomings of the StructuredText -"standard". This discussion has been going on since the inception of -the mailing list in 1996, and possibly predates it.I decided to modify the original module with my own extensions and -some suggested by the Doc-SIG members. I soon realized that the -module was not written with extension in mind, so I embarked upon a -general reworking, including adapting it to the "re" regular -expression module (the original inspiration for the name of this -project). Soon after I completed the modifications, I discovered that -StructuredText.py was up to version 1.23 in the ZOPE distribution. -Implementing the new syntax extensions from version 1.23 proved to be -an exercise in frustration, as the complexity of the module had become -overwhelming.In 2000, development on StructuredTextNG ("Next Generation") began at -Zope Corporation (then Digital Creations). It seems to have many -improvements, but still suffers from many of the problems of classic -StructuredText.I decided that a complete rewrite was in order, and even started a -reStructuredText SourceForge project (now inactive). My -motivations (the "itches" I aim to "scratch") are as follows:I need a standard format for inline documentation of the programs I -write. This inline documentation has to be convertible to other -useful formats, such as HTML. I believe many others have the same -need.I believe in the Setext/StructuredText idea and want to help -formalize the standard. However, I feel the current specifications -and implementations have flaws that desperately need fixing.reStructuredText could form part of the foundation for a -documentation extraction and processing system, greatly benefitting -Python. But it is only a part, not the whole. reStructuredText is -a markup language specification and a reference parser -implementation, but it does not aspire to be the entire system. I -don't want reStructuredText or a hypothetical Python documentation -processor to die stillborn because of over-ambition.Most of all, I want to help ease the documentation chore, the bane -of many a programmer.Unfortunately I was sidetracked and stopped working on this project. -In November 2000 I made the time to enumerate the problems of -StructuredText and possible solutions, and complete the first draft of -a specification. This first draft was posted to the Doc-SIG in three -parts:A Plan for Structured TextProblems With StructuredTextreStructuredText: Revised Structured Text SpecificationIn March 2001 a flurry of activity on the Doc-SIG spurred me to -further revise and refine my specification, the result of which you -are now reading. An offshoot of the reStructuredText project has been -the realization that a single markup scheme, no matter how well -thought out, may not be enough. In order to tame the endless debates -on Doc-SIG, a flexible Docstring Processing System framework needed -to be constructed. This framework has become the more important of -the two projects; reStructuredText has found its place as one -possible choice for a single component of the larger framework.The project web site and the first project release were rolled out in -June 2001, including posting the second draft of the spec 2 -and the first draft of PEPs 256, 257, and 258 3 to the -Doc-SIG. These documents and the project implementation proceeded to -evolve at a rapid pace. Implementation history details can be found -in the project history file.In November 2001, the reStructuredText parser was nearing completion. -Development of the parser continued with the addition of small -convenience features, improvements to the syntax, the filling in of -gaps, and bug fixes. After a long holiday break, in early 2002 most -development moved over to the other Docutils components, the -"Readers", "Writers", and "Transforms". A "standalone" reader -(processes standalone text file documents) was completed in February, -and a basic HTML writer (producing HTML 4.01, using CSS-1) was -completed in early March.PEP 287, "reStructuredText Standard Docstring Format", was created -to formally propose reStructuredText as a standard format for Python -docstrings, PEPs, and other files. It was first posted to -comp.lang.python and the Python-dev mailing list on 2002-04-02.Version 0.4 of the reStructuredText and Docstring Processing -System projects were released in April 2002. The two projects were -immediately merged, renamed to "Docutils", and a 0.1 release soon -followed.2The second draft of the spec:An Introduction to reStructuredTextProblems With StructuredTextreStructuredText Markup SpecificationPython Extensions to the reStructuredText Markup Specification3First drafts of the PEPs:PEP 256: Docstring Processing System FrameworkPEP 258: DPS Generic Implementation DetailsPEP 257: Docstring ConventionsCurrent working versions of the PEPs can be found in -http://docutils.sourceforge.net/docs/peps/, and official versions -can be found in the master PEP repository.Local Variables: -mode: indented-text -indent-tabs-mode: nil -sentence-end-double-space: t -fill-column: 70 -End:

<generated class="sectnum">1 </generated>Documentation utilisateur

<generated class="sectnum">1.1 </generated>PrésentationLe format reStructuredText est un format de description de documents. A l'image +d'autres LaTeX ou DocBook, il peut être décliné en une multitude de formats. Ces +formats souffrent habituellement d'une syntaxe envahissante qui, si elle est +nécessaire pour des documents très spécifiques, devient gênante quand il s'agit +de créer rapidement un document pas trop complexe. RST dispose quant à lui d'une +syntaxe tellement simple qu'elle en devient presque invisible.JRST est un parseur RST en Java permettant de créer une représentation en arbre +d'un document. Il devient alors facile de générer une représentation du document +vers différents formats.

<generated class="sectnum">1.2 </generated>UsageLe parser JRST prend un fichier reStructuredText en entré et génère un fichier XML qui pourra ensuite servir à produire divers formats de fichiers grâce à des fichiers XSL de générations. Les formats de sortie disponibles sont le html, le xhtml, le rst, le pdf, le docbook, le odt (Open-Office), le rtf, ou encore le XML.JRST myfile.rstCette commande aura pour effet de convertir le fichier myfile.rst en XML qui sera affiché sur la sortie standard (console). +Plusieurs options sont disponibles :pour rediriger la sortie vers un fichier.pour préciser un format de sortie, donc utiliser un fichier XSL de génération. Plusieurs formats sont disponibles xhtml, docbook, xml, html, xdoc, rst, pdf, odt, rtf.sert à préciser le fichier xsl de génération à utiliser.forcer l'écriture d'un fichier, si le fichier de sortie existe, il sera remplacé.pour afficher les options disponibles :Usage: [options] FILE + [--force] : overwrite existing out file + [--help] : display this help and exit + [--outFile -o value] : Output file + [--outType -t /xhtml|docbook|xml|html|xdoc|rst/] : Output type + [--xslFile -x value] : XSL file list to apply, comma separatedex :JRST --force -t html -o myfile.html myfile.rstCette commande produira un fichier html (myfile.html) à partir du fichier reStructuredText (myfile.rst) même si myfile.html existe déjà.

<generated class="sectnum">1.3 </generated>Plugin mavenUn plugin maven est disponnible à l'adresse suivante +http://jrst.labs.libre-entreprise.org/maven-jrst-plugin. Il permet l'utilisation +depuis maven de JRst.

<generated class="sectnum">2 </generated>Introduction à ReStructuredTextDocument adaptée du document de Richard Jones : http://docutils.sourceforge.net/sandbox/wilk/french/quickstart-fr.htmlCe 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.

<generated class="sectnum">2.1 </generated>StructurePour 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 autreLe 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

<generated class="sectnum">2.2 </generated>Styles de texte(quickref)Dans les paragraphes et le corps du texte, nous pouvons utiliser +des marqueurs pour italique avec "`` italique " ou **gras** +avec " gras ``".Inline literal start-string without end-string.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.Inline literal start-string without end-string.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)

<generated class="sectnum">2.3 </generated>ListesIl 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)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 encoreLe 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) :nombresLettres en majuscule +qui continue sur plusieurs ligneavec deux paragraphes et tout !lettres minusculesavec une sous-liste qui démarre à un nombre différentfaites attention à garder une séquence de nombre correcte !majuscules en chiffres romainsminuscules en chiffres romainsdes nombres à nouveauet encoreListes à puces (quickref)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 optionLe résultat:une puce "*"une sous-liste avec "-"à nouveau une sous-listeune autre optionLes listes de définitions (quickref)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:QuoiLes listes de définitions associent un terme avec une définition.CommentLe 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.

<generated class="sectnum">2.4 </generated>Préformatage(quickref)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'exempleLe 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'exempleNotez que si le paragraphe contient seulement "::", il est ignoré.Ceci est un texte préformaté, +le paragraphe "::" est ignoré.

<generated class="sectnum">2.5 </generated>Sections(quickref)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:<section> + <title> + 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.

<generated class="sectnum">2.6 </generated>Images(quickref)Pour inclure une image dans votre document, vous devez utiliser la directive +image. +Par exemple:.. image:: biohazard.pngLe résultat: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:: biohazard.png + :height: 100 + :width: 200 + :scale: 50 + :alt: texte alternatifConsultez la documentation complète de la directive image pour plus d'informations.

<generated class="sectnum">2.7 </generated>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 1.1Si ce lien relatif ne fonctionne pas, consultez le document principal: +http://docutils.sourceforge.net/spec/rst/reStructuredText.html.

<generated class="sectnum">3 </generated>Le XSL (Extensible Stylesheets Language)

<generated class="sectnum">3.1 </generated>PrésentationXML 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

<generated class="sectnum">3.2 </generated>Structure d'un document XSLUn 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 ... > +  + </xsl:template > +</xsl:stylesheet>

<generated class="sectnum">3.3 </generated>Association d'une feuille XSL à un document XMLUne 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"?>

<generated class="sectnum">3.4 </generated>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 :PatternExempleSignification|Gauche|MilieuIndique une alternative (un noeud ou bien l'autre (ou les deux))/personne/nomChemin d'accès aux éléments (personne/bras/gauche)Motif "joker" désignant n'importe quel élément////personneIndique tous les descendants d'un noeud..Caractérise le noeud courant....Désigne le noeud parent@@valeurIndique 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 matchVoici 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</TITLE> + </HEAD> + <BODY BGCOLOR="#FFFFFF"> + <xsl:apply-templates/> + </BODY> + </HTML> + </xsl:template > + <xsl:template match="personne" > + <ul> + <li> + <xsl:value-of select="nom"/> + - + <xsl:value-of select="prenom"/> + </li> + </ul> + </xsl:template > +</xsl:stylesheet>Voici la signification de cette feuille XSL :Le premier tag <xsl:template> 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 <xsl:apply-templates/> indique le traitement de tous les enfants directs de la racine.La balise <xsl:template match="personne"> permet d'aller traiter les éléments de type personne.Enfin les deux éléments <xsl:value-of select="nom"/> et <xsl:value-of select="prenom"/> permettent de +recuperer les valeurs des balises nom et prenom.

<generated class="sectnum">3.5 </generated>RéférencesArticle : http://www.commentcamarche.net/xml/xmlxsl.php3Schéma : http://fr.wikipedia.org/wiki/Extended_stylesheet_language_transformations presentationxsl

<generated class="sectnum">4 </generated>Documentation développeur

<generated class="sectnum">4.1 </generated>Le diagramme de Class classDiagramme

La Class AdvancedReader à pour fonction de faciliter la lecture du fichier RST grâce à différentes méthodes :String readLine() : renvoie une ligneString[] readLines(int nombresLigne) : renvoie un certain nombre de lignesStringn[] readWhile(Pattern p) : renvoie les lignes tant qu'elles correspondent au pattern...La Class JRSTLexer utilise AdvancedReader pour construire un fichier XML, il parcours 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 à 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.

<generated class="sectnum">4.2 </generated>La génération diagrammegeneration

Référence :xml2rst.xsl (convertion de xml de docutils vers rst) : http://www.merten-home.de/FreeSoftware/xml2rstdn2dbk.xsl (convertion de xml de docutils vers docbook) : http://membres.lycos.fr/ebellot/dn2dbkles xsl de nwalsh (convertion de docbook vers FO et xhtml) : http://nwalsh.comXMLmind (convertion de FO vers ODT et RTF) : http://www.xmlmind.com/foconverter/what_is_xfc.htmlFOP (convertion de FO vers PDF) : http://xmlgraphics.apache.org/fop

<generated class="sectnum">4.3 </generated>Exemple d'utilisationL'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épendantOn utilise donc la commande suivante:JRST -t html -o text.html text.rstCe diagramme de séquence décrit le fonctionnement du parseur tout au long de la génération : sequanceDiagramme

La Classe JRSTGenerator, grâce au fichier XSL rst2xhtml.xsl, renvoie le fichier html suivant:<?xml version="1.0" encoding="UTF-8"?> +<html xmlns="http://www.w3.org/TR/xhtml1/strict"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/> + <meta name="generator" content="JRST http://jrst.labs.libre-entreprise.org/"/> + <title>Titre</title> + </head> + <body> + <h1>Titre</h1> + <table class="docinfo" frame="void" rules="none"> + <col class="docinfo-name"/> + <col class="docinfo-content"/> + <tbody valign="top"> + <tr> + <th class="docpatterninfo-name">author :</th> + <td class="docinfo-content">Letellier Sylvain</td> + </tr> + </tbody> + </table> + <div class="attention"> + <p class="title">attention :</p> + <p class="body"> + <p>texte à être réinterprété comme un fichier rst indépendant</p> + </p> + </div> + </body> +</html>Qui affiche la page (un CSS à été ajouté pour la mise en forme) :TitreAuthorLetellier SylvainField list ends without a blank line; unexpected unindent.texte à être réinterprété comme un fichier rst indépendant diagrammegeneration

<generated class="sectnum">5 </generated>Fonctionnalités proposéesLa DTD de Docutils : http://docutils.sourceforge.net/docs/ref/doctree.html

<generated class="sectnum">5.1 </generated>Fonctionnalités implantées

<generated class="sectnum">5.1.1 </generated>Element racinedocument

<generated class="sectnum">5.1.2 </generated>Elements titresubtitletitle

<generated class="sectnum">5.1.3 </generated>Elements bibliographiquesdocinfoauthorauthorsorganizationaddresscontactversionrevisionstatusdatecopyright

<generated class="sectnum">5.1.4 </generated>Elements de décorationdecorationfooterheader

<generated class="sectnum">5.1.5 </generated>Elements structurelssectiontopicsidebartransition

<generated class="sectnum">5.1.6 </generated>Elements du corpsadmonitionattentionblock_quotebullet_listcautionclassifierdangerdefinitiondefinition_listdefinition_list_itemdescriptiondoctest_blockenumerated_listerrorfieldfield_bodyfield_listfield_namefootnotehintimageimportantlineline_blocklist_itemliteral_blocknoteoptionoption_argumentoption_groupoption_listoption_list_itemoption_stringparagraphtermtipwarning

<generated class="sectnum">5.1.7 </generated>Elements des tableauxtabletbodyentryrowcolspectheadtgroup

<generated class="sectnum">5.1.8 </generated>Elements de la ligneemphasisstrongliteralreferencefootnote_reference

<generated class="sectnum">5.2 </generated>Fonctionnalités non-implantéesabbreviationacronymattributioncaptioncitationcitation_referencecommentcompoundcontainerfiguregeneratedinlinelabellegendpendingproblematicrawrubricsubscriptsubstitution_definitionsubstitution_referencesuperscriptsystem_messagetargettitle_reference

<generated class="sectnum">6 </generated>Les différentes librairies utilisées

<generated class="sectnum">6.1 </generated><reference name="dom4j" refuri="http://www.dom4j.org">dom4j</reference>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.

<generated class="sectnum">6.2 </generated><reference name="javax.xml.transform" refuri="http://java.sun.com/j2se/1.4.2/docs/api/javax/xml/transform/package-summary.html">javax.xml.transform</reference>Librairie permettant la transformation XSL.

<generated class="sectnum">6.3 </generated><reference name="SDoc" refuri="http://sdoc.sourceforge.net/wiki/pmwiki.php">SDoc</reference>SDoc fournit des composants Swing qui inclut la coloration syntaxique pour de nombreux langages.

<generated class="sectnum">6.4 </generated><reference name="Xmlunit" refuri="http://xmlunit.sourceforge.net/">Xmlunit</reference>Xmlunit permet de comparer deux fichiers XML pour mettre en évidences les différences.

<generated class="sectnum">7 </generated>Documentation externeLe site de docUtils : http://docutils.sourceforge.net/rst.htmlLa DTD reStructuredText : http://docutils.sourceforge.net/docs/ref/doctree.htmlUn XSL permettant 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... footer:: view code source

+ + 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:: biohazard.png + +Le r�sultat: + +.. image:: 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:: 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/ + + +Le XSL (Extensible Stylesheets Language) +======================================== + + +Pr�sentation du XSL +------------------- + +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 ... > +  + </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 + +Documentation d�veloppeur +========================= + +Le diagramme de Class +--------------------- + +|classDiagramme| + +La Class **AdvancedReader** � 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 parcours 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 � 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**. + +La g�n�ration +------------- + +|diagrammegeneration| + +R�f�rences : + +- xml2rst.xsl (convertion de xml de docutils vers rst) : http://www.merten-home.de/FreeSoftware/xml2rst +- dn2dbk.xsl (convertion de xml de docutils vers docbook) : http://membres.lycos.fr/ebellot/dn2dbk +- les xsl de nwalsh (convertion de docbook vers FO et xhtml) : http://nwalsh.com + +- XMLmind (convertion de FO vers ODT et RTF) : http://www.xmlmind.com/foconverter/what_is_xfc.html +- FOP (convertion de FO vers PDF) : http://xmlgraphics.apache.org/fop + +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**, gr�ce 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 +.. |diagrammegeneration| image:: DiagrammeGeneration.png +.. |classDiagramme| image:: DiagrammeClass.png +.. |sequanceDiagramme| image:: DiagrammeSequance.png + +Les diff�rentes librairies utilis�es +------------------------------------ + + +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/ + +Fonctionnalit�s propos�es +========================= + +La DTD de Docutils : http://docutils.sourceforge.net/docs/ref/doctree.html + + +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 + + +Documentation externe +===================== + +Le site de docUtils : http://docutils.sourceforge.net/rst.html + +La DTD reStructuredText : http://docutils.sourceforge.net/docs/ref/doctree.html + +Un XSL permettant 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 + +.. footer:: Afficher le `code source`__ + +__ frEntier.rst