~ubuntu-branches/ubuntu/natty/moin/natty-updates

Re``Structured``Text 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. Re``Structured``Text is designed for extensibility for specific application domains. Re``Structured``Text is a revision and re-interpretation of the Structured``Text and Setext lightweight markup systems.

People new to Wikis often find the Re``Structured``Text markup more natural and easier to learn than the default markup of MoinMoin.

= ReStructuredText Parser =

== Installation ==

Before you can use it, you need to install the Python docutils package, which provides the additional Re``Structured``Text 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 ===

{{{#!rst

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_.

}}}

{{{#!rst

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".

=== Support for MoinMoin-specific link schemes ===

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

}}}

{{{#!rst

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:

* {{{wiki:}}}

* {{{attachment:}}}

* {{{inline:}}}

* {{{drawing:}}}

=== 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

}}}

{{{#!rst

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.

100

101

{{{ #!rst

102

.. include:: header

103

104

The sole document sentence.

105

106

.. include:: footer

107

}}}

108

109

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

110

111

==== Macro Support ====

112

113

The MoinMoin reStructuredText parser adds a new MoinMoin specific macro

114

directive. The directive allows access to MoinMoin macros from within a

115

reStructuredText document. For example:

116

117

{{{ #!rst

118

Use the title search macro to insert a search box to search through page titles.

119

120

.. macro:: [[TitleSearch]]

121

}}}

122

123

{{{#!rst

124

Use the title search macro to insert a search box to search through page titles.

125

126

.. macro:: [[TitleSearch]]

127

}}}

128

129

=== Known Issues ===

130

131

* Docutils and MoinMoin use different sets of css directives. Some directives overlap, while others do not. For example, the note directive is not displayed with any special formatting. This issue is most severe when using the rightsidebar theme with the docutils sidebar directive. The docutils sidebar will replace the MoinMoin sidebar. It is currently recommended that the sidebar directive not be used with MoinMoin.

132

* Features related to external URL and local file retrieval are unsupported by the parser in order to guarantee local security. Besides that, raw roles and other features that might support the user to output raw HTML are disallowed, too.

133

134

=== Links ===

135

136

* [[http://docutils.sourceforge.net/rst.html|reStructuredText]]

137

* [[http://docutils.sourceforge.net/docs/user/rst/quickref.html|Quick Reference]]

138

* [[http://docutils.sourceforge.net/|Docutils]]

139

* [[HelpOnParsers/ReStructuredText/RstPrimer|A ReStructuredText Primer]]

Older »