# RedCloth-4.2.9 Documentation

Homepage | redcloth.org
Author | Jason Garber
Copyright | © 2011 Jason Garber
License | MIT

(See redcloth.org/textile/ for a Textile reference.)

# RedCloth

RedCloth is a Ruby library for converting Textile into HTML.

## Installing

RedCloth can be installed via RubyGems:

    gem install RedCloth

It will install the appropriate Ruby, JRuby, or Win32 gem. If using JRuby, version 1.1.5 or greater is required.

## Compiling

If you just want to use RedCloth, you do NOT need to build/compile it. It is compiled from C sources automatically when you install the gem on the ruby platform. Precompiled binary gems are provided for JRuby and Win32 platforms.

RedCloth can be compiled with `rake compile`. Ragel 6.3 or greater is required. Again, Ragel is NOT needed to simply use RedCloth.

### Supported platforms

By default, the rake compile task builds a native C extension (MRI 1.8 or 1.9) or Java extension (JRuby 1.3). A pure Ruby version can also be generated, but it’s super slow and Ruby 1.8-only. The JRuby and pure-Ruby extensions don’t support multi-byte characters. Cross-compiling for win32 uses rake-compiler.

The RedCloth::EXTENSION_LANGUAGE constant indicates in which language your copy of RedCloth is compiled.

### Compiling gems

To compile MRI, JRuby, and win32 gems, you need rvm and rake-compiler. These and other dependencies can be installed with bundler. Then rake build:all takes care of compiling and packaging all gems.

    1. gem install bundler
    2. bundle install
    3. rake-compiler cross-ruby VERSION=1.8.6-p398
    4. rake-compiler cross-ruby VERSION=1.9.1-p243
    5. rake build:all

## Bugs

Please submit bugs to jgarber.lighthouseapp.com/projects/13054-redcloth/overview

## Using RedCloth

RedCloth is simply an extension of the String class that can handle Textile formatting. Use it like a String and output HTML with its RedCloth#to_html method.

Simple use:

    text = "This is *my* text."
    RedCloth.new(text).to_html

Multi-line example:

    doc = RedCloth.new <<EOD
    h2. Test document

    Just a simple test.
    EOD
    puts doc.to_html

## What is Textile?

Textile is a simple formatting style for text documents, loosely based on some HTML conventions.

## Sample Textile Text

    h2. This is a title

    h3. This is a subhead

    This is a bit of paragraph.

    bq. This is a blockquote.

# Writing Textile

A Textile document consists of paragraphs. Paragraphs can be specially formatted by adding a small instruction to the beginning of the paragraph.

    h3.     Header 3.
    bq.     Blockquote.
    #       Numeric list.
    *       Bulleted list.

## Quick Phrase Modifiers

Quick phrase modifiers are also included, to allow formatting of small portions of text within a paragraph.

    _emphasis_
    __italicized__
    *strong*
    **bold**
    ??citation??
    -deleted text-
    +inserted text+
    ^superscript^
    ~subscript~
    @code@
    %(classname)span%

    ==notextile== (leave text alone)

## Links

To make a hypertext link, put the link text in “quotation marks” followed immediately by a colon and the URL of the link.

Optional: text in (parentheses) following the link text, but before the closing quotation mark, will become a title attribute for the link, visible as a tool tip when a cursor is above it.

Example:

    "This is a link (This is a title)":http://www.textism.com

Will become:

    <a href="http://www.textism.com" title="This is a title">This is a link</a>

## Images

To insert an image, put the URL for the image inside exclamation marks.

Optional: text that immediately follows the URL in (parentheses) will be used as the Alt text for the image. Images on the web should always have descriptive Alt text for the benefit of readers using non-graphical browsers.

Optional: place a colon followed by a URL immediately after the closing ! to make the image into a link.

Example:

    !http://www.textism.com/common/textist.gif(Textist)!

Will become:

    <img src="http://www.textism.com/common/textist.gif" alt="Textist" />

With a link:

    !/common/textist.gif(Textist)!:http://textism.com

Will become:

    <a href="http://textism.com"><img src="/common/textist.gif" alt="Textist" /></a>

## Defining Acronyms

HTML allows authors to define acronyms via the tag. The definition appears as a tool tip when a cursor hovers over the acronym. A crucial aid to clear writing, this should be used at least once for each acronym in documents where they appear.

To quickly define an acronym in Textile, place the full text in (parentheses) immediately following the acronym.

Example:

    ACLU(American Civil Liberties Union)

Will become:

    <acronym title="American Civil Liberties Union">ACLU</acronym>

## Adding Tables

In Textile, simple tables can be added by separating each column by a pipe.

    |a|simple|table|row|
    |And|Another|table|row|

Styles are applied with curly braces.

    table{border:1px solid black}.
    {background:#ddd;color:red}. |a|red|row|

## Files

- CHANGELOG
- COPYING
- README.rdoc
- Makefile

## Classes/Modules

- RedCloth
- RedCloth::Formatters
- RedCloth::Formatters::Base
- RedCloth::Formatters::HTML
- RedCloth::Formatters::LATEX
- RedCloth::Formatters::LATEX::Settings
- RedCloth::TextileDoc
- RedCloth::TextileDoc::ParseError
- RedCloth::VERSION
- ERB
- ERB::Util
- Object

## Methods

- ::== — RedCloth::VERSION
- ::include — RedCloth
- ::new — RedCloth
- ::new — RedCloth::TextileDoc
- ::t — ERB::Util
- ::textilize — ERB::Util
- ::to_s — RedCloth::VERSION
- #acronym — RedCloth::Formatters::LATEX
- #acronym — RedCloth::Formatters::HTML
- #amp — RedCloth::Formatters::HTML
- #apos — RedCloth::Formatters::HTML
- #arrow — RedCloth::Formatters::HTML
- #arrow — RedCloth::Formatters::LATEX
- #bc_close — RedCloth::Formatters::HTML
- #bc_close — RedCloth::Formatters::LATEX
- #bc_open — RedCloth::Formatters::LATEX
- #bc_open — RedCloth::Formatters::HTML
- #bq_close — RedCloth::Formatters::HTML
- #bq_close — RedCloth::Formatters::LATEX
- #bq_open — RedCloth::Formatters::HTML
- #bq_open — RedCloth::Formatters::LATEX
- #br — RedCloth::Formatters::HTML
- #caps — RedCloth::Formatters::HTML
- #code — RedCloth::Formatters::LATEX
- #copyright — RedCloth::Formatters::HTML
- #copyright — RedCloth::Formatters::LATEX
- #del — RedCloth::Formatters::HTML
- #dim — RedCloth::Formatters::HTML
- #dim — RedCloth::Formatters::LATEX
- #dl_close — RedCloth::Formatters::HTML
- #dl_open — RedCloth::Formatters::HTML
- #ellipsis — RedCloth::Formatters::HTML
- #ellipsis — RedCloth::Formatters::LATEX
- #emdash — RedCloth::Formatters::LATEX
- #emdash — RedCloth::Formatters::HTML
- #endash — RedCloth::Formatters::LATEX
- #endash — RedCloth::Formatters::HTML
- #entity — RedCloth::Formatters::LATEX
- #entity — RedCloth::Formatters::HTML
- #fn — RedCloth::Formatters::LATEX
- #fn — RedCloth::Formatters::HTML
- #footno — RedCloth::Formatters::HTML
- #footno — RedCloth::Formatters::LATEX
- #gt — RedCloth::Formatters::HTML
- #hr — RedCloth::Formatters::HTML
- #html — RedCloth::Formatters::HTML
- #html_block — RedCloth::Formatters::HTML
- #html_esc — RedCloth::TextileDoc
- #ignore — RedCloth::Formatters::Base
- #ignored_line — RedCloth::Formatters::HTML
- #image — RedCloth::Formatters::HTML
- #image — RedCloth::Formatters::LATEX
- #inline_html — RedCloth::Formatters::LATEX
- #inline_html — RedCloth::Formatters::HTML
- #inline_redcloth_version — RedCloth::Formatters::Base
- #latex_esc — RedCloth::TextileDoc
- #latex_image_styles — RedCloth::Formatters::LATEX::Settings
- #li_close — RedCloth::Formatters::LATEX
- #li_close — RedCloth::Formatters::HTML
- #li_open — RedCloth::Formatters::LATEX
- #li_open — RedCloth::Formatters::HTML
- #link — RedCloth::Formatters::HTML
- #link — RedCloth::Formatters::LATEX
- #lt — RedCloth::Formatters::HTML
- #multi_paragraph_quote — RedCloth::Formatters::HTML
- #notextile — RedCloth::Formatters::HTML
- #notextile — RedCloth::Formatters::Base
- #p — RedCloth::Formatters::LATEX
- #quot — RedCloth::Formatters::HTML
- #quote1 — RedCloth::Formatters::HTML
- #quote1 — RedCloth::Formatters::LATEX
- #quote2 — RedCloth::Formatters::HTML
- #quote2 — RedCloth::Formatters::LATEX
- #redcloth_version — RedCloth::Formatters::Base
- #registered — RedCloth::Formatters::HTML
- #registered — RedCloth::Formatters::LATEX
- #snip — RedCloth::Formatters::LATEX
- #snip — RedCloth::Formatters::HTML
- #squot — RedCloth::Formatters::HTML
- #table_close — RedCloth::Formatters::HTML
- #table_close — RedCloth::Formatters::LATEX
- #table_open — RedCloth::Formatters::HTML
- #table_open — RedCloth::Formatters::LATEX
- #td — RedCloth::Formatters::HTML
- #td — RedCloth::Formatters::LATEX
- #to — RedCloth::TextileDoc
- #to_html — RedCloth::TextileDoc
- #to_latex — RedCloth::TextileDoc
- #tr_close — RedCloth::Formatters::HTML
- #tr_close — RedCloth::Formatters::LATEX
- #tr_open — RedCloth::Formatters::LATEX
- #tr_open — RedCloth::Formatters::HTML
- #trademark — RedCloth::Formatters::LATEX
- #trademark — RedCloth::Formatters::HTML

[Validate]

Generated with the Darkfish Rdoc Generator 2.