README.md in csl-1.0.0.pre23 vs README.md in csl-1.0.0
- old
+ new
@@ -1,10 +1,10 @@
CSL-Ruby
========
-CSL-Ruby is a Ruby parser and library for the Citation Style Language (CSL),
-an XML-based format to describe the formatting of citations, notes and
-bibliographies.
+CSL-Ruby provides a Ruby parser and a comprehensive API for the
+[Citation Style Language](http://citationstyles.org) (CSL), an XML-based
+format to describe the formatting of citations, notes and bibliographies.
[](http://travis-ci.org/inukshuk/csl-ruby)
Styles and Locales
------------------
@@ -18,19 +18,106 @@
You can change these locations by changing the value of `CSL::Style.root` and
`CSL::Locale.root` respectively.
Alternatively, you can `gem install csl-styles` to install all official CSL
-styles and locales.
+styles and locales. To make the styles and locales available, simply
+`require 'csl/styles`.
+Usage
+-----
+CSL-Ruby is broadly aimed at two very different usage scenarios: on the one
+hand, you can use the parser to load existing styles and locales and
+manipulate, query or otherwise work with them using a dedicated API: that is
+to say, you do not have to resort to XML-related methods of access, but can
+make use of a large set of library methods which are specific to CSL. This
+is useful, primarily, for citation processors like
+[CiteProc-Ruby](https://github.com/inukshuk/citeproc-ruby).
+
+On the other hand, CSL-Ruby makes it easy to create new styles and locales
+using Ruby; this is useful, for example, if you need to change or adapt
+styles on-the-fly or for writing an interactive style editor.
+
+To get you started, here are a few usage examples; for the full set of
+available features, please consult the
+[API documentation](http://rubydoc.info/gems/csl/).
+
+ require 'csl'
+
+ # Load a style from the Zotero style repository
+ jps = CSL::Style.load 'http://zotero.org/styles/american-journal-of-political-science'
+
+ # Query style information
+ jps.title #-> "American Journal of Political Science"
+ jps.independent? #-> true
+ jps.citation_format #-> :"author-date"
+
+ # Validate style against the CSL schema
+ jps.valid? #-> true
+
+ # Load another style
+ amc = CSL::Style.load 'http://zotero.org/styles/applied-mathematics-and-computation'
+
+ amc.independent? #-> false
+
+ # Load the independent parent style
+ parent = amc.independent_parent
+ parent.title #-> "Elsevier (numeric, with titles)"
+
+ # Load standard CSL styles and locales from csl-styles gem
+ # Requires you to gem install csl-styles
+ require 'csl/styles'
+
+ # Load a locally installed style
+ apa = CSL::Style.load :apa
+
+ # Fetch the a macro
+ authors = apa.macros['authors'].children[0]
+ #-> #<CSL::Style::Names variable="author" children=[2]>
+
+ # Load a locally installed locale
+ fr = CSL::Locale.load :fr
+
+ # Translate a term
+ fr.translate 'editor' #-> "éditeur"
+ fr.translate 'editor', plural: true #-> "éditeurs"
+ fr.translate 'editor', form: 'short' #-> "éd."
+
+ # Ordinalize a number
+ fr.ordinalize 42 #=> "42ᵉ"
+ fr.ordinalize 3, form: 'long' => "troisième"
+
+ # Create a new style
+ style = CSL::Style.new
+
+ style.id = 'http://www.zotero.org/styles/my-style'
+ style.title = 'My Style'
+
+ # Add the default license for CSL styles
+ style.default_license!
+
+ # Access the style as XML
+ style.to_xml
+
+ # Access the style as XML (pretty printed)
+ style.to_s
+
+Dependencies
+------------
+CSL-Ruby was written with portability in mind. For performance reasons it
+will use [Nokogiri ](http://nokogiri.org) for XML parsing and validation
+if available; however, CSL-Ruby will fallback to REXML from the Ruby standard
+library. In order to use Nokogiri, simply `gem install nokogiri` or add it
+to your Gemfile.
+
Development
-----------
The CSL-Ruby source code is [hosted on GitHub](https://github.com/inukshuk/csl-ruby).
You can check out a copy of the latest code using Git:
$ git clone https://github.com/inukshuk/csl-ruby.git
-
+
To get started, install the development dependencies and run all tests:
$ cd csl-ruby
$ bundle install
$ rake
@@ -41,12 +128,12 @@
example, fix the bug and submit a pull request.
Copyright
---------
-Copyright 2012 President and Fellows of Harvard College.
-
Copyright 2009-2013 Sylvester Keil. All rights reserved.
+Copyright 2012 President and Fellows of Harvard College.
+
License
-------
-CiteProc is dual licensed under the AGPL and the FreeBSD license.
+CSL-Ruby is dual licensed under the AGPL and the FreeBSD license.