welcome: please sign in

The following 345 words could not be found in the dictionary of 0 words and are highlighted below:
above   access   additional   adds   all   allows   alone   already   an   and   any   application   apt   are   areas   around   as   aspects   asterisks   at   attachment   Attachment   attachments   attacks   available   be   because   been   Before   behavior   below   Besides   block   box   but   by   can   candidates   cause   code   considered   contains   contents   Contents   converted   create   creates   creating   css   currently   Debian   default   denial   depends   designed   different   directive   directives   disallowed   displayed   distribution   distributions   do   docs   docstrings   document   documentation   documents   Docutils   docutils   does   domains   drawing   due   easier   easy   enable   error   example   Example   exist   expected   Experimental   experimental   explicit   extensibility   extensively   external   features   Features   file   find   following   footer   For   for   format   formatted   formatting   from   get   guarantee   have   header   Help   here   Here   However   html   http   hyperlink   If   image   Images   improperly   in   include   Include   Included   included   including   inline   Inline   insert   inserting   install   Installation   installation   installed   instead   interpretation   into   is   isn   issue   Issues   it   It   italics   January   jpg   Known   lack   learn   lightweight   like   limited   line   link   links   Links   Linux   local   Macro   macro   macros   markup   means   message   might   modified   module   Moin   more   most   must   name   named   natural   need   needs   net   new   newer   normal   not   note   now   number   Of   of   often   On   on   or   order   Other   other   others   outlined   output   overlap   package   packages   page   Page   pages   Parser   parser   Parsers   part   People   picture   place   plaintext   prevent   previous   Primer   probably   produce   produces   program   provides   python   Python   Quick   quickly   quickref   raw   re   Re   read   reading   recent   recommended   recursive   Reference   reference   related   replace   replaced   replacement   restrictions   retrieval   revision   rightsidebar   roles   rst   Rst   same   schemes   search   Search   Second   security   See   see   sentence   service   Setext   sets   severe   sidebar   simple   simply   slightly   snapshot   sole   Some   some   source   sourceforge   special   specific   stand   Structured   such   Support   support   supported   Supported   supports   surrounding   syntax   system   systems   Table   target   targets   Targets   ten   testing   Text   text   than   that   The   the   theme   then   there   These   They   this   This   through   Title   title   titles   to   To   too   took   two   type   typical   typically   Typically   Unknown   unknown   unsupported   upload   uploading   urls   use   Use   used   useful   user   Using   using   version   very   web   well   what   When   when   which   while   whole   wiki   Wikis   will   with   within   word   work   would   writer   yesterday   Yesterday   you   your   zip  

Clear message
location: HelpOnParsers / ReStructuredText

ReStructuredText Parser

Contents

  1. ReStructuredText Parser
    1. Installation
    2. The Parser in MoinMoin
    3. Using ReST in MoinMoin
      1. Example
      2. Unknown Targets
      3. Support for MoinMoin-specific link schemes
      4. Inline Images
      5. Experimental Features
        1. Include Support
        2. Macro Support
      6. Known Issues
      7. Links

ReStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for stand-alone documents. ReStructuredText is designed for extensibility for specific application domains. ReStructuredText is a revision and re-interpretation of the StructuredText and Setext lightweight markup systems.

People new to Wikis often find the ReStructuredText markup more natural and easier to learn than the default markup of MoinMoin.

Installation

Before you can use it, you need to install the Python docutils package, which provides the additional ReStructuredText support that MoinMoin needs.

The docutils version you will need depends on the MoinMoin version. If you are reading this text here as part of your MoinMoin installation, you probably have MoinMoin 1.5 or newer, which currently (as of January 2006) needs docutils 0.4.0 or newer, or a recent 0.3.10 snapshot. If you are using MoinMoin on Linux, docutils is probably already available as part of your Linux distribution. For example on Debian GNU/Linux you simply need to type apt-get install python-docutils. Other Linux distributions use other means to install packages: See the documentation of your Linux distribution.

The Parser in MoinMoin

The parser supports the same features that are supported by the docutils HTML writer. However, some aspects have been slightly modified to work well with MoinMoin. These areas are outlined below.

Using ReST in MoinMoin

Example

Rendering of reStructured text is not possible, please install Docutils.
This is a *very* simple example. If you see two asterisks around the word "very" in the previous sentence, then the module docutils is improperly installed (or not installed at all). When the module docutils is there, the word is displayed in italics and this whole block of text is not displayed in a special source-code-like format, but like a normal part of the page.

Unknown Targets

Unknown targets are used to create wiki links. Typically an unknown target would cause an error in a reStructuredText document. To enable wiki like behavior, unknown targets now create links to wiki pages using the target name as the name of the wiki page. For example: 

{{{#!rst
Here is a link to a MoinMoin page named SecondPage_.
}}}

Rendering of reStructured text is not possible, please install Docutils.
Here is a link to a MoinMoin page named SecondPage_.

The above contains a reStructuredText reference to "SecondPage". The reference would typically cause an unknown target error from the docutils parser. This is because there isn't a target in the document named "SecondPage". However, with the MoinMoin parser, the "SecondPage_" reference instead creates a link to a MoinMoin page named "SecondPage".

MoinMoin-specific link schemes are supported when used in a reStructuredText explicit hyperlink target. For example: 

{{{#!rst
Here is a link to a page attachment__.

__ attachment:Attachment.zip
}}}

Rendering of reStructured text is not possible, please install Docutils.
Here is a link to a page attachment__.

__ attachment:Attachment.zip

The above creates a link to an attachment named Attachment.zip. If the attachment for the page does not exist, the link text will be replaced with the typical MoinMoin replacement text for uploading an attachment. Supported MoinMoin-specific link schemes are:

Inline Images

Docutils image directives, that are not urls, are converted to MoinMoin inline: links. This produces the expected behavior of inserting the image into the document. If the image attachment does not exist, the typical MoinMoin upload new attachment message will be displayed instead. For example: 

{{{#!rst
Here is the picture I took yesterday |image|

.. |image| image:: Yesterday.jpg
}}}

Rendering of reStructured text is not possible, please install Docutils.
Here is the picture I took yesterday |image|

.. |image| image:: Yesterday.jpg

The above will insert the image "Yesterday.jpg" in place of |image|.

Experimental Features

The include and macro directives are considered experimental due to lack of testing. They are expected to work but have not been used extensively.

Include Support

The reStructuredText include directive is supported with some restrictions. The directive allows including wiki pages from the same wiki (page attachments are not candidates for the include directive). Included pages must be formatted using reStructuredText (wiki formatted pages will produce improperly formatted documents). For example, the following would insert the pages header and footer surrounding the page contents. 

{{{#!rst
.. include:: header

The sole document sentence.

.. include:: footer
}}}

The number of included documents is limited to ten. This is to prevent denial of service attacks using recursive include directives.

Macro Support

The MoinMoin reStructuredText parser adds a new MoinMoin specific macro directive. The directive allows access to MoinMoin macros from within a reStructuredText document. For example: 

{{{#!rst
Use the title search macro to insert a search box to search through page titles.

.. macro:: <<TitleSearch>>
}}}

Rendering of reStructured text is not possible, please install Docutils.
Use the title search macro to insert a search box to search through page titles.

.. macro:: <<TitleSearch>>

Known Issues