Feature #1208

Restructured text support for the wiki

Added by James Turnbull about 11 years ago. Updated over 5 years ago.

Status:NewStart date:2008-05-08
Priority:NormalDue date:
Assignee:-% Done:

0%

Category:Wiki
Target version:-
Resolution:

Description

We're a heavy user of Trac's support for restructured text (http://docutils.sourceforge.net/rst.html). We'd love to migrate to Redmine but we have no way to support our existing RST based documentation.

I'd like to see the Textile parser in Redmine supplemented with a RST parser also. As there is no RST parser in Ruby currently this could be tricky but figured I'd register the request at least.


Related issues

Duplicated by Redmine - Feature #1860: reST (reStructuredText) support Closed 2008-09-05

History

#1 Updated by Daniel Serodio over 10 years ago

+1

I'm considering moving from Trac too, but ReStructuredText is a lot nicer than Textile...

#2 Updated by Chris Dew over 10 years ago

+1

Yes, we also use Trac and rst. It would be good to see it in Redmine.

#3 Updated by Ilia Lobsanov over 10 years ago

please add rst support...

#4 Updated by Jens Goldhammer about 10 years ago

+1

#5 Updated by Paul Rivier about 10 years ago

Redmine uses RedCloth to convert Textile to xhtml. In recent versions of redmine, one can add more wiki syntax engines, but we have to wonder if they should co-exist, and at which level ? IOW, should the whole instance use a uniform syntax ? Should this setting be per-project ? Per-wiki-page ?

What I mean is that using a wiki syntax or an other is generaly a matter of personal taste and nothing else. A wiki is aimed at collaborative editing, so if many syntax co-exist in the same wiki, every users will have to learn them all to be able to edit any page. So IMO, a per-page freedom of syntax is a bad idea. At least per project syntax consistency is required, but still I don't like this idea.

The other possibility is to enforce the use of two-ways full-converters in redmine. Such a two-ways converter should be able to produce xhtml from a given wiki syntax, and produce back the same wiki syntax from xhtml. That way, each user can select the wiki syntax (s)he wants to work with, and data is stored in xhtml in the model. Per-user preference really is the right level for such a setting.

#6 Updated by Ilia Lobsanov about 10 years ago

per-user preference sounds fine to me. the inline markup switch ala trac would be nice too. eg. #!html

#7 Updated by Manuel Vázquez Acosta over 9 years ago

+10

Is this goint to be implemented? Issue #1860 also ask for this.

I prefer reST because it:

  • Allows line breaking a paragraph without losing track.
  • Allows a blank line between items on a list without making two separate lists.
  • Sublists are defined by indentation level. This is far more readable than several * signs.
The cons:
  • The extensible way of making custom links is something like :rev:`12726` which is worse than r12726. However this could be easily overcome.

#8 Updated by Steve Steiner over 9 years ago

I'd be just as happy with one setting for the whole installation. We use restructured text for any text-based documentation everywhere so there's no one on the team who even wants to use anything else.

I think, generally, a group is going to be used to one format or another and it doesn't need to be too granular.

Please do one global setting and, if anyone needs more, let them bring it up again later.

I love Redmine so far and this is the one real sore spot in an otherwise awesome product.

#9 Updated by Steve Steiner over 9 years ago

Paul Rivier wrote:

Redmine uses RedCloth to convert Textile to xhtml. In recent versions of redmine, one can add more wiki syntax engines

Is there any documentation on how to do this, please?

I just upgraded to Redmine 0.8.7.stable but there's still only textile in the wiki formatting dropdown in the settings.

We only want to support restructured text across the whole app; nothing fancy, we just want restructured text to be the default everywhere.

Can this be done?

Thanks,

S

#10 Updated by James Turnbull over 9 years ago

The issue remains that is NOT a native RST parser for Ruby. Until there is one the request for support is pretty much moot.

#11 Updated by William M. over 9 years ago

I saw this issue and took Larry Baltz's markdown formatter and converted it into a simple redmine reStructuredText formatter plugin using either my RbST reStructuredText gem that processes RST via python's docutils or my PandocRuby wrapper for Pandoc.

The reason for including both options is that docutils supports all of RST but is slow (probably too slow for public-facing Redmine install), while Pandoc is faster but only supports a subset of RST (eg, no support for RST tables). Remine does formatting via a helper, so each request is dependent on the performance of the formatter.

As James noted, there is no native Ruby reStructuredText parser and I wouldn't hold my breath for one, but this plugin should be sufficient. Note that I disabled the toolbar, but feel free to fork this and put a working one back in.

#12 Updated by Paolo Freuli over 9 years ago

Hello,
I am migrating from trac to redmine.
Migration worked fine except for RST, so I tried to install the RbST and redmine reStructuredText formatter plugin (following instructions found at github link).
After installing python, docutils, RbSt and reStructuredText formatter plugin,
redmine is not starting any more.
The following error is shown:

Loading development environment (Rails 2.3.5)
/opt/redmine-0.9.2-0/ruby/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:31:in `gem_original_require': no such file to load -- RbST (MissingSourceFile)
from /opt/redmine-0.9.2-0/ruby/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:31:in `require'
from /opt/redmine-0.9.2-0/apps/redmine/vendor/rails/activesupport/lib/active_support/dependencies.rb:156:in `require'
from /opt/redmine-0.9.2-0/apps/redmine/vendor/rails/activesupport/lib/active_support/dependencies.rb:521:in `new_constants_in'

Any help is appreciated.
Thanks

#13 Updated by Paolo Freuli over 9 years ago

Hello,
I am migrating from trac to redmine.
Migration worked fine except for RST, so I tried to install the RbST and redmine reStructuredText formatter plugin (following instructions found at github link).
After installing python, docutils, RbSt and reStructuredText formatter plugin,
and now the plugin shows up correctly in the Plugins section.
I am now trying to figure out how to use it.
More: is the plugin supposed to get invoked when migrating from a trac site with wiki pages using renstructured text?
Thanks

#14 Updated by carlos lopez over 9 years ago

Hello,

You must install rbst. gem install RbST

If the problems persists (the sames happen to me (I am using Debian)) the solutions is weird.

You need to edit the file lib/redmine_restructuredtext_formatter/wiki_formatter.rb and change the line require 'RbST' to require 'rbst' *

Paolo Freuli wrote:

Hello,
I am migrating from trac to redmine.
Migration worked fine except for RST, so I tried to install the RbST and redmine reStructuredText formatter plugin (following instructions found at github link).
After installing python, docutils, RbSt and reStructuredText formatter plugin,
redmine is not starting any more.
The following error is shown:

Loading development environment (Rails 2.3.5)
/opt/redmine-0.9.2-0/ruby/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:31:in `gem_original_require': no such file to load -- RbST (MissingSourceFile)
from /opt/redmine-0.9.2-0/ruby/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:31:in `require'
from /opt/redmine-0.9.2-0/apps/redmine/vendor/rails/activesupport/lib/active_support/dependencies.rb:156:in `require'
from /opt/redmine-0.9.2-0/apps/redmine/vendor/rails/activesupport/lib/active_support/dependencies.rb:521:in `new_constants_in'

Any help is appreciated.
Thanks

#15 Updated by William M. over 9 years ago

My bad. Yeah, the require didn't play well with case-sensitive file systems. It should be fixed in the github repo now.

#17 Updated by James Turnbull about 9 years ago

William - any chance you could add support for macros and TOC etc?

#18 Updated by Greg Thornton about 9 years ago

I created a similar plugin that should be a little more turnkey. It has a simple toolbar and help link like the Textile formatter and updates some styles for the fixed-length nature of reSt. If you have Pygments installed you can also use the sourcecode directive and get free pygmentized syntax highlighting. There is currently no RbST requirement in my version either, but that may change since the author recently pushed an updated just for me. =)

Documentation is forthcoming, but from now on the master branch will remain stable.

Red reSt - Redmine reStructuredText wiki formatter

#19 Updated by Ebrahim Mohammadi about 8 years ago

I added a toolbar to William's plugin: http://github.com/ebrahim/redmine_restructuredtext_formatter

Note that my fork has some other changes as well.

#20 Updated by Ebrahim Mohammadi about 8 years ago

"reStructuredText" is one word. Please fix the title.

#21 Updated by James Turnbull about 8 years ago

Not sure it really matters but even if it did - I can't update the title.

#22 Updated by Ebrahim Mohammadi about 8 years ago

I've replaced plain textarea of redmine_restructuredtext_formatter with CodeMirror 2 for syntax highlighted rich text editor for reStructuredText. Feel free to give it a try after checking out my codemirror branch. Any kind of feedback is welcome.

#23 Updated by Jon Wong over 5 years ago

Is this plugin fit for purpose? Should this issue be closed?

I'm considering JIRA vs Redmine based on this. I'll need the following from Redmine:

  • Markdown for issues (reST is good to have here)
  • reST for wiki (must have)

Consider that Markdown syntax is very similar to reST. They complement each other. We use reST for complex documents, and Markdown for quick notes.

Ah, I see this Redmine instance uses Textile. In Markdown, Asterisks mean bold in Textile.

Nested lists in Textile is a deal-breaker for me. General human-readability is better with reST.

Nothing compares to Redmine. We hope to use Redmine if at all possible.

Also available in: Atom PDF