%META:TOPICINFO{author="TWikiContributor" date="1305439919" format="1.1" version="$Rev$"}%
---+!! <nop>%TOPIC%
<!--
   Contributions to this TWiki plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/ReStructuredTextPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/ReStructuredTextPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>
%SHORTDESCRIPTION%

---++ Introduction

This plugin allows processing of reStructuredText input within a TWiki page. It accomplishes this task by calling the =trip= reStructuredText parser. The =trip= utility is included with this plugin; it is a Perl implementation of a reStructuredText parser (and writers).

[[http://docutils.sourceforge.net/rst.html][reStructuredText]] is an easy-to-read, what-you-see-is-what-you-get plain-text markup syntax and parser system. It is useful for inline program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents. The original implementation of a reStructuredText parser is that of the docutils project, written in Python. The "trip" name is an acronym for <b>T</b>ransforming <b>r</b>eStructuredText <b>i</b>n <b>P</b>erl".

---++ Syntax Rules

<verbatim>
%RESTSTART{ _parms_ }%
Add reStructuredText here
%RESTEND%=
</verbatim>

The =parms= are optional. Supported parameters:

   * =options="&lt;trip options>"= : A set of options to be passed to the =trip= executable.
   * =stylesheet="&lt;url>"= : Uses =url= as URL for a stylesheet.

---++ Examples

|   *Unrendered, we look like:*   |

<verbatim>
%RESTSTART%
A reStructuredText Header
=========================

This is reStructuredText.  Here I have a **bold block
with *italics* and ``literal`` nested within it**.
It has link to `Another Header`_.

Another Header
==============

This is a second section.
%RESTEND%
</verbatim>

|   *With the plugin installed correctly, we look like*   |

%RESTSTART%
A reStructuredText Header
=========================

This is reStructuredText.  Here I have a **bold block
with *italics* and ``literal`` nested within it**.
It has link to `Another Header`_.

Another Header
==============

This is a second section.
%RESTEND%

*(End of Examples)*

---++ Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write ==%<nop>&lt;plugin&gt;_&lt;setting&gt;%==, i.e. ==%<nop>RESTRUCTUREDTEXTPLUGIN_SHORTDESCRIPTION%==

   * One line description, shown in the %SYSTEMWEB%.TextFormattingRules topic:
      * Set SHORTDESCRIPTION = Render reStructuredText (Python documentation) within a TWiki page 

---++ Plugin Installation Instructions

__Note:__ You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running. 

   * Download the ZIP file from the Plugin web (see below)
   * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
     | *File:* | *Description:* |
     | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
     | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
     | ==lib/TWiki/Plugins/%TOPIC%/Config.spec== | Settings for configure script |
     | ==lib/TWiki/Plugins/%TOPIC%/trip/*== | trip utility (Perl script) |
   * Visit =configure= in your TWiki installation:
      * Enable the plugin in the {Plugins} section
      * In Extensions section, set {Plugins}{ReStructuredTextPlugin}{TripCmd} to an absolute path; the trip executable is located below your TWiki directory at =lib/TWiki/Plugins/%TOPIC%/trip/bin/trip=.
   * Test above example if the installation was successful.

---++ Plugin Info

|  Plugin Author: | TWiki:Main.SteveRJones, TWiki:Main.PeterThoeny |
|  Plugin Copyright: | &copy; 2005 TWiki:Main.SteveRJones <br /> &copy; 2010 TWiki:Main.PeterThoeny <br /> &copy; 2005-2010 TWiki:TWiki.TWikiContributor |
|  Trip tool Author: | TWiki:Main.MarkNodine |
|  Trip tool Copyright: | &copy; 2002-2005 Freescale Semiconductor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 2011-05-14 (V1.2) |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  2011-05-14: | TWikibug:Item6701: Doc improvements; small fix in Config.spec -- TWiki:Main.PeterThoeny |
|  2010-12-16: | TWikibug:Item6530: Move plugin settings to configure (to fix security issue); filter options parameter (to fix security issue) -- TWiki:Main.PeterThoeny |
|  2010-12-15: | TWikibug:Item6530: Doc improvements; changing TWIKIWEB to SYSTEMWEB -- TWiki:Main.PeterThoeny |
|  2005-05-19: | Initial version |
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.024 |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  TWiki:Plugins/Benchmark: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

__Related Topics:__ %SYSTEMWEB%.TWikiPreferences, %SYSTEMWEB%.TWikiPlugins

%META:TOPICMOVED{by="r4aajl" date="1116362544" from="TWiki.RestructuredTextPlugin" to="TWiki.ReStructuredTextPlugin"}%
