Author: kcardineaud Date: 2011-05-19 11:51:39 +0200 (Thu, 19 May 2011) New Revision: 586 Url: http://nuiton.org/repositories/revision/jrst/586 Log: Ajout d'une fonction permettant de comparer les resultats de l'execution de jrst et docutils Added: trunk/jrst/src/test/java/org/nuiton/jrst/JRSTCompareDocutils.java trunk/jrst/src/test/resources/FilesTest/ trunk/jrst/src/test/resources/FilesTest/index.txt trunk/jrst/src/test/resources/FilesTest/roles.txt trunk/jrst/src/test/resources/FilesTest/rstTest.rst Added: trunk/jrst/src/test/java/org/nuiton/jrst/JRSTCompareDocutils.java =================================================================== --- trunk/jrst/src/test/java/org/nuiton/jrst/JRSTCompareDocutils.java (rev 0) +++ trunk/jrst/src/test/java/org/nuiton/jrst/JRSTCompareDocutils.java 2011-05-19 09:51:39 UTC (rev 586) @@ -0,0 +1,325 @@ +package org.nuiton.jrst; + +import java.io.File; +import java.io.IOException; +import java.io.InputStreamReader; +import java.io.Reader; +import java.io.StringReader; +import java.io.StringWriter; +import java.net.URL; +import java.util.Iterator; +import java.util.LinkedList; +import java.util.List; +import java.util.Locale; + +import javax.xml.transform.TransformerException; + +import junit.framework.Assert; + +import org.apache.commons.logging.Log; +import org.apache.commons.logging.LogFactory; +import org.custommonkey.xmlunit.DetailedDiff; +import org.custommonkey.xmlunit.Diff; +import org.custommonkey.xmlunit.DifferenceListener; + +import org.custommonkey.xmlunit.IgnoreTextAndAttributeValuesDifferenceListener; +import org.dom4j.Document; +import org.dom4j.DocumentException; +import org.dom4j.io.SAXReader; +import org.dom4j.io.XMLWriter; +import org.junit.Ignore; +import org.junit.Test; +import org.nuiton.i18n.I18n; +import org.nuiton.i18n.init.ClassPathI18nInitializer; +import org.nuiton.util.FileUtil; + + + + + +public class JRSTCompareDocutils { + + /** to use log facility, just put in your code: log.info(\"...\"); */ + private static Log log = LogFactory.getLog(JRSTCompareDocutils.class); + + /** Commande utilisee pour transformer le rst en xml */ + private static String rst2xml = "rst2xml"; + + /** Commande utilisee pour transformer le rst en html */ + private static String rst2html = "rst2html"; + + + public static void main(String[] args) throws Exception { + + I18n.init(new ClassPathI18nInitializer(), Locale.UK); + + JRSTCompareDocutils jT = new JRSTCompareDocutils(); + + File rep = null; + if (args.length > 0) { + rep = new File(args[0]); + jT.runCompare(rep); + } + else { + jT.runCompare(new File("src/test/resources/FilesTest/")); + } + + } + + + /** + * + * @param rep + * @throws Exception + */ + public void runCompare(File rep) throws Exception { + + if(testIfDocutils()) { + //File rep = new File("src/test/resources/FilesTest/"); + + LinkedList<File> rstFilesTests = new LinkedList<File>(); + + //1. recuperation des fichiers de test directement dans le repertoire des fichiers rst + rstFilesTests.addAll(FileUtil.getFiles(rep)); + + //2. boucle sur les fichiers de test + Iterator<File> iteFiles = rstFilesTests.iterator(); + + File testFile; + + + String res=""; + + while(iteFiles.hasNext()) { + testFile = iteFiles.next(); + log.debug("fichier test : "+testFile.getName()); + res+="\nFichier test: "+testFile.getName(); + + //Compare XML + if (compareXML(getXMLJrst(testFile),getDocPython(testFile,rst2xml))) { + res+="\tXML->OK\n"; + } + else { + res+="\n\tXML->KO\n"; + } + + //Compare HTML + if (compareHTML(testFile)) { + res+="\tHTML->OK\n"; + } + else { + res+="\tHTML->KO\n"; + } + + //Compare RST + if (compareRST(testFile)) { + res+="\tRST->OK\n"; + } + else { + res+="\tRST->KO\n"; + } + log.debug("=========================================================="); + } + + log.info(res); + } + Assert.assertTrue(true); + } + + + /** + * + * @param compare + * @param base + * @return + * @throws Exception + */ + private boolean compareXML(Document compare, Document base) throws Exception { + + Document docRst = compare; // JRST + + Document docPython = base; // docutils + + + XMLCaseTest test = new XMLCaseTest("testXML"); + DetailedDiff myDiff = test.testAllDifferences(docPython.asXML(), docRst.asXML()); + List<?> allDifferences = myDiff.getAllDifferences(); + + + log.debug("Nombre de difference XML: "+allDifferences.size()); + + + + return myDiff.similar(); + + } + + + /** + * + * @param testFile + * @return + * @throws Exception + */ + private boolean compareHTML(File testFile) throws Exception { + + String htmlJRST = getHTMLJrst(testFile); + + Document htmlPython = getDocPython(testFile,rst2html); + + String BadlyFormedJRST2HTML = htmlJRST; + + String BadlyFormedPython2HTML = toWriter(htmlPython).toString(); + + DifferenceListener myDifferenceListener = new IgnoreTextAndAttributeValuesDifferenceListener(); + + Diff myDiff = new Diff(BadlyFormedJRST2HTML, BadlyFormedPython2HTML); + + myDiff.overrideDifferenceListener(myDifferenceListener); + + return myDiff.similar(); + } + + + /** + * + * @param testFile + * @return + * @throws Exception + */ + private boolean compareRST(File testFile) throws Exception { + + //recuperation du XML cree depuis le RST avec JRST + Document rst2xml = getXMLJrst(testFile); + + //recuperation du rst genere depuis le xml + String rst2rst = getRSTJrst(testFile); + + JRSTReader jrst = new JRSTReader(); + + Document rst2rst2xml = jrst.read(new StringReader(rst2rst)); // JRST + + return compareXML(rst2xml, rst2rst2xml); + //return true; + + } + + + /** + * Permet de recuperer le fichier XML genere par JRST + * @param source + * @return Document le xml genere + * @throws Exception + */ + private Document getXMLJrst(File source) throws Exception { + URL url = source.toURI().toURL(); + Reader in = new InputStreamReader(url.openStream()); + + JRSTReader jrst = new JRSTReader(); + + return jrst.read(in); // JRST + + } + + /** + * + * @param source + * @return + * @throws Exception + */ + private String getHTMLJrst(File source) throws Exception { + + URL url = source.toURI().toURL(); + Reader reader = new InputStreamReader(url.openStream(), JRST.UTF_8); + + + return JRST.generate(JRST.TYPE_HTML,reader); + } + + /** + * + * @param source + * @return + * @throws Exception + */ + private String getRSTJrst(File source) throws Exception { + + URL url = source.toURI().toURL(); + Reader reader = new InputStreamReader(url.openStream(), JRST.UTF_8); + + return JRST.generate(JRST.TYPE_RST,reader); + } + + + /** + * Permet de recuperer le fichier genere par docutils en specifiant son type + * @param source + * @return Document le xml genere + * @throws IOException + * @throws TransformerException + * @throws Exception + */ + private Document getDocPython(File source, String action) throws DocumentException, InterruptedException, TransformerException, IOException { + + ProcessBuilder processBuilder = new ProcessBuilder(action, source.getPath()); + processBuilder.redirectErrorStream(true); + Process p = processBuilder.start(); + + ThreadRedirection t = new ThreadRedirection(p); + t.start(); + p.waitFor(); + t.join(); + //On attend que le processus ce termine + //t.stop(); + p.destroy(); + + + SAXReader sr = new SAXReader(false); + + return sr.read(new StringReader(t.getOutput())); + + } + + + private static boolean testIfDocutils() { + + File file = new File("src/test/resources/docutilsFilesTest/rstTest.rst"); + + ProcessBuilder processBuilder = new ProcessBuilder(rst2xml, file.getPath()); + processBuilder.redirectErrorStream(true); + @SuppressWarnings("unused") + Process p =null; + + try { + p = processBuilder.start(); + } + catch(IOException ioe) { + rst2xml="rst2xml.py"; + rst2html="rst2html.py"; + processBuilder = new ProcessBuilder(rst2xml, file.getPath()); + try { + p = processBuilder.start(); + } catch (IOException e) { + log.warn("You must install python-docutils to compare rst files"); + return false; + } + } + p.destroy(); + return true; + + } + + + + private static StringWriter toWriter(org.dom4j.Document dom4jdoc) throws TransformerException, IOException { + + StringWriter writer = new StringWriter(); + XMLWriter xmlWriter = new XMLWriter(writer); + + xmlWriter.write(dom4jdoc); + return writer; + } + + + +} Added: trunk/jrst/src/test/resources/FilesTest/index.txt =================================================================== --- trunk/jrst/src/test/resources/FilesTest/index.txt (rev 0) +++ trunk/jrst/src/test/resources/FilesTest/index.txt 2011-05-19 09:51:39 UTC (rev 586) @@ -0,0 +1,238 @@ +========================================== + Docutils_ Project Documentation Overview +========================================== + +:Author: David Goodger +:Contact: goodger@python.org +:Date: $Date: 2008-12-26 17:36:46 -0500 (Fri, 26 Dec 2008) $ +:Revision: $Revision: 5834 $ +:Copyright: This document has been placed in the public domain. + +The latest working documents may be accessed individually below, or +from the ``docs`` directory of the `Docutils distribution`_. + +.. _Docutils: http://docutils.sourceforge.net/ +.. _Docutils distribution: http://docutils.sourceforge.net/#download + +.. contents:: + + +Docutils Stakeholders +===================== + +Docutils stakeholders can be categorized in several groups: + +1. End-users: users of reStructuredText and the Docutils tools. + Although some are developers (e.g. Python developers utilizing + reStructuredText for docstrings in their source), many are not. + +2. Client-developers: developers using Docutils as a library, + programmers developing *with* Docutils. + +3. Component-developers: those who implement application-specific + components, directives, and/or roles, separately from Docutils. + +4. Core-developers: developers of the Docutils codebase and + participants in the Docutils project community. + +5. Re-implementers: developers of alternate implementations of + Docutils. + +There's a lot of overlap between these groups. Most (perhaps all) +core-developers, component-developers, client-developers, and +re-implementers are also end-users. Core-developers are also +client-developers, and may also be component-developers in other +projects. Component-developers are also client-developers. + + +Project Fundamentals +==================== + +These files are for all Docutils stakeholders. They are kept at the +top level of the Docutils project directory. + +:README.txt_: Project overview: quick-start, requirements, + installation, and usage. +:COPYING.txt_: Conditions for Docutils redistribution, with links to + licenses. +:FAQ.txt_: Docutils Frequently Asked Questions. If you have a + question or issue, there's a good chance it's already + answered here. +:BUGS.txt_: A list of known bugs, and how to report a bug. +:RELEASE-NOTES.txt_: Summary of the major changes in recent releases. +:HISTORY.txt_: Detailed change history log. +:THANKS.txt_: Acknowledgements. + +.. _README.txt: ../README.html +.. _BUGS.txt: ../BUGS.html +.. _COPYING.txt: ../COPYING.html +.. _Docutils FAQ: +.. _FAQ.txt: ../FAQ.html +.. _RELEASE-NOTES.txt: ../RELEASE-NOTES.html +.. _HISTORY.txt: ../HISTORY.html +.. _THANKS.txt: ../THANKS.html + + +.. _user: + +``user/``: Introductory & Tutorial Material for End-Users +========================================================= + +Docutils-general: + +* `Docutils Front-End Tools <user/tools.html>`__ +* `Docutils Configuration <user/config.html>`__ +* `Docutils Mailing Lists <user/mailing-lists.html>`__ +* `Docutils Link List <user/links.html>`__ + +Writer-specific: + +* `Easy Slide Shows With reStructuredText & S5 <user/slide-shows.html>`__ +* `Docutils LaTeX Writer <user/latex.html>`__ +* `Docutils ODF/OpenOffice/odt Writer <user/odt.html>`__ + +`reStructuredText <http://docutils.sourceforge.net/rst.html>`_: + +* `A ReStructuredText Primer (HTML) <user/rst/quickstart.html>`__ (or + `text source <user/rst/quickstart.txt>`__) +* `Quick reStructuredText <user/rst/quickref.html>`__ (user reference) +* `reStructuredText Cheat Sheet <user/rst/cheatsheet.txt>`__ (text + only; 1 page for syntax, 1 page directive & role reference) +* `reStructuredText Demonstration <user/rst/demo.html>`_ (a + demonstration of most reStructuredText features; you can also have a + look at the `text source <user/rst/demo.txt>`__) + +Editor support: + +* `Emacs support for reStructuredText <user/emacs.html>`_ + + +.. _ref: + +``ref/``: Reference Material for All Groups +=========================================== + +Many of these files began as developer specifications, but now that +they're mature and used by end-users and client-developers, they have +become reference material. Successful specs evolve into refs. + +Docutils-general: + +* `The Docutils Document Tree <ref/doctree.html>`__ (incomplete) +* `Docutils Transforms <ref/transforms.html>`__ +* `Docutils Generic DTD <ref/docutils.dtd>`__ +* `OASIS XML Exchange Table Model Declaration Module + <ref/soextblx.dtd>`__ (CALS tables DTD module) + +Although not in the "ref" directory, `PEP 258`_ is a must-read +reference for any Docutils developer. + +reStructuredText_: + +* `An Introduction to reStructuredText <ref/rst/introduction.html>`__ + (includes the `Goals <ref/rst/introduction.html#goals>`__ and + `History <ref/rst/introduction.html#history>`__ of reStructuredText) +* `reStructuredText Markup Specification <ref/rst/restructuredtext.html>`__ +* `reStructuredText Directives <ref/rst/directives.html>`__ +* `reStructuredText Interpreted Text Roles <ref/rst/roles.html>`__ +* `reStructuredText Standard Definition Files + <ref/rst/definitions.html>`_ + +Prehistoric: + +* `Setext Documents Mirror + <http://docutils.sourceforge.net/mirror/setext.html>`__ + + +.. _peps: + +``peps/``: Python Enhancement Proposals +======================================= + +* `PEP 256: Docstring Processing System Framework`__ is a high-level + generic proposal. [`PEP 256`__ in the `master repository`_] +* `PEP 257: Docstring Conventions`__ addresses docstring style and + touches on content. [`PEP 257`__ in the `master repository`_] +* `PEP 258: Docutils Design Specification`__ is an overview of the + architecture of Docutils. It documents design issues and + implementation details. [`PEP 258`__ in the `master repository`_] +* `PEP 287: reStructuredText Docstring Format`__ proposes a standard + markup syntax. [`PEP 287`__ in the `master repository`_] + +Please note that PEPs in the `master repository`_ may not be current, +whereas the local versions are. + +__ peps/pep-0256.html +__ http://www.python.org/peps/pep-0256.html +__ peps/pep-0257.html +__ http://www.python.org/peps/pep-0257.html +.. _PEP 258: +__ peps/pep-0258.html +__ http://www.python.org/peps/pep-0258.html +__ peps/pep-0287.html +__ http://www.python.org/peps/pep-0287.html +.. _master repository: http://www.python.org/peps/ + + +.. _api: + +``api/``: API Reference Material for Client-Developers +====================================================== + +* `The Docutils Publisher <api/publisher.html>`__ +* `Inside A Docutils Command-Line Front-End Tool <api/cmdline-tool.html>`__ +* `Docutils Runtime Settings <api/runtime-settings.html>`__ +* (`Docutils Transforms <ref/transforms.html>`__ should be moved here) + +`PEP 258`_ is an overview of the architecture of Docutils. + + +.. _howto: + +``howto/``: Instructions for Developers +======================================= + +* **Security:** `Deploying Docutils Securely <howto/security.html>`__ +* `Writing HTML (CSS) Stylesheets for Docutils + <howto/html-stylesheets.html>`__ +* `Docutils Internationalization <howto/i18n.html>`__ +* `Creating reStructuredText Directives <howto/rst-directives.html>`__ +* `Creating reStructuredText Interpreted Text Roles + <howto/rst-roles.html>`__ + + +.. _dev: + +``dev/``: Development Notes and Plans for Core-Developers +========================================================= + +Docutils-general: + +* `Docutils Hacker's Guide <dev/hacking.html>`__ +* `Docutils Distributor's Guide <dev/distributing.html>`__ +* `Docutils To Do List <dev/todo.html>`__ +* `Docutils Project Policies <dev/policies.html>`__ +* `Docutils Web Site <dev/website.html>`__ +* `Docutils Release Procedure <dev/release.html>`__ +* `The Docutils Subversion Repository <dev/repository.html>`__ +* `Docutils Testing <dev/testing.html>`__ +* `Docstring Semantics <dev/semantics.html>`__ (incomplete) +* `Python Source Reader <dev/pysource.html>`_ (incomplete) +* `Docutils Python DTD <dev/pysource.dtd>`_ (experimental) +* `Plan for Enthought API Documentation Tool <dev/enthought-plan.html>`_ +* `Enthought API Documentation Tool RFP <dev/enthought-rfp.html>`_ + +reStructuredText_: + +* `A Record of reStructuredText Syntax Alternatives + <dev/rst/alternatives.html>`__ +* `Problems With StructuredText <dev/rst/problems.html>`__ + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: Added: trunk/jrst/src/test/resources/FilesTest/roles.txt =================================================================== --- trunk/jrst/src/test/resources/FilesTest/roles.txt (rev 0) +++ trunk/jrst/src/test/resources/FilesTest/roles.txt 2011-05-19 09:51:39 UTC (rev 586) @@ -0,0 +1,318 @@ +========================================= + reStructuredText Interpreted Text Roles +========================================= + +:Author: David Goodger +:Contact: goodger@python.org +:Revision: $Revision: 4564 $ +:Date: $Date: 2006-05-21 16:44:42 -0400 (Sun, 21 May 2006) $ +:Copyright: This document has been placed in the public domain. + +This document describes the interpreted text roles implemented in the +reference reStructuredText parser. + +Interpreted text uses backquotes (`) around the text. An explicit +role marker may optionally appear before or after the text, delimited +with colons. For example:: + + This is `interpreted text` using the default role. + + This is :title:`interpreted text` using an explicit role. + +A default role may be defined by applications of reStructuredText; it +is used if no explicit ``:role:`` prefix or suffix is given. The +"default default role" is `:title-reference:`_. It can be changed +using the default-role_ directive. + +See the `Interpreted Text`_ section in the `reStructuredText Markup +Specification`_ for syntax details. For details on the hierarchy of +elements, please see `The Docutils Document Tree`_ and the `Docutils +Generic DTD`_ XML document type definition. For interpreted text role +implementation details, see `Creating reStructuredText Interpreted +Text Roles`_. + +.. _"role" directive: directives.html#role +.. _default-role: directives.html#default-role +.. _Interpreted Text: restructuredtext.html#interpreted-text +.. _reStructuredText Markup Specification: restructuredtext.html +.. _The Docutils Document Tree: ../doctree.html +.. _Docutils Generic DTD: ../docutils.dtd +.. _Creating reStructuredText Interpreted Text Roles: + ../../howto/rst-roles.html + + +.. contents:: + + +--------------- + Customization +--------------- + +Custom interpreted text roles may be defined in a document with the +`"role" directive`_. Customization details are listed with each role. + +.. _class: + +A ``class`` option is recognized by the "role" directive for most +interpreted text roles. A description__ is provided in the `"role" +directive`_ documentation. + +__ directives.html#role-class + + +---------------- + Standard Roles +---------------- + +``:emphasis:`` +============== + +:Aliases: None +:DTD Element: emphasis +:Customization: + :Options: class_. + :Content: None. + +Implements emphasis. These are equivalent:: + + *text* + :emphasis:`text` + + +``:literal:`` +============== + +:Aliases: None +:DTD Element: literal +:Customization: + :Options: class_. + :Content: None. + +Implements inline literal text. These are equivalent:: + + ``text`` + :literal:`text` + +Care must be taken with backslash-escapes though. These are *not* +equivalent:: + + ``text \ and \ backslashes`` + :literal:`text \ and \ backslashes` + +The backslashes in the first line are preserved (and do nothing), +whereas the backslashes in the second line escape the following +spaces. + + +``:pep-reference:`` +=================== + +:Aliases: ``:PEP:`` +:DTD Element: reference +:Customization: + :Options: class_. + :Content: None. + +The ``:pep-reference:`` role is used to create an HTTP reference to a +PEP (Python Enhancement Proposal). The ``:PEP:`` alias is usually +used. For example:: + + See :PEP:`287` for more information about reStructuredText. + +This is equivalent to:: + + See `PEP 287`__ for more information about reStructuredText. + + __ http://www.python.org/peps/pep-0287.html + + +``:rfc-reference:`` +=================== + +:Aliases: ``:RFC:`` +:DTD Element: reference +:Customization: + :Options: class_. + :Content: None. + +The ``:rfc-reference:`` role is used to create an HTTP reference to an +RFC (Internet Request for Comments). The ``:RFC:`` alias is usually +used. For example:: + + See :RFC:`2822` for information about email headers. + +This is equivalent to:: + + See `RFC 2822`__ for information about email headers. + + __ http://www.faqs.org/rfcs/rfc2822.html + + +``:strong:`` +============ + +:Aliases: None +:DTD Element: strong +:Customization: + :Options: class_. + :Content: None. + +Implements strong emphasis. These are equivalent:: + + **text** + :strong:`text` + + +``:subscript:`` +=============== + +:Aliases: ``:sub:`` +:DTD Element: subscript +:Customization: + :Options: class_. + :Content: None. + +Implements subscripts. + +.. Tip:: + + Whitespace or punctuation is required around interpreted text, but + often not desired with subscripts & superscripts. + Backslash-escaped whitespace can be used; the whitespace will be + removed from the processed document:: + + H\ :sub:`2`\ O + E = mc\ :sup:`2` + + In such cases, readability of the plain text can be greatly + improved with substitutions:: + + The chemical formula for pure water is |H2O|. + + .. |H2O| replace:: H\ :sub:`2`\ O + + See `the reStructuredText spec`__ for further information on + `character-level markup`__ and `the substitution mechanism`__. + + __ restructuredtext.html + __ restructuredtext.html#character-level-inline-markup + __ restructuredtext.html#substitution-references + + +``:superscript:`` +================= + +:Aliases: ``:sup:`` +:DTD Element: superscript +:Customization: + :Options: class_. + :Content: None. + +Implements superscripts. See the tip in `:subscript:`_ above. + + +``:title-reference:`` +===================== + +:Aliases: ``:title:``, ``:t:``. +:DTD Element: title_reference +:Customization: + :Options: class_. + :Content: None. + +The ``:title-reference:`` role is used to describe the titles of +books, periodicals, and other materials. It is the equivalent of the +HTML "cite" element, and it is expected that HTML writers will +typically render "title_reference" elements using "cite". + +Since title references are typically rendered with italics, they are +often marked up using ``*emphasis*``, which is misleading and vague. +The "title_reference" element provides accurate and unambiguous +descriptive markup. + +Let's assume ``:title-reference:`` is the default interpreted text +role (see below) for this example:: + + `Design Patterns` [GoF95]_ is an excellent read. + +The following document fragment (pseudo-XML_) will result from +processing:: + + <paragraph> + <title_reference> + Design Patterns + + <citation_reference refname="gof95"> + GoF95 + is an excellent read. + +``:title-reference:`` is the default interpreted text role in the +standard reStructuredText parser. This means that no explicit role is +required. Applications of reStructuredText may designate a different +default role, in which case the explicit ``:title-reference:`` role +must be used to obtain a ``title_reference`` element. + + +.. _pseudo-XML: ../doctree.html#pseudo-xml + + +------------------- + Specialized Roles +------------------- + +``raw`` +======= + +:Aliases: None +:DTD Element: raw +:Customization: + :Options: class_, format + :Content: None + +.. WARNING:: + + The "raw" role is a stop-gap measure allowing the author to bypass + reStructuredText's markup. It is a "power-user" feature that + should not be overused or abused. The use of "raw" ties documents + to specific output formats and makes them less portable. + + If you often need to use "raw"-derived interpreted text roles or + the "raw" directive, that is a sign either of overuse/abuse or that + functionality may be missing from reStructuredText. Please + describe your situation in a message to the Docutils-users_ mailing + list. + + .. _Docutils-users: ../../user/mailing-lists.html#docutils-user + +The "raw" role indicates non-reStructuredText data that is to be +passed untouched to the Writer. It is the inline equivalent of the +`"raw" directive`_; see its documentation for details on the +semantics. + +.. _"raw" directive: directives.html#raw + +The "raw" role cannot be used directly. The `"role" directive`_ must +first be used to build custom roles based on the "raw" role. One or +more formats (Writer names) must be provided in a "format" option. + +For example, the following creates an HTML-specific "raw-html" role:: + + .. role:: raw-html(raw) + :format: html + +This role can now be used directly to pass data untouched to the HTML +Writer. For example:: + + If there just *has* to be a line break here, + :raw-html:`<br />` + it can be accomplished with a "raw"-derived role. + But the line block syntax should be considered first. + +.. Tip:: Roles based on "raw" should clearly indicate their origin, so + they are not mistaken for reStructuredText markup. Using a "raw-" + prefix for role names is recommended. + +In addition to "class_", the following option is recognized: + +``format`` : text + One or more space-separated output format names (Writer names). Added: trunk/jrst/src/test/resources/FilesTest/rstTest.rst =================================================================== --- trunk/jrst/src/test/resources/FilesTest/rstTest.rst (rev 0) +++ trunk/jrst/src/test/resources/FilesTest/rstTest.rst 2011-05-19 09:51:39 UTC (rev 586) @@ -0,0 +1,5 @@ +===== +tests +===== + +le paragraphe de test