bibtex-ruby 5.1.6 → 6.1.0

data/README.md

@@ -1,7 +1,5 @@
 BibTeX-Ruby
 ===========
-[![Build Status](https://secure.travis-ci.org/inukshuk/bibtex-ruby.png?branch=master)](http://travis-ci.org/inukshuk/bibtex-ruby)
-[![Coverage Status](https://coveralls.io/repos/inukshuk/bibtex-ruby/badge.png)](https://coveralls.io/r/inukshuk/bibtex-ruby)
 
 BibTeX-Ruby is the Rubyist's swiss-army-knife for all things BibTeX. It
 includes a parser for all common BibTeX objects (@string, @preamble, @comment
@@ -10,7 +8,7 @@ formatted names; BibTeX-Ruby recognizes BibTeX string replacements, joins
 values containing multiple strings or variables, supports cross-references,
 and decodes common LaTeX formatting instructions to unicode; if you are in a
 hurry, it also allows for easy export/conversion to formats such as YAML,
-JSON, CiteProc/CSL, XML (BibTeXML), and RDF (experimental).
+JSON, CiteProc/CSL, XML (BibTeXML, requires `rexml`), and RDF (experimental).
 
 For a list of projects using BibTeX-Ruby, take a look at the
 [project wiki](https://github.com/inukshuk/bibtex-ruby/wiki/Projects-Using-BibTeX-Ruby).
@@ -26,50 +24,62 @@ Install and load BibTeX-Ruby in an IRB session:
 
 Open a BibTeX bibliography:
 
-    b = BibTeX.open('./ruby.bib')
+```ruby
+b = BibTeX.open('./ruby.bib')
+```
 
 Select a BibTeX entry and access individual fields:
 
-    b['pickaxe'].title
-    #=> "Programming Ruby 1.9: The Pragmatic Programmer's Guide"
-    b[:pickaxe].author.length
-    #=> 3
-    b[:pickaxe].author.to_s
-    #=> "Thomas, D. and Fowler, Chad and Hunt, Andy"
-    b[:pickaxe].author[2].first
-    #=> "Andy"
+```ruby
+b['pickaxe'].title
+#=> "Programming Ruby 1.9: The Pragmatic Programmer's Guide"
+b[:pickaxe].author.length
+#=> 3
+b[:pickaxe].author.to_s
+#=> "Thomas, D. and Fowler, Chad and Hunt, Andy"
+b[:pickaxe].author[2].first
+#=> "Andy"
+```
 
 Query a bibliography:
 
-    b['@book'].length
-    #=> 3 - the number books in the bibliography
-    b['@article'].length
-    #=> 0 - the number of articles in the bibliography
-    b['@book[year=2009]'].length
-    #=> 1 - the number of books published in 2009
+```ruby
+b['@book'].length
+#=> 3 - the number books in the bibliography
+b['@article'].length
+#=> 0 - the number of articles in the bibliography
+b['@book[year=2009]'].length
+#=> 1 - the number of books published in 2009
+```
 
 Extend first name initials throughout your bibliography:
 
-    b.extend_initials ['Dave', 'Thomas']
-    b[:pickaxe].author.to_s
-    #=> "Thomas, Dave and Fowler, Chad and Hunt, Andy"
+```ruby
+b.extend_initials ['Dave', 'Thomas']
+b[:pickaxe].author.to_s
+#=> "Thomas, Dave and Fowler, Chad and Hunt, Andy"
+```
 
 You can also extend all names in the bibliography to their prototypical
 (i.e., the longest available) form:
 
-    b.extend_initials! #=> extends all names in the bibliography
+```ruby
+b.extend_initials! #=> extends all names in the bibliography
+```
 
 Use with caution as this method will treat two names as identical if they
 look the same in their `#sort_order(:initials => true)` form.
 
 Unify certain fields across the bibliography:
 
-    b.unify :publisher, /o'?reilly/i, "O'Reilly"
+```ruby
+b.unify :publisher, /o'?reilly/i, "O'Reilly"
 
-    b.unify :publisher, /^penguin/i do |entry|
-      entry.publisher = 'Penguin Books'
-      entry.address = 'London'
-    end
+b.unify :publisher, /^penguin/i do |entry|
+  entry.publisher = 'Penguin Books'
+  entry.address = 'London'
+end
+```
 
 This will unify various spellings of entries published by O'Reilly and Penguin.
 
@@ -77,24 +87,24 @@ Render your bibliography in one of
 [many different citation styles](https://github.com/citation-style-language/styles)
 (requires the **citeproc-ruby** gem):
 
-    require 'citeproc'
-    CiteProc.process b[:pickaxe].to_citeproc, :style => :apa
-    #=> "Thomas, D., Fowler, C., & Hunt, A. (2009). Programming Ruby 1.9: The Pragmatic Programmer's
-      Guide. The Facets of Ruby. Raleigh, North Carolina: The Pragmatic Bookshelf."
-    CiteProc.process b[:pickaxe].to_citeproc, :style => 'chicago-author-date'
-    #=> "Thomas, Dave, Chad Fowler, and Andy Hunt. 2009. Programming Ruby 1.9: The Pragmatic
-      Programmer's Guide. The Facets of Ruby.Raleigh, North Carolina: The Pragmatic Bookshelf."
-    CiteProc.process b[:pickaxe].to_citeproc, :style => :mla
-    #=> "Thomas, Dave, Chad Fowler, and Andy Hunt. Programming Ruby 1.9: The Pragmatic Programmer's
-      Guide. Raleigh, North Carolina: The Pragmatic Bookshelf, 2009."
+```ruby
+require 'citeproc'
+CiteProc.process b[:pickaxe].to_citeproc, :style => :apa
+#=> "Thomas, D., Fowler, C., & Hunt, A. (2009). Programming Ruby 1.9: The Pragmatic Programmer's Guide. The Facets of Ruby. Raleigh, North Carolina: The Pragmatic Bookshelf."
+CiteProc.process b[:pickaxe].to_citeproc, :style => 'chicago-author-date'
+#=> "Thomas, Dave, Chad Fowler, and Andy Hunt. 2009. Programming Ruby 1.9: The Pragmatic Programmer's Guide. The Facets of Ruby.Raleigh, North Carolina: The Pragmatic Bookshelf."
+CiteProc.process b[:pickaxe].to_citeproc, :style => :mla
+#=> "Thomas, Dave, Chad Fowler, and Andy Hunt. Programming Ruby 1.9: The Pragmatic Programmer's Guide. Raleigh, North Carolina: The Pragmatic Bookshelf, 2009."
+```
 
 Save a bibliography to a file:
 
-    b.save
-    #=> saves the original file
-    b.save_to(file)
-    #=> saves the bibliography in a new file
-
+```ruby
+b.save
+#=> saves the original file
+b.save_to(file)
+#=> saves the bibliography in a new file
+```
 
 Compatibility
 -------------
@@ -108,6 +118,8 @@ Starting with BibTeX-Ruby version 3.0, support for Ruby versions 1.9.2 and
 earlier has been dropped; most features will likely continue to work, but
 compliance with old Rubies is not a priority going forward.
 
+Starting with BibTex-Ruby version 7.0, only ruby versions still in "security maintenance phase" will be supported.
+This is, as of writing Ruby 2.7 and up.
 
 Documentation
 -------------
@@ -121,16 +133,18 @@ everything, simply add `:include => [:meta_content]` to your invocation of
 Once BibTeX-Ruby has parsed your '.bib' file, you can easily access individual
 entries. For example, if you set up your bibliography as follows:
 
-    b = BibTeX.parse <<-END
-    @book{pickaxe,
-      address = {Raleigh, North Carolina},
-      author = {Thomas, Dave and Fowler, Chad and Hunt, Andy},
-      publisher = {The Pragmatic Bookshelf},
-      series = {The Facets of Ruby},
-      title = {Programming Ruby 1.9: The Pragmatic Programmer's Guide},
-      year = {2009}
-    }
-    END
+```ruby
+b = BibTeX.parse <<-END
+@book{pickaxe,
+  address = {Raleigh, North Carolina},
+  author = {Thomas, Dave and Fowler, Chad and Hunt, Andy},
+  publisher = {The Pragmatic Bookshelf},
+  series = {The Facets of Ruby},
+  title = {Programming Ruby 1.9: The Pragmatic Programmer's Guide},
+  year = {2009}
+}
+END
+```
 
 You could easily access it, using the entry's key, 'pickaxe', like so:
 `b[:pickaxe]`; you also have easy access to individual fields, for example:
@@ -149,31 +163,36 @@ problem with a field's value, simply convert it to a string by calling the
 Instead of parsing strings you can also create BibTeX elements directly in
 Ruby:
 
-    > bib = BibTeX::Bibliography.new
+```ruby
+bib = BibTeX::Bibliography.new
+```
 
 Using a Hash:
 
-    > bib << BibTeX::Entry.new({
-        :bibtex_type => :book,
-        :key => :rails,
-        :address => 'Raleigh, North Carolina',
-        :author => 'Ruby, Sam and Thomas, Dave, and Hansson, David Heinemeier',
-        :booktitle => 'Agile Web Development with Rails',
-        :edition => 'third',
-        :keywords => 'ruby, rails',
-        :publisher => 'The Pragmatic Bookshelf',
-        :series => 'The Facets of Ruby',
-        :title => 'Agile Web Development with Rails',
-        :year => '2009'
-      })
+```ruby
+bib << BibTeX::Entry.new({
+  :bibtex_type => :book,
+  :key => :rails,
+  :address => 'Raleigh, North Carolina',
+  :author => 'Ruby, Sam and Thomas, Dave, and Hansson, David Heinemeier',
+  :booktitle => 'Agile Web Development with Rails',
+  :edition => 'third',
+  :keywords => 'ruby, rails',
+  :publisher => 'The Pragmatic Bookshelf',
+  :series => 'The Facets of Ruby',
+  :title => 'Agile Web Development with Rails',
+  :year => '2009'
+})
+```
 
 Or programmatically:
 
-    > book = BibTeX::Entry.new
-    > book.type = :book
-    > book.key = :mybook
-    > bib << book
-
+```ruby
+book = BibTeX::Entry.new
+book.type = :book
+book.key = :mybook
+bib << book
+```
 
 ### Cross References
 
@@ -183,24 +202,25 @@ and `inproceedings`. When an entry has a valid citation key in the field
 `crossref`, BibTeX-Ruby will return any fields inherited from the parent
 entry:
 
-    > b = BibTeX.parse <<-END
-    @inbook{fraassen_1989b,
-      Crossref = {fraassen_1989},
-      Pages = {40-64},
-      Title = {Ideal Science: David Lewis's Account of Laws},
-    }
-
-    @book{fraassen_1989,
-      Address = {Oxford},
-      Author = {Bas C. van Fraassen},
-      Publisher = {Oxford University Press},
-      Title = {Laws and Symmetry},
-      Year = 1989
-    }
-    END
-    > b['fraassen_1989b'].booktitle
-    => <"Laws and Symmetry">
-
+```ruby
+b = BibTeX.parse <<-END
+@inbook{fraassen_1989b,
+  Crossref = {fraassen_1989},
+  Pages = {40-64},
+  Title = {Ideal Science: David Lewis's Account of Laws},
+}
+
+@book{fraassen_1989,
+  Address = {Oxford},
+  Author = {Bas C. van Fraassen},
+  Publisher = {Oxford University Press},
+  Title = {Laws and Symmetry},
+  Year = 1989
+}
+END
+> b['fraassen_1989b'].booktitle
+#=> <"Laws and Symmetry">
+```
 
 ### Queries
 
@@ -210,70 +230,75 @@ Additionally, you can access individual elements or groups of elements via
 their index using `Bibliography#[]`; this accessor also exposes some of the
 query functionality with the exception of yielding to a block. For instance:
 
-    bib[-1]
-    => Returns the last element of the Bibliography or nil
-    bib[1,2]
-    => Returns the second and third elements or nil
-    bib[1..2]
-    => Same as above
-
-    bib[:key]
-    => Returns the first entry with key 'key' or nil
-    bib['key']
-    => Returns all entries with key 'key' or []
-
-    bib['@article']
-    => Returns all entries of type 'article' or []
-    bib['!@book']
-    => Returns all entries of any type other than 'book' or []
-    bib['@preamble']
-    => Returns all preamble objects (this is the same as Bibliography#preambles) or []
-    bib[/ruby/]
-    => Returns all objects that match 'ruby' anywhere or []
-
-    bib['@incollection[booktitle]']
-    => Returns all in-collection entries with a booktitle or []
-
-    # note that the above includes entries inheriting the book title
-    # from a cross-referenced entry!
-
-    bib['@book[keywords=ruby]']
-    => Returns all books whose keywords attribute equals 'ruby' or []
-    bib['@book[keywords!=ruby]']
-    => Returns all books whose keywords attribute does not equal 'ruby'
-    bib['@book[keywords/=ruby]']
-    => Same as above
-
-    bib.q('@book[keywords ^= ruby]')
-    => Returns all books whose keywords attribute matches /^ruby/
-    bib.q('@book[keywords ~= ruby]')
-    => Returns all books whose keywords attribute matches /ruby/
-    bib['@book[keywords!~ruby]']
-    => Returns all books whose keywords attribute does not match /ruby/ or don't have keywords attribute
-
-    bib.q('@article[year<=2007]')
-    => Returns all articles published in 2007 or earlier
-    bib.query('@book') { |e| e.keywords.split(/,/).length > 1 }
-    => Returns all book entries with two or more keywords or []
+```ruby
+bib[-1]
+#=> Returns the last element of the Bibliography or nil
+bib[1,2]
+#=> Returns the second and third elements or nil
+bib[1..2]
+#=> Same as above
+
+bib[:key]
+#=> Returns the first entry with key 'key' or nil
+bib['key']
+#=> Returns all entries with key 'key' or []
+
+bib['@article']
+#=> Returns all entries of type 'article' or []
+bib['!@book']
+#=> Returns all entries of any type other than 'book' or []
+bib['@preamble']
+#=> Returns all preamble objects (this is the same as Bibliography#preambles) or []
+bib[/ruby/]
+#=> Returns all objects that match 'ruby' anywhere or []
+
+bib['@incollection[booktitle]']
+#=> Returns all in-collection entries with a booktitle or []
+
+# note that the above includes entries inheriting the book title
+# from a cross-referenced entry!
+
+bib['@book[keywords=ruby]']
+#=> Returns all books whose keywords attribute equals 'ruby' or []
+bib['@book[keywords!=ruby]']
+#=> Returns all books whose keywords attribute does not equal 'ruby'
+bib['@book[keywords/=ruby]']
+#=> Same as above
+
+bib.q('@book[keywords ^= ruby]')
+#=> Returns all books whose keywords attribute matches /^ruby/
+bib.q('@book[keywords ~= ruby]')
+#=> Returns all books whose keywords attribute matches /ruby/
+bib['@book[keywords!~ruby]']
+#=> Returns all books whose keywords attribute does not match /ruby/ or don't have keywords attribute
+
+bib.q('@article[year<=2007]')
+#=> Returns all articles published in 2007 or earlier
+bib.query('@book') { |e| e.keywords.split(/,/).length > 1 }
+#=> Returns all book entries with two or more keywords or []
+```
 
 Queries offer syntactic sugar for common enumerator invocations:
 
-    bib.query(:all, '@book')
-    => same as bib.select { |b| b.has_type?(:book) }
-    bib.query('@book')
-    => same as above
-    bib.query(:first, '@book')
-    => same as bib.detect { |b| b.has_type?(:book) }
-    bib.query(:none, '@book')
-    => same as bib.reject { |b| b.has_type?(:book) }
+```ruby
+bib.query(:all, '@book')
+#=> same as bib.select { |b| b.has_type?(:book) }
+bib.query('@book')
+#=> same as above
+bib.query(:first, '@book')
+#=> same as bib.detect { |b| b.has_type?(:book) }
+bib.query(:none, '@book')
+#=> same as bib.reject { |b| b.has_type?(:book) }
+```
 
 You can also use queries to delete entries in your bibliography:
 
-    bib.delete(/ruby/)
-    => deletes all object that match 'ruby' in their string representation
-    bib.delete('@comment')
-    => strips all BibTeX comments from the bibliography
-
+```ruby
+bib.delete(/ruby/)
+#=> deletes all object that match 'ruby' in their string representation
+bib.delete('@comment')
+#=> strips all BibTeX comments from the bibliography
+```
 
 ### String Replacement
 
@@ -284,39 +309,43 @@ You can replace the string symbols of an object by calling the object's
 the **replace** method. Thus, to replace all strings defined in bibliography
 b you could use the following code:
 
-    b.each do |obj|
-      obj.replace(b.q('@string'))
-    end
-    
+```ruby
+b.each do |obj|
+  obj.replace(b.q('@string'))
+end
+```
+
 A shorthand version for replacing all strings in a given bibliography is the
 `Bibliography#replace` method. Similarly, you can use the
 `Bibliography#join` method to join individual strings together. For instance:
 
-    > bib = BibTeX::Bibliography.new
-    > bib.add BibTeX::Element.parse '@string{ foo = "foo" }'
-    > bib << BibTeX::Element.parse '@string{ bar = "bar" }'
-    > bib.add BibTeX::Element.parse <<-END
-    >  @book{abook,
-    >    author = foo # "Author",
-    >    title = foo # bar
-    >  }
-    > END
-    > puts bib[:abook].to_s
-    @book{abook,
-      author = foo # "Author",
-      title = foo # bar
-    }
-    > bib.replace
-    > puts bib[:abook].to_s
-    @book{abook,
-      author = "foo" # "Author",
-      title = "foo" # "bar"
-    }
-    > bib.join
-    @book{abook,
-      author = {fooAuthor},
-      title = {foobar}
-    }
+```ruby
+    bib = BibTeX::Bibliography.new
+    bib.add BibTeX::Element.parse '@string{ foo = "foo" }'
+    bib << BibTeX::Element.parse '@string{ bar = "bar" }'
+    bib.add BibTeX::Element.parse <<-END
+     @book{abook,
+       author = foo # "Author",
+       title = foo # bar
+     }
+    END
+    puts bib[:abook].to_s
+    #@book{abook,
+    #  author = foo # "Author",
+    #  title = foo # bar
+    #}
+    bib.replace
+    puts bib[:abook].to_s
+    #@book{abook,
+    #  author = "foo" # "Author",
+    #  title = "foo" # "bar"
+    #}
+    bib.join
+    #@book{abook,
+    #  author = {fooAuthor},
+    #  title = {foobar}
+    #}
+```
 
 ### Names
 
@@ -335,34 +364,42 @@ symbols that cannot be replaced will not be parsed.
 In the following example, string replacement can take place, thus all names
 are parsed and can easily be mapped to their last names:
 
-    BibTeX.parse(<<-END)[1].author.map(&:last)
-      @string{ ht = "Nathaniel Hawthorne" }
-      @book{key,
-       author = ht # " and Melville, Herman"
-      }
-      END
-    #=> ["Hawthorne", "Melville"]
+```ruby
+BibTeX.parse(<<-END)[1].author.map(&:last)
+  @string{ ht = "Nathaniel Hawthorne" }
+  @book{key,
+    author = ht # " and Melville, Herman"
+  }
+  END
+#=> ["Hawthorne", "Melville"]
+```
 
 Another useful method is `Bibliography#names` which returns all names in
 your bibliography (authors, editors, translators). For example, to quickly
 expand the initials of a name across your entire bibliography, you could
 use the following snippet:
 
-    b.names.each do |name|
-      if name.sort_order =~ /^Poe, E/
-        name.first = 'Edgar Allen'
-      end
-    end
+```ruby
+b.names.each do |name|
+  if name.sort_order =~ /^Poe, E/
+    name.first = 'Edgar Allen'
+  end
+end
+```
 
 There is also a short-hand for this use case:
 
-    b.extend_initials ['Edgar Allen', 'Poe']
+```ruby
+b.extend_initials ['Edgar Allen', 'Poe']
+```
 
 Alternatively, if your bibliography contains the same names in various
 forms (e.g., 'Poe, Edgar A.', 'Poe, E.A.', 'Poe, E. Allen') you can also
 set all names to their longest available form:
 
-    b.extend_initials!
+```ruby
+b.extend_initials!
+```
 
 Use with caution, though, as this method will treat names as identical
 as long as their initials are the same. That is to say, 'Poe, Eric A.' would
@@ -376,11 +413,13 @@ names or initials, titles using different casing, different keywords etc.).
 BibTex-Ruby allows you to group your bibliography by any number of fields
 in order to detect such duplicate entries.
 
-    b.select_duplicates_by :year, :title
-    #=> groups the bibliography by using the year and title field as key
+```ruby
+b.select_duplicates_by :year, :title
+#=> groups the bibliography by using the year and title field as key
 
-    b.duplicates?
-    #=> whether or not the bibliography contains any duplicates
+b.duplicates?
+#=> whether or not the bibliography contains any duplicates
+```
 
 For more complex requirements you can use the `#group_by` method directly.
 This methods accepts a list of arguments whose value will be used for grouping
@@ -390,25 +429,29 @@ digest.
 
 The duplicate methods above, for example, do something like this:
 
-    group_by(:year, :title) do |digest, entry|
-      digest.gsub(/\s+/, '').downcase
-    end
+```ruby
+group_by(:year, :title) do |digest, entry|
+  digest.gsub(/\s+/, '').downcase
+end
+```
 
 You can use this method, for example, to match entries only by their author's
 last name and so on and so forth.
 
 Since version 4.1.0, BibTeX-ruby supports parsing of names spelled in the East Asian order (last name, then first name). Names contain a Chinese, Japanese or Korean letter are currently assumed to be such names. If the name is written in comma-separated manner, it is parsed in the normal way.
 
-    b = BibTeX.parse(<<-END)
-    @book{key,
-     title = "プログラミング言語 Ruby",
-     author = "David Flanagan and まつもと ゆきひろ",
-     translator = "卜部, 昌平 and 長尾, 高弘",
-     year = "2009",
-     publisher = "O'Reilly Japan"
-    }
-    END
-    [*b[0].author, *b[0].translator].map(&:last) #=> [Flanagan, まつもと, 卜部, 長尾]
+```ruby
+b = BibTeX.parse(<<-END)
+@book{key,
+  title = "プログラミング言語 Ruby",
+  author = "David Flanagan and まつもと ゆきひろ",
+  translator = "卜部, 昌平 and 長尾, 高弘",
+  year = "2009",
+  publisher = "O'Reilly Japan"
+}
+END
+[*b[0].author, *b[0].translator].map(&:last) #=> [Flanagan, まつもと, 卜部, 長尾]
+```
 
 ### Filters
 
@@ -419,24 +462,30 @@ to a given filter. Starting with version 1.3.9 BibTeX-Ruby includes a
 LaTeX filter that depends on the
 [latex-decode gem](http://rubygems.org/gems/latex-decode). Example:
 
-    faust = '@book{faust, title = {Faust: Der Trag\"odie Erster Teil}}'
-    BibTeX.parse(faust).convert(:latex)[:faust].title
-    #=> "Faust: Der Tragödie Erster Teil"
+```ruby
+faust = '@book{faust, title = {Faust: Der Trag\"odie Erster Teil}}'
+BibTeX.parse(faust).convert(:latex)[:faust].title
+#=> "Faust: Der Tragödie Erster Teil"
+```
 
 Conditional conversions are also supported:
 
-    faust1 = '@book{faust1, title = {Faust: Der Trag\"odie Erster Teil}}'
-    faust2 = '@book{faust2, title = {Faust: Der Trag\"odie Zweiter Teil}}'
-    p BibTeX.parse(faust1 + faust2).convert(:latex) { |e| e.key == :faust2 }.to_s
-    
+```ruby
+faust1 = '@book{faust1, title = {Faust: Der Trag\"odie Erster Teil}}'
+faust2 = '@book{faust2, title = {Faust: Der Trag\"odie Zweiter Teil}}'
+p BibTeX.parse(faust1 + faust2).convert(:latex) { |e| e.key == :faust2 }.to_s
+```
+
 Returns:
 
-    @book{faust1,
-      title = {Faust: Der Trag\"odie Erster Teil}
-    }
-    @book{faust2,
-      title = {Faust: Der Tragödie Zweiter Teil}
-    }
+```bibtex
+@book{faust1,
+  title = {Faust: Der Trag\"odie Erster Teil}
+}
+@book{faust2,
+  title = {Faust: Der Tragödie Zweiter Teil}
+}
+```
 
 If you need to express a condition on the basis of individual fields, use the
 conversion methods of BibTeX::Entry with a block instead (the block will be
@@ -446,8 +495,9 @@ When working with Bibliographies that contain LaTeX it is often best to
 apply the filter upon opening or parsing the Bibliography. You can do this,
 by passing the `:filter` option:
 
-   BibTeX.open 'references.bib', :filter => :latex
-
+```ruby
+BibTeX.open 'references.bib', :filter => :latex
+```
 
 ### Exports
 
@@ -463,23 +513,27 @@ In order to export your bibliography use **#to\_s**, **#to\_yaml**,
 **#to\_json**, or **#to\_xml**, respectively. For example, the following line
 constitutes a simple BibTeX to YAML converter:
 
-    >> BibTeX.open('example.bib').to_yaml
+```ruby
+BibTeX.open('example.bib').to_yaml
+```
 
 Starting with version 2.0, BibTeX-Ruby's `#to_xml` exports your bibliography
-to the [BibTeXML](http://bibtexml.sf.net/) format. By passing the option
+to the [BibTeXML](http://bibtexml.sf.net/) format via `rexml`. By passing the option
 `:extended => true` you can make use of the BibTeXML's extended format which
 will return individual person elements and name tokens (provided you have
 successfully parsed the names of your bibliography).
 
-    > BibTeX.parse(<<-END).to_xml(:extended => true).write($stdout, 2)
-    " @book{pickaxe,
-    "   Address = {Raleigh, North Carolina},
-    "     Author = {Thomas, Dave, and Fowler, Chad, and Hunt, Andy},
-    "     Publisher = {The Pragmatic Bookshelf},
-    "     Title = {Programming Ruby 1.9: The Pragmatic Programmer's Guide},
-    "     Year = {2009}
-    "   }
-    " END
+```ruby
+BibTeX.parse(<<-END).to_xml(:extended => true).write($stdout, 2)
+@book{pickaxe,
+  Address = {Raleigh, North Carolina},
+  Author = {Thomas, Dave, and Fowler, Chad, and Hunt, Andy},
+  Publisher = {The Pragmatic Bookshelf},
+  Title = {Programming Ruby 1.9: The Pragmatic Programmer's Guide},
+  Year = {2009}
+}
+END
+```
 
 This example parse a BibTeX entry, formats it as extended BibTeXML,
 and writes the following XML to standard out:
@@ -529,35 +583,38 @@ hash which lets you define what quotes to use (note that BibTeX-Ruby will
 always use regular double quotes if a value consists of more than one token,
 because these tokens will be concatenated using BibTeX's '#' operator).
 
-    >> BibTeX.parse(<<-END).to_a # implies: :quotes => ['{','}']
-    @book{pickaxe,
-      Address = {Raleigh, North Carolina},
-      Author = {Thomas, Dave, and Fowler, Chad, and Hunt, Andy},
-      Publisher = {The Pragmatic Bookshelf},
-      Title = {Programming Ruby 1.9: The Pragmatic Programmer's Guide},
-      Year = {2009}
-    }
-    END
-    => [{:bibtex_key=>:pickaxe, :bibtex_type=>:book,
-      :address=>"{Raleigh, North Carolina}",
-      :author=>"{Thomas, Dave, and Fowler, Chad, and Hunt, Andy}",
-      :publisher=>"{The Pragmatic Bookshelf}",
-      :title=>"{Programming Ruby 1.9: The Pragmatic Programmer's Guide}",
-      :year=>"{2009}"}]
+```ruby
+BibTeX.parse(<<-END).to_a # implies: :quotes => ['{','}']
+@book{pickaxe,
+  Address = {Raleigh, North Carolina},
+  Author = {Thomas, Dave, and Fowler, Chad, and Hunt, Andy},
+  Publisher = {The Pragmatic Bookshelf},
+  Title = {Programming Ruby 1.9: The Pragmatic Programmer's Guide},
+  Year = {2009}
+}
+END
+#=> [{:bibtex_key=>:pickaxe, :bibtex_type=>:book,
+#  :address=>"{Raleigh, North Carolina}",
+#  :author=>"{Thomas, Dave, and Fowler, Chad, and Hunt, Andy}",
+#  :publisher=>"{The Pragmatic Bookshelf}",
+#  :title=>"{Programming Ruby 1.9: The Pragmatic Programmer's Guide}",
+#  :year=>"{2009}"}]
+```
 
 For post-processing in Ruby most of the time you do not need any explicit
 quotes; therefore you can simply add the :quotes option with an empty string:
 
-    >> BibTeX.parse(<<-END).to_a(:quotes => '')
-    ...
-    END
-    => [{:bibtex_key=>:pickaxe, :bibtex_type=>:book,
-      :address=>"Raleigh, North Carolina",
-      :author=>"Thomas, Dave, and Fowler, Chad, and Hunt, Andy",
-      :publisher=>"The Pragmatic Bookshelf",
-      :title=>"Programming Ruby 1.9: The Pragmatic Programmer's Guide",
-      :year=>"2009"}]
-
+```ruby
+>> BibTeX.parse(<<-END).to_a(:quotes => '')
+...
+END
+#=> [{:bibtex_key=>:pickaxe, :bibtex_type=>:book,
+#  :address=>"Raleigh, North Carolina",
+#  :author=>"Thomas, Dave, and Fowler, Chad, and Hunt, Andy",
+#  :publisher=>"The Pragmatic Bookshelf",
+#  :title=>"Programming Ruby 1.9: The Pragmatic Programmer's Guide",
+#  :year=>"2009"}]
+```
 
 The Parser
 ----------
@@ -601,8 +658,6 @@ To execute the test suite continuously while you're working run:
 
     $ bundle exec guard
 
-
-
 Credits
 -------