= Acts as Markup

by Brian Landau of Viget Labs <brian.landau@viget.com>

GitHub Project: http://github.com/vigetlabs/acts_as_markup

RDoc: 
* http://viget.rubyforge.org/acts_as_markup
* http://gitrdoc.com/vigetlabs/acts_as_markup/tree/master
* http://vigetlabs.github.com/acts_as_markup


== DESCRIPTION:

Allows you to specify columns of an ActiveRecord model that contain Markdown, 
Textile, Wiki text and RDoc. You may then use +to_s+ to get the original markup 
text or +to_html+ to get the formated HTML.

Additionally you can have a model that contains a column that has a column with 
markup text, and another that defines what language to process it as. If the field 
is listed as "markdown" "textile", "wikitext" or "rdoc" (case insensitive) it will 
treat it as such, any other value for markup language will have the value pass 
through as a normal string.

This AR extension can use 3 different types of Markdown processing backends: 
BlueCloth, RDiscount, Ruby PEG or Maruku. You specify which one you want to use by setting
a config value in your environment.rb file:

    ActsAsMarkup.markdown_library = :bluecloth

By default RDiscount will be used.

You can specify additional options to pass to the markup library by using
<tt>:markdown_options</tt>, <tt>:textile_options</tt> or <tt>:wikitext_options</tt>.
RDoc does not support any useful options. The options should be given as an
array of arguments. You can specify options for multiple languages when
allowing more than one. See each library's documentation for more details on
what options are available.

== EXAMPLES:

==== Using +acts_as_markdown+:

    class Post < ActiveRecord
      acts_as_markdown :body
    end
    
    @post = Post.find(:first)
    @post.body.to_s     #=> "## Markdown Headline"
    @post.body.to_html  #=> "<h2> Markdown Headline</h2>"
    

==== Using +acts_as_textile+:

    class Post < ActiveRecord
      acts_as_textile :body
    end

    @post = Post.find(:first)
    @post.body.to_s     #=> "h2. Textile Headline"
    @post.body.to_html  #=> "<h2>Textile Headline</h2>"
    

==== Using +acts_as_wikitext+:

    class Post < ActiveRecord
      acts_as_wikitext :body
    end

    @post = Post.find(:first)
    @post.body.to_s     #=> "== Wikitext Headline =="
    @post.body.to_html  #=> "<h2>Wikitext Headline</h2>"
    

==== Using +acts_as_rdoc+:

    class Post < ActiveRecord
      acts_as_rdoc :body
    end

    @post = Post.find(:first)
    @post.body.to_s     #=> "== RDoc Headline"
    @post.body.to_html  #=> "<h2>RDoc Headline</h2>"
    

==== Using +acts_as_markup+:

    class Post < ActiveRecord
      acts_as_markup :language => :markdown, :columns => [:body]
    end

    @post = Post.find(:first)
    @post.body.to_s     #=> "## Markdown Headline"
    @post.body.to_html  #=> "<h2> Markdown Headline</h2>"
    
    
==== Using +acts_as_markup+ with <tt>:variable</tt> language:

    class Post < ActiveRecord
      acts_as_markup :language => :variable, :columns => [:body]
    end
    
    @post = Post.find(:first)
    @post.markup_language      # => "markdown"
    @post.body.to_s            # => "## Markdown Headline"
    @post.body.to_html         # => "<h2> Markdown Headline</h2>"
    

==== Using options

    class Post < ActiveRecord
      acts_as_markdown :body, :markdown_options => [ :filter_html ]
    end
    
    class Post < ActiveRecord
      acts_as_textile :body, :textile_options => [ [ :filter_html ] ]
    end
    
    class Post < ActiveRecord
      acts_as_wikitext :body, :wikitext_options => [ { :space_to_underscore => true } ]
    end
    

== REQUIREMENTS:

You will need the RedCloth[http://whytheluckystiff.net/ruby/redcloth/] library 
for processing the Textile text, and the Wikitext[http://wikitext.rubyforge.org/] 
library for processing wikitext.

You will also need to install some type of Markdown processor.
The three options currently supported are:

* BlueCloth
* RDiscount[http://github.com/rtomayko/rdiscount]
* {Ruby PEG}[http://github.com/rtomayko/rpeg-markdown/tree/master]
* Maruku[http://maruku.rubyforge.org/]

== INSTALL:

<tt>sudo gem install acts_as_markup</tt>
 
Add "+acts_as_markup+" to your environment.rb:

    config.gem "acts_as_markup"

== CONTRIBUTING:

Make a fork on GitHub, make your changes and do a pull request. Good places to start are adding new Markdown libraries or new markup languages, here's instructions for both:

=== Instructions for how to add a new Markdown Library:

1. Add another item to the <tt>ActsAsMarkup::MARKDOWN_LIBS</tt> hash in the form of:
       :bluecloth => {:class_name => "BlueCloth",
                      :lib_name   => "bluecloth"}
   <tt>:lib_name</tt> should be the name needed to require the library, while <tt>:class_name</tt> should be the class that we are making an instance of.
2. If you need to modify the object in anyway (e.g. to add a <tt>to_s</tt> or <tt>to_html</tt> method), add a file to the "lib/acts_as_markup/exts/" directory.
3. Add appropriate tests (see current tests).

=== Instructions for how to add a new Markup Language:

1. Add a "<tt>when</tt>" statement to the "<tt>case</tt>" statement in <tt>acts_as_markup</tt>. The "<tt>when</tt>" statement should match with a symbol that represents the language name in some way (e.g. "<tt>:markdown</tt>").
2. In the "<tt>when</tt>" block you need to set the "<tt>klass</tt>" local variable and require the library and the extension file if you need one (use the special <tt>require_extensions</tt> method to require extensions).
3. Add the same lines you added to the previous "<tt>when</tt>" statement to the "<tt>:variable</tt>" "<tt>when</tt>" statement. But replace "<tt>klass</tt>" with "<tt>language_klass</tt>" (e.g. "<tt>markdown_klass</tt>").
4. Add a relevant "<tt>when</tt>" statement to the <tt>class_eval</tt> block for the "<tt>:variable</tt>" language option. This should look something like:
       when /markdown/i
         markup_klasses[:markdown].new self[col].to_s
5. Add a convenience method (e.g. "<tt>acts_as_markdown</tt>")
6. Add an extension file to the "lib/acts_as_markup/exts/" directory if you need to modify the object in anyway.
7. Add appropriate tests (see current tests).