bibtex-ruby 1.2.1 → 1.3.0

data/Gemfile

@@ -1,2 +1,7 @@
 source :rubygems
-gemspec
+gemspec
+
+group :development do
+	gem 'ruby-debug19', :platforms => [:ruby_19]
+	gem 'ruby-debug', :platforms => [:ruby_18]
+end

data/Gemfile.lock

@@ -1,20 +1,63 @@
 PATH
   remote: .
   specs:
-    bibtex-ruby (1.1.2)
+    bibtex-ruby (1.3.0)
 
 GEM
   remote: http://rubygems.org/
   specs:
+    archive-tar-minitar (0.5.2)
+    autowatchr (0.1.5)
+      watchr
+    builder (3.0.0)
+    columnize (0.3.2)
+    cucumber (0.10.2)
+      builder (>= 2.1.2)
+      diff-lcs (>= 1.1.2)
+      gherkin (>= 2.3.5)
+      json (>= 1.4.6)
+      term-ansicolor (>= 1.0.5)
+    diff-lcs (1.1.2)
+    gherkin (2.3.5)
+      json (>= 1.4.6)
     json (1.5.1)
-    minitest (2.0.2)
+    linecache (0.43)
+    linecache19 (0.5.12)
+      ruby_core_source (>= 0.1.4)
+    mini_shoulda (0.3.0)
+      minitest (~> 2.1.0)
+    minitest (2.1.0)
+    mynyml-redgreen (0.7.1)
+      term-ansicolor (>= 1.0.4)
     racc (1.4.6)
+    ruby-debug (0.10.4)
+      columnize (>= 0.1)
+      ruby-debug-base (~> 0.10.4.0)
+    ruby-debug-base (0.10.4)
+      linecache (>= 0.3)
+    ruby-debug-base19 (0.11.25)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby_core_source (>= 0.1.4)
+    ruby-debug19 (0.11.6)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby-debug-base19 (>= 0.11.19)
+    ruby_core_source (0.1.5)
+      archive-tar-minitar (>= 0.5.2)
+    term-ansicolor (1.0.5)
+    watchr (0.7)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  autowatchr (>= 0.1)
   bibtex-ruby!
-  json (>= 1.5.0)
-  minitest (>= 2.0.2)
-  racc (>= 1.4.6)
+  cucumber (>= 0.10)
+  json (>= 1.5)
+  mini_shoulda (>= 0.3)
+  mynyml-redgreen (>= 0.7)
+  racc (>= 1.4)
+  ruby-debug
+  ruby-debug19

data/History.txt

@@ -1,7 +1,22 @@
+=== 1.3.1
+
+* Added CiteProc/CSL export format
+
+=== 1.3.0 / 2011-05-12
+
+* Improved top-level utility functions
+* Implemented a BibTeX name parser and name value objects
+* Re-factored and cleaned up API and export
+* Added cucumber features
+* Re-implemented string handling using dedicated Value objects
+* Implemented query language to search in bibliographies
+* Improved testing environment
+* Added cucumber features
+
 === 1.2.1 / 2011-02-26
 
 * Fixed several MacRuby compliancy issues.
-* Fixed compatibility issues and BibTeX parsing of Name tokens (by lyro)
+* Fixed compatibility issues and BibTeX parsing of name tokens (lyro)
 
 === 1.2.0 / 2011-02-12
 

data/Manifest

@@ -5,11 +5,27 @@ LICENSE
 Manifest
 README.md
 Rakefile
+auto.watchr
 bibtex-ruby.gemspec
 examples
 examples/bib2html.rb
 examples/bib2yaml.rb
 examples/markdown.bib
+features
+features/bibtex.feature
+features/entries.feature
+features/issues
+features/issues/slash_keys.feature
+features/names.feature
+features/preambles.feature
+features/query.feature
+features/replacement.feature
+features/step_definitions
+features/step_definitions/bibtex_steps.rb
+features/step_definitions/name_steps.rb
+features/strings.feature
+features/support
+features/support/env.rb
 lib
 lib/bibtex
 lib/bibtex/bibliography.rb
@@ -19,30 +35,38 @@ lib/bibtex/entry.rb
 lib/bibtex/error.rb
 lib/bibtex/extensions.rb
 lib/bibtex/lexer.rb
+lib/bibtex/name_parser.output
+lib/bibtex/name_parser.rb
+lib/bibtex/names.rb
+lib/bibtex/names.y
 lib/bibtex/parser.output
 lib/bibtex/parser.rb
+lib/bibtex/replaceable.rb
 lib/bibtex/utilities.rb
+lib/bibtex/value.rb
 lib/bibtex/version.rb
 lib/bibtex.rb
 test
-test/bib
-test/bib/00_empty.bib
-test/bib/01_no_bibtex.bib
-test/bib/02_string.bib
-test/bib/03_string.bib
-test/bib/04_string_replacement.bib
-test/bib/05_comment.bib
-test/bib/06_preamble.bib
-test/bib/07_entry.bib
-test/bib/08_decoret.bib
-test/bib/09_errors.bib
-test/bib/10_bibdesk.bib
-test/bib/11_roundtrip.bib
+test/benchmark.rb
+test/bibtex
+test/bibtex/test_bibliography.rb
+test/bibtex/test_elements.rb
+test/bibtex/test_entry.rb
+test/bibtex/test_names.rb
+test/bibtex/test_parser.rb
+test/bibtex/test_string.rb
+test/bibtex/test_utilities.rb
+test/bibtex/test_value.rb
+test/fixtures
+test/fixtures/bibdesk.bib
+test/fixtures/comment.bib
+test/fixtures/decoret.bib
+test/fixtures/empty.bib
+test/fixtures/entry.bib
+test/fixtures/errors.bib
+test/fixtures/no_bibtex.bib
+test/fixtures/preamble.bib
+test/fixtures/roundtrip.bib
 test/helper.rb
 test/test_bibtex.rb
-test/test_comment.rb
-test/test_entry.rb
-test/test_export.rb
-test/test_preamble.rb
-test/test_string.rb
-test/test_utilities.rb
+test/test_export.rb

data/README.md

@@ -1,12 +1,13 @@
 BibTeX-Ruby
 ===========
 
-The BibTeX-Ruby package contains a parser for BibTeX bibliography files and a
-class structure to manage or convert BibTeX objects in Ruby. It is designed to
-support all BibTeX objects (including @comment, string-replacements via @string,
-as well as string concatenation using '#') and handles all content outside of
-BibTeX objects as 'meta comments' which may or may not be included in
-post-processing.
+BibTeX-Ruby is a fairly complete library and parser for BibTeX bibliography
+files; it offers an interface to manage, search, or convert BibTeX objects in
+Ruby. It is designed to support all BibTeX objects (including @comment,
+string-replacements via @string, as well as string concatenation using '#')
+and handles all content outside of BibTeX objects as 'meta content' which may
+or may not be included in post-processing. BibTeX-Ruby also includes a name
+parser to support comfortable access to the individual tokens of name values.
 
 
 Quickstart
@@ -14,26 +15,25 @@ Quickstart
 
     $ [sudo] gem install bibtex-ruby
     $ irb
-    > require 'bibtex'
-     => true
-    > bib = BibTeX.open('./ruby.bib')
-     => book{pickaxe,
-      address = {Raleigh, North Carolina},
-      author  = {Thomas, Dave, and Fowler, Chad, and Hunt, Andy},
-      date-added = {2010-08-05 09:54:07 0200},
-      date-modified = {2010-08-05 10:07:01 0200},
-      keywords = {ruby},
-      publisher = {The Pragmatic Bookshelf},
-      series = {The Facets of Ruby},
-      title = {Programming Ruby 1.9: The Pragmatic Programmers Guide},
-      year = {2009}
-    }
-    > bib[:pickaxe].year
-     => "2009"
-    > bib[:pickaxe][:title]
-     => "Programming Ruby 1.9: The Pragmatic Programmer's Guide"
-    > bib[:pickaxe].author = 'Thomas, D., Fowler, C., and Hunt, A.'
-     => "Thomas, D., and Fowler, C., and Hunt, A."
+    >> require 'bibtex'
+    => true
+    >> b = BibTeX.open('./ruby.bib')
+    >> b[:pickaxe]
+    => "2009"
+    >> b[:pickaxe].title
+    => "Programming Ruby 1.9: The Pragmatic Programmer's Guide"
+    >> b[:pickaxe].author.length
+    => 3
+    >> b[:pickaxe].author.to_s
+    => "Thomas, Dave and Fowler, Chad and Hunt, Andy"
+    >> b[:pickaxe].author[2].first
+    => "Andy"
+    >> b['@book'].length
+    => 3
+    >> b['@article'].length
+    => 0
+    >> bib['@book[year=2009]'].length
+    => 1
 
 
 Installation
@@ -50,24 +50,24 @@ If you want to work with the sources:
     $ [sudo] bundle install
     $ rake racc
     $ rake rdoc
+    $ rake features
     $ rake test
 
-Or, alternatively, fork the [project on GitHub](http://github.com/inukshuk/bibtex-ruby.git).
+For extra credit, fork the
+[project on GitHub](http://github.com/inukshuk/bibtex-ruby.git).
 
 
 Requirements
 ------------
 
 * The parser generator [racc](http://i.loveruby.net/en/projects/racc/) is
-  required to generate parser.
-* The *minitest* gem is required to run the tests in older Ruby versions.
-* The *json* gem is required on older Ruby versions for JSON export.
+  required to generate the BibTeX parser and the name parser.
+* The **json** gem is required on older Ruby versions for JSON export.
 
 The bibtex-ruby gem has been tested on Ruby versions 1.8.7 and 1.9.2; it has
-been confirmed to work with REE 1.8.7 x86_64 and JRuby 1.5.6 x86_64-java. It
-does not work with MacRuby 0.8 because of a bug in MacRuby's implementation
-of the *StringScanner* class, however, this has been fixed in SVN (see
-[#1](https://github.com/inukshuk/bibtex-ruby/issues/closed#issue/1) for details).
+been confirmed to work with REE 1.8.7 x86_64 and JRuby 1.5.6 x86_64-java;
+however, there have been some [issues](https://github.com/inukshuk/bibtex-ruby/issues)
+with MacRuby implementations.
 
 
 
@@ -78,18 +78,15 @@ It is very easy to use BibTeX-Ruby. You can use the top level utility methods
 **BibTeX.open** and **BibTeX.parse** to open a '.bib' file or to parse a string
 containing BibTeX contents. Normally, BibTeX-Ruby will discard all text outside
 of regular BibTeX elements; however, if you wish to include everything, simply add
-`:include => [:meta_comments]` to your invocation of **BibTeX.open** or **BibTeX.parse**.
+`:include => [:meta_content]` to your invocation of **BibTeX.open** or **BibTeX.parse**.
 
 Once BibTeX-Ruby has parsed your '.bib' file, you can easily access individual entries.
 For example, if you set up your bibliography as follows:
 
-    bib = BibTeX.parse <<-END
+    b = BibTeX.parse <<-END
     @book{pickaxe,
       address = {Raleigh, North Carolina},
-      author = {Thomas, Dave, and Fowler, Chad, and Hunt, Andy},
-      date-added = {2010-08-05 09:54:07 +0200},
-      date-modified = {2010-08-05 10:07:01 +0200},
-      keywords = {ruby},
+      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},
@@ -97,20 +94,20 @@ For example, if you set up your bibliography as follows:
     }
     END
     
-You could easily access it, using the entry's key, 'pickaxe', like so: `bib[:pickaxe]`;
-you also have easy access to individual fields, for example: `bib[:pickaxe][:author]`.
+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: `b[:pickaxe][:author]`.
 Alternatively, BibTeX-Ruby accepts ghost methods to conveniently access an entry's fields,
 similar to **ActiveRecord::Base**. Therefore, it is equally possible to access the
-'author' field above as `bib[:pickaxe].author`.
+'author' field above as `b[:pickaxe].author`.
 
-Instead of parsing strings you can also create BibTeX elements by using Ruby:
+Instead of parsing strings you can also create BibTeX elements directly in Ruby:
 
     > bib = BibTeX::Bibliography.new
     > bib << BibTeX::Entry.new({
     >   :type => :book,
-    >   :key => 'rails',
+    >   :key => :rails,
     >   :address => 'Raleigh, North Carolina',
-    >   :author => 'Ruby, Sam, and Thomas, Dave, and Hansson, David Heinemeier',
+    >   :author => 'Ruby, Sam and Thomas, Dave, and Hansson, David Heinemeier',
     >   :booktitle => 'Agile Web Development with Rails',
     >   :edition => 'third',
     >   :keywords => 'ruby, rails',
@@ -121,30 +118,78 @@ Instead of parsing strings you can also create BibTeX elements by using Ruby:
     > })
     > book = BibTeX::Entry.new
     > book.type = :book
-    > book.key = 'mybook'
+    > book.key = :mybook
     > bib << book
 
 
+### Queries
+
+Since version 1.3 BibTeX-Ruby implements a simple query language to search
+Bibliographies via the `Bibliography#query` (or `Bibliography#q`) methods.
+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['@preamble']
+    => Returns all preamble objects (this is the same as Bibliography#preambles) or []
+    >> bib[/ruby/]
+    => Returns all objects that match 'ruby' anywhere or []
+    >> bib['@book[keywords=ruby]']
+    => Returns all books whose keywords attribute equals 'ruby' or []
+    >> 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) }
+
+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
+
 
 ### String Replacement
 
 If your bibliography contains BibTeX @string objects, you can let BibTeX-Ruby
 replace the strings for you. You have access to a bibliography's strings via
-**BibTeX::Bibliography#strings** and you can replace the strings of an entry using
-the **BibTeX::Entry#replace!** method. Thus, to replace all strings defined in your
-bibliography object **bib** your could use this code:
+**BibTeX::Bibliography#strings** or by using a '@string' query.
+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:
 
-    bib.entries.each do |entry|
-      entry.replace!(bib.strings)
+    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_strings` method. Similarly, you can use the
-`Bibliography#join_strings` method to join individual strings together. For instance:
+`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.add BibTeX::Element.parse '@string{ bar = "bar" }'
+    > bib << BibTeX::Element.parse '@string{ bar = "bar" }'
     > bib.add BibTeX::Element.parse <<-END
     >  @book{abook,
     >    author = foo # "Author",
@@ -156,24 +201,50 @@ A shorthand version for replacing all strings in a given bibliography is the
       author = foo # "Author",
       title = foo # bar
     }
-    > bib.replace_strings
+    > bib.replace
     > puts bib[:abook].to_s
     @book{abook,
       author = "foo" # "Author",
       title = "foo" # "bar"
     }
-    > bib.join_strings
+    > bib.join
     @book{abook,
       author = {fooAuthor},
       title = {foobar}
     }
 
+### Names
+
+Since version 1.3, BibTeX-Ruby features a name parser. You can use the top-level
+`BibTeX.names` utility to quickly parse individual name values. Alternatively,
+you can call `Bibliography.parse_names` to convert all name fields contained
+in the bibliography. When parsing BibTeX files, BibTeX-Ruby will automatically
+convert names; if you do not want the names to be parsed you can set the
+`:parse_names` parser option to false.
+
+Note that the string replacement and concatenation features described above
+are not supported for name objects; therefore, BibTeX-Ruby tries to replace
+and join all values before name conversion; name fields containing string
+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"]
+
+
 ### Conversions
 
 Furthermore, BibTeX-Ruby allows you to export your bibliography for processing
 by other tools. Currently supported formats include YAML, JSON, and XML.
 Of course, you can also export your bibliography back to BibTeX; if you include
-`:meta_comments', your export should be identical to the original '.bib' file,
+`:meta_content', your export should be identical to the original '.bib' file,
 except for whitespace, blank lines and letter case (BibTeX-Ruby will downcase
 all keys).
 
@@ -181,126 +252,66 @@ In order to export your bibliography use **#to\_s**, **#to\_yaml**, **#to\_json*
 **#to\_xml**, respectively. For example, the following line constitutes a simple
 BibTeX to YAML converter:
 
-    BibTeX.open('example.bib').to_yaml
+    >> BibTeX.open('example.bib').to_yaml
 
 Look at the 'examples' directory for more elaborate examples of a BibTeX to YAML
 and a BibTeX to HTML converter.
 
-
+BibTeX-Ruby offers an API which lets you manipulate BibTeX objects (string
+replacement, name parsing etc.); however, sometimes you just want quick access
+to your bibliography's contents. In these cases the **to_hash** method is
+useful (use **to_a** if you are only interested in the bibliography's contents):
+it converts all objects into simple Ruby hashes made up of symbols
+and strings. Furthermore, often you would like to control what sort of quotes
+are used in an export;
+therefore, all conversion methods accept an options 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
+    => [{:key=>:pickaxe, :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
+    => [{:key=>:pickaxe, :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
 ----------
 
-The BibTeX-Ruby parser is generated using the wonderful
+The BibTeX-Ruby parser is generated using the awesome
 [racc](http://i.loveruby.net/en/projects/racc/) parser generator. You can take
-look at the grammar definition in the file `lib/bibtex/bibtex.y`.
-
-
-### The BibTeX Format
-
-At first glance, the BibTeX file format seems very clear and simple;
-however, there are a number of peculiarities which warrant some
-explanation. The best place to start reading is probably at [your closest
-ctan server](http://www.ctan.org/get/biblio/bibtex/) where
-the original `bibtex` from 1988 still lives. Additionally, Xavier Decoret
-has written
-[a great summary](http://artis.imag.fr/~Xavier.Decoret/resources/xdkbibtex/bibtex_summary.html)
-of the format; another invaluable source of information is [Nicolas Markey's
-website](http://www.lsv.ens-cachan.fr/~markey/bibla.php). Unfortunately,
-even after consulting these documents, a number of issues remain.
-Therefore, it is the purpose of this section to deliver the rationale
-that went into some of the design decision in BibTeX-Ruby.
-
-A BibTeX bibliography is typically stored in a file with the file
-extension '.bib'. This file may contain any number of BibTeX objects;
-everything that is not a BibTeX object is assumed to be a comment and
-ignored.
-
-The individual objects are discussed in further detail below. First, however, a
-number of general remarks:
-
-* BibTeX-Ruby begins in comment-mode, treating all text it encounters as comments.
-  Normally these comments are ignored; however, if you wish the parser to include
-  them, you can do so by adding the symbol `:meta_comments` to the `:include` array
-  in the parser's options.
-* Note that string literals in BibTeX are either contained in quotes or braces;
-  nested quotes in a quoted literal are not escaped with a usual backslash but
-  must be placed inside braces. Nested braces must be balanced in literals, regardless
-  of whether they are surrounded by quotes or braces.
-* Quoted strings and string constants (which are defined by @string objects) can be
-  concatted by the '#' symbol. String literals in braces can not be concatted in
-  this way.
-* The '@' symbol may only occur in quoted string literals (not in braced out literals)
-  in the original BibTeX; note, however, that this is not true for BibTeX-Ruby (i.e.,
-  it will parse any string containing an '@').
-
-### @comment
-
-
-The purpose of the @comment object is not entirely clear, because everything
-outside of an object is treated as a comment anyway. Nicolas Markay argues that
-a @comment makes it possible to quickly comment out a number of consecutive
-objects; however, as Xavier Decoret points out that this does not work with the
-original `bibtex' program (following a @comment, it simply ignores everything
-until the end of the line). Indeed, on page 13 of [the original
-documentation](http://www.ctan.org/get/biblio/bibtex/contrib/doc/btxdoc.pdf),
-Oren Patashnik explains that @comment objects are not really necessary; they
-exist only for _Scribe_ system compatibility.
-
-Because they would be useless otherwise, BibTeX-Ruby treats @comment objects
-as Nicolas Markay describes them: thus, everything inside a @comment is treated
-as a comment and is ignored -- everything,
-that is, until the object is closed. For this reason, BibTeX-Ruby assumes that
-braces inside a @comment are balanced! Obviously, BibTeX-Ruby differs from
-`bibtex` in that respect; though, the gain is, that it is now possible to
-comment out a sequence of entries, without removing their respective '@' symbols.
-
-### @string
-
-The @string object defines a single string constant (for multiple constant
-assignments, it is necessary to define separate @string objects). These
-constants can be used within string assignments in other @string or @preamble
-objects, as well as in regular BibTeX entries. For example, this is a valid constant
-definition and usage:
-
-    @string{ generator = "BibTeX-Ruby"}
-    @preamble{ "This bibliography was generated by " # generator }
-
-
-### @preamble
-
-Typically, the purpose of @preamble objects is to define LaTeX statements, which
-will be put into the '.bbl' file by `bibtex`. A @preamble object may contain
-a single string literal, a single string constant (defined by a @string object), or
-a concatenation of literals and constants.
-
-### Entries
-
-These represent proper BibTeX objects (e.g., @book, @collection, etc.).
+look at the grammar definition in the file
+[lib/bibtex/bibtex.y](https://github.com/inukshuk/bibtex-ruby/blob/master/lib/bibtex/bibtex.y).
 
+For more information about the BibTeX format and the parser's idiosyncrasies
+[refer to the project wiki](https://github.com/inukshuk/bibtex-ruby/wiki/The-BibTeX-Format).
 
-Credits
--------
-
-The BibTeX-Ruby package was written by [Sylvester Keil](http://sylvester.keil.or.at/),
-with contributions by [Frank Fischer](https://github.com/lyro).
 
-
-License
+Credits
 -------
 
-BibTeX-Ruby
-Copyright (C) 2010-2011 [Sylvester Keil](http://sylvester.keil.or.at)
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this program.  If not, see <http://www.gnu.org/licenses/>.
+The BibTeX-Ruby package was written by [Sylvester Keil](http://sylvester.keil.or.at/);
+kudos and thanks to all [contributors](https://github.com/inukshuk/bibtex-ruby/contributors)!