Index: jrst2/src/site/fr/rst/user/presentationRST.rst diff -u /dev/null jrst2/src/site/fr/rst/user/presentationRST.rst:1.1 --- /dev/null Tue Jun 5 15:52:19 2007 +++ jrst2/src/site/fr/rst/user/presentationRST.rst Tue Jun 5 15:52:14 2007 @@ -0,0 +1,363 @@ +=============================== +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. + + 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. + + 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/src/site/fr/rst/user/index.rst diff -u /dev/null jrst2/src/site/fr/rst/user/index.rst:1.1 --- /dev/null Tue Jun 5 15:52:19 2007 +++ jrst2/src/site/fr/rst/user/index.rst Tue Jun 5 15:52:14 2007 @@ -0,0 +1,69 @@ +================================== +Parseur reStructuredText : le JRst +================================== + +Documentation utilisateur +========================= + +.. contents:: Sommaire + + +Présentation +------------ + +Le 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. + + +Usage +----- + +Le 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.rst + +Cette commande aura pour effet de convertir le fichier myfile.rst en XML qui sera affiché sur la sortie standard (console). +Plusieurs options sont disponibles : + +-o file, --outFile=file pour rediriger la sortie vers un fichier. +-t format, --outType format 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. +-x xslFile, --xslFile xslFile sert à préciser le fichier xsl de génération à utiliser. +--force forcer l'écriture d'un fichier, si le fichier de sortie existe, il sera remplacé. +--help 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 separated + + +ex : + +:: + + JRST --force -t html -o myfile.html myfile.rst + +Cette commande produira un fichier html (myfile.html) à partir du fichier reStructuredText (myfile.rst) même si myfile.html existe déjà. + + +Plugin maven +------------ + +Un plugin maven est disponnible à l'adresse suivante +http://jrst.labs.libre-entreprise.org/maven-jrst-plugin. Il permet l'utilisation +depuis maven de JRst. Index: jrst2/src/site/fr/rst/user/fonctionnalites.rst diff -u /dev/null jrst2/src/site/fr/rst/user/fonctionnalites.rst:1.1 --- /dev/null Tue Jun 5 15:52:22 2007 +++ jrst2/src/site/fr/rst/user/fonctionnalites.rst Tue Jun 5 15:52:14 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 +