Extension:RstToHtml

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual - list
Crystal Clear action run.png
reStructuredText to HTML

Release status: beta

Implementation Tag
Description Use reStructuredText in MediaWiki pages
Author(s) Paul Kippes
Latest version 0.1b (2008-01-31)
MediaWiki 1.5 and up
License No license specified
Download No link

Translate the RstToHtml extension if possible

Check usage and version matrix; code metrics

What is reStructuredText?[edit | edit source]

reStructuredText is a lightweight markup language intended to be highly readable in source format. A parser is implemented as a component of the Docutils text processing framework in Python. For help on creating reStructuredText, see reStructuredText Primer.

What does this extension do?[edit | edit source]

The extension hooks into your MediaWiki installation. A new tag <rst> invokes the reST parser to process the text into HTML.

Example[edit | edit source]

When this extension is installed, the following reST text would be formatted and presented in HTML. (A <source> tag prevents any parsing on this site.)

<rst>
Example Documentation
=====================
 
reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get plaintext
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. reStructuredText_ is a proposed revision and
reinterpretation of the StructuredText_ and Setext_ lightweight markup systems.
 
reStructuredText_ is designed for extensibility for specific application
domains. Its parser is a component of Docutils_.
 
.. _StructuredText: http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Setext: http://docutils.sourceforge.net/mirror/setext.html
.. _Docutils: http://docutils.sourceforge.net
 
More Examples
-------------
 
Tables are quite simple to read and create with reStructureText.  Two table
formats, grid and simple, are supported.
 
Grid Table Example
~~~~~~~~~~~~~~~~~~
 
    +------------+------------+-----------+ 
    | Header 1   | Header 2   | Header 3  | 
    +============+============+===========+ 
    | body row 1 | column 2   | column 3  | 
    +------------+------------+-----------+ 
    | body row 2 | Cells may span columns.| 
    +------------+------------+-----------+ 
    | body row 3 | Cells may  | - Cells   | 
    +------------+ span rows. | - contain | 
    | body row 4 |            | - blocks. | 
    +------------+------------+-----------+
 
Simple Table Example
~~~~~~~~~~~~~~~~~~~~
 
    =====  =====  ====== 
       Inputs     Output 
    ------------  ------ 
      A      B    A or B 
    =====  =====  ====== 
    False  False  False 
    True   False  True 
    False  True   True 
    True   True   True 
    =====  =====  ======
 
Still More Examples
-------------------
 
Various formatting such as *emphasis* and **strong emphasis** and ``inline
literal`` are supported.  Links to external websites may be fully listed,
http://www.google.com, or presented as anonymous_ links.
 
.. _anonymous: http://www.google.com
 
Lists are also easy to read and create:
 
- item 1
- item 2
- item 3
 
When literal text is required, it can be created::
 
  Whitespace, newlines, blank lines, and 
  all kinds of markup (like *this* or 
  \this) is preserved by literal blocks. 
</rst>

Where do I get the source?[edit | edit source]

Well....here. Save the following code to a file named rsttohtml.php.

NB. When installing this code (very nice thank you Paul) to MediaWiki 1.12.0 (and presumably others) it seems necessary to leave off the closing ?> tag else php returns headers after this script runs and the response object in mediawiki throws errors subsequently.


<?php
# reStructuredText to HTML
# version 0.1b (2008-01-31)
# by Paul Kippes

# Requires local installation of reStructuredText parser
# See: http://docutils.sourceforge.net/rst.html

# Update $rst2html for the appropriate location of rst2html.py

$rst2html = '/usr/bin/rst2html.py';
$wgExtensionCredits['parserhook'][] = array(
    'name' => 'RSTtoHTML',
    'author' => 'Paul Kippes',
    'url' => 'https://www.mediawiki.org/wiki/Extension:RstToHtml',
    'description' => 'This extension parses reStructured Text into HTML');
 
$wgExtensionFunctions[] = 'rstRstToHtmlSetup';
 
function rstRstToHtmlSetup()
{
    global $wgParser;
    $wgParser->setHook('rst', 'rstRstRender');
}
 
function rstRstRender($input, $args, $parser)
{
    global $rst2html;
    if (count($args))
    {
        return "<strong class='error'>" .
               "reStructureText extension: arguments not supported" .
               "</strong>";
    }
 
    if (!is_executable($rst2html))
    {
        return "<strong class='error'>" .
               "reStructureText extension: No executable at $rst2html" .
               "</strong>";
    }
 
    # If pipe errors are reported, enable output to the file.
    # But make certain the file doesn't already exist or else
    # the webserver may not have permission to create it.
    $io_desc = array(
            0 => array('pipe', 'r'),
            1 => array('pipe', 'w'),
            /* 2 => array('file', '/tmp/error-output.txt', 'a') */);
 
    $res = proc_open($rst2html . " --stylesheet-path='' " .
                     "--initial-header-level=2 --no-doc-title " .
                     "--no-file-insertion --no-raw",
                     $io_desc, $pipes, '/tmp', NULL);
    if (is_resource($res))
    {
        fwrite($pipes[0], $input);
        fclose($pipes[0]);
 
        $html = stream_get_contents($pipes[1]);
        fclose($pipes[1]);
 
        $html = preg_replace('/.*<body>\n(.*)<\/body>.*/s', '${1}', $html);
    }
    else
    {
        $html = "<strong class='error'>" .
                "reStructureText extension: error opening pipe" .
                "</strong>";
    }
 
    return $html;
}
?>

Docutils Installation[edit | edit source]

This extension requires docutils to be installed. As of this writing (18 January 2012), for example, the Ubuntu 11.10 package for Python 2.7 can be installed with

sudo apt-get install python-docutils

Once installed, the rst2html script will be installed to /usr/bin/rst2html. So with Ubuntu 11.10, the above MediaWiki script must be modified to this path. Use the whereis rst2html to locate the proper script if necessary.

The rst2html Python script can be verified by querying its version with rst2html --version.

Installation[edit | edit source]

Save the PHP source as rsttohtml.php to your extensions directory. Include the script in the LocalSettings.php file:

# Add support for reST to HTML extension
require_once('extensions/rsttohtml.php');

Issues[edit | edit source]

There seems to be no way to create an

[[internal link]]

(within the wiki, among pages) inside

<rst>...</rst>

The closest thing is:

<rst>
`other page <index.php/Other_Page>`_
</rst>

and this is represented as an external link.