instiki/vendor/RedCloth-3.0.4/doc/README

p=. !redcloth3-title.png!

<div id="sidebar">

h4. Get RedCloth 3

p(example1). *Stable version:* "3.0.3":http://rubyforge.org/frs/download.php/2896/RedCloth-3.0.3.tar.gz

Take a complete tour of Textile at "A Textile Reference":http://hobix.com/textile/.

For fast syntax checking, try the "Quick Reference":http://hobix.com/textile/quick.html.

p(example1). Upgrade with "RubyGems":http://rubygems.rubyforge.org/!  Try: 
@gem install RedCloth@.

See the "project page":http://rubyforge.org/projects/redcloth/ for bug reporting, old releases and CVS instructions.  "Documentation":http://redcloth.rubyforge.org/rdoc/ is also hosted at RubyForge.

h4. RedCloth Links

"Instiki":http://www.instiki.org is the greatest Wiki ever!  Uses RedCloth for its markup!

"Hobix":http://hobix.com is a lovely little blogging package which uses RedCloth for blog entries.

<div id="css-buttons">

* "(css-button w3c)%W3C% xhtml 1.0(Valid XHTML 1.0!)":http://validator.w3.org/check?uri=referer
* "(css-button w3c w3c2)%W3C% valid css(Valid CSS!)":http://jigsaw.w3.org/css-validator/check/referer

</div>

</div>

RedCloth is a module for using Textile in Ruby.  Textile is a text format.  A very simple text format.  Another stab at making readable text that can be converted to HTML.

h2. What is Textile?

Textile is a simple markup language.

table{width:400px}.
|_. textile|_. to|_. html|
| <notextile>_a phrase_</notextile> |->|_a phrase_|
| <notextile>*a phrase*</notextile> |->|*a phrase*|
| <notextile>_*a phrase*_</notextile> |->|_*a phrase*_|
| <notextile>"Google":http://google.com</notextile> |->|"Google":http://google.com|

No need to use verbose HTML to build your docs, your blogs, your pages.  Textile gives you readable text while you're writing and beautiful text for your readers.  And if you need to break out into HTML, Textile will allow you to do so.

Textile also handles some subtleties of formatting which will enhance your document's readability:

* Single- and double-quotes around words or phrases are converted to curly quotations, much easier on
  the eye.  "Observe!"

* Double hyphens are replaced with an em-dash.  Observe -- very nice!

* Single hyphens are replaced with en-dashes. Observe - so cute!

* Triplets of periods become an ellipsis.  Observe...

* The letter 'x' becomes a dimension sign when used alone.  Observe: 2 x 2.

* Conversion of <notextile>(TM)</notextile> to (TM), <notextile>(R)</notextile> to (R), <notextile>(C)</notextile> to (C).

For more on Textile's language, hop over to "A Textile Reference":http://hobix.com/textile/.

h2. Using RedCloth

The RedCloth class is an extension of Ruby's String class. Use it like you would a String:

<pre>
  >> r = RedCloth.new "*strong text* and _emphasized text_"
  => "*strong text* and _emphasized text_"
  >> r.gsub!( 'text', 'words' )
  => "*strong words* and _emphasized words_"
</pre>

To generate HTML from your RedCloth object, use the @RedCloth#to_html@ method:

<pre>
  >> r.to_html
  => "<p><strong>strong words</strong> and <em>emphasized words</em></p>"
</pre>


h2. Installing RedCloth

To install RedCloth via RubyGems:

<pre>
  gem install RedCloth
</pre>

Or "download RedCloth":http://rubyforge.org/frs/download.php/2896/RedCloth-3.0.3.tar.gz and simply run the install.rb like so:

<pre>
  ruby install.rb config
  ruby install.rb setup
  sudo ruby install.rb install
</pre>


h2. Acknowledgements

Textile is (c) 2003 Dean Allen.  All rights reserved. You can read more "here":http://www.textism.com/tools/textile/.

RedCloth is also based on PyTextile, which is: Copyright (c) 2003, "Mark Pilgrim":http://diveintomark.org/.  All rights reserved.  You can read more about PyTextile "here":http://dealmeida.net/projects/textile.