]> git.wincent.com - wikitext.git/blobdiff - README.rdoc
Auto-initialize under Rails 3
[wikitext.git] / README.rdoc
index 4558b4581d229109258dc6e964205b0d620c9601..5c08a13330d8855c6d0a3bb8980c76bbaf6c814c 100644 (file)
@@ -1,4 +1,4 @@
-The wikitext extension is a fast wikitext-to-HTML translator written
+The Wikitext extension is a fast wikitext-to-HTML translator written
 in C and packaged as a Ruby extension.
 
 Usage is straightforward:
@@ -34,7 +34,7 @@ of design goals flowed on from this:
   printable ASCII in a compatible fashion
 * _attractive_: the emitted HTML source should be consistent and attractive
 * <em>valid output</em>: regardless of the input, the translator should
-  always produce valid XHTML output
+  always produce valid HTML5 output
 * <em>well-tested</em>: the translator should have a comprehensive test
   suite to ensure that its behaviour is not only correct but also stable
   over time
@@ -134,6 +134,9 @@ backtick (`) as a shorthand. These two are equivalent:
   <tt>fixed</tt>
   `fixed`
 
+As of version 2.0, this markup is actually translated to +code+ tags
+in the output because the +tt+ tag was removed from the HTML5 standard.
+
 If you need to insert a literal backtick in your text you use a +nowiki+
 span:
 
@@ -209,7 +212,10 @@ Would become:
   <a href="/wiki/article">link text</a>
 
 See the Parser attributes documentation for how you can override the
-default link prefix (<em>/wiki/</em> as shown in the example).
+default link prefix (<em>/wiki/</em> as shown in the example), and how
+"red links" can be implemented by applying custom CSS depending on the
+link target (this can be used to make links to non-existent pages appear
+in a different color).
 
 == Alternative blockquote and preformatted block syntax
 
@@ -232,7 +238,7 @@ the two styles (HTML markup and wikitext markup).
 +pre+ blocks may also contain a custom +lang+ attribute for the purposes
 of marking up a block for syntax-highlighting (note that the highlighting
 itself would be provided by JavaScript in the browser and is not actually
-part of the wikitext extension). For example:
+part of the Wikitext extension). For example:
 
   <pre lang="ruby">puts @person.name</pre>
 
@@ -295,6 +301,37 @@ Would become:
 
   <img src="/foo.png" alt="/foo.png" />
 
+= Rails support
+
+The Wikitext extension provides a template handler so that templates named
+following the <tt>template_name.html.wikitext</tt> format will automatically be
+translated from wikitext markup into HTML when rendered.
+
+Likewise, a +to_wikitext+ method (aliased as +w+) is added to the +String+
+class (and also +NilClass+, for convenience) so that content can be easily
+translated.
+
+Finally, a Wikitext::Parser#shared_parser method is added to provide
+convenient access to a shared singleton instance of the parser so as to
+avoid repeatedly instantiating and setting up new parser instances as part
+of every request.
+
+== Rails 2.3
+
+The plug-in can be activated with an appropriate <tt>config.gem</tt> statement
+in your <tt>config/environment.rb</tt>:
+
+  config.gem 'wikitext'
+
+== Rails 3.0
+
+Add a line like the following to your Gemfile:
+
+  gem 'wikitext', '>= 2.0'
+
+Note that while older versions of Wikitext do work with Rails 3 to some degree,
+for full compatibility Wikitext version 2.0 or higher should be used.
+
 = Links
 
 * RubyForge project page: http://rubyforge.org/projects/wikitext
@@ -304,7 +341,7 @@ Would become:
 
 = License
 
-Copyright 2007-2009 Wincent Colaiuta. All rights reserved.
+Copyright 2007-2010 Wincent Colaiuta. All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
@@ -329,7 +366,7 @@ POSSIBILITY OF SUCH DAMAGE.
 
 = Feedback
 
-Please let me know if you're using the wikitext extension in your project.
+Please let me know if you're using the Wikitext extension in your project.
 If you have any bug reports or feature requests please open a ticket in
 the issue tracker at https://wincent.com/issues.