# [Agate](http://en.wikipedia.org/w/index.php?title=Ruby_character&oldid=540994629#History)
[](http://badge.fury.io/rb/agate)
[](https://travis-ci.org/jbhannah/agate)
[](https://gemnasium.com/jbhannah/agate)
[](https://codeclimate.com/github/jbhannah/agate)
[](https://coveralls.io/r/jbhannah/agate?branch=master)
Format ruby characters (currently only furigana) in text for display. **Requires
Ruby 1.9 or later (or compatible engine).**
## Formatters
* Plain text (echoes back passed text)
* [HTML5 (`ruby` element)][]
## Usage
Install the gem with
gem install agate
or add it to your `Gemfile`:
```ruby
gem "agate", "~> 0.4.1"
```
To markup a simple string with delimited furigana:
```ruby
require "rubygems"
require "agate"
options = {
# can be any single character or pair of characters which surround ruby characters in text to parse
:delimiters => "【】" # default delimiters
# markup formatter to use (options: :plain (default), :html)
:formatter => :html
}
a = Agate::Parser.new(options) # call without arguments to use defaults
a.parse("勉【べん】強【きょう】します")
```
results in
```html
勉強します
```
which (in your browser) looks like
> 勉強します
It's highly recommended to read the W3C's documentation on the [HTML5
`ruby` element][] to understand the usage of this element. There is a
[CSS workaround][] available that enables the display of ruby characters
in all modern browsers, but it's up to you to test all cases where you
intend to use the `ruby` element.
[HTML5 (`ruby` element)]: http://www.w3.org/TR/html5/text-level-semantics.html#the-ruby-element
[CSS workaround]: http://web.nickshanks.com/stylesheets/ruby.css