README in console-0.2.3 vs README in console-0.3

@@ -1,22 +1,51 @@
 Console is a helper class for displaying super-ASCII strings on the console.
 
-Console is needed when you want to mix multi-column (e.g. Chinese, Japanese and
-Korean characters) and single-column (e.g. ASCII) characters and know how much
-horizontal realestate the result takes on the screen. This is generally
-necessary when you want to have internationalization support in a console
-program.
+Console is necessary when you want to mix multi-column (e.g.  Chinese, Japanese
+and Korean characters) and single-column (e.g. ASCII, Latin, Vietnamese)
+characters on screen in such a way that the display width matters. This is
+typically the case in curses programs with i18n support, but can be necessary
+in certain internationalized $stdout applications as well.
 
+Note that display width is different from a) the number of bytes in the string,
+and b) the number of characters in the string. When you move beyond ASCII
+strings, these three metrics can all have distinct values for a given string.
+
 The Console gem currently provides these methods:
 
+- Console.init_locale!: set the program's locale from the appropriate
+  environment variables. (Ruby 1.8 programs must call this before calling any
+  of the other methods. Ruby 1.9 programs can call it or skip it without
+  effect.)
 - Console.display_width: calculates the display width of a string
 - Console.display_slice: returns a substring according to display offset
   and display width parameters.
 
 If you require 'console', you will get just those methods.
 
 If you require 'console/string', you will get String#display_width and
 String#display_slice methods directly on all strings.
 
-The console homepage is <code>http://masanjin.net/console/</code>.
+= EXAMPLE USAGE
 
+  ## encoding: UTF-8 (this comment required for ruby 1.9)
+  require 'rubygems' # this line required for ruby 1.8
+  require 'console'
+  require 'console/string'
+
+  Console.init_locale!
+
+  STRING = "我能吞下玻璃而不傷身體。Góa ē-tàng chia̍h po-lê, mā bē tio̍h-siong.私はガラスを食べられます。それは私を傷つけません。I can eat glass and it doesn't hurt me."
+  COLS = 30
+
+  rows = STRING.display_width / COLS
+  (0 .. rows).each { |i| puts STRING.display_slice(i * COLS, COLS) }
+
+The result will be displayed in an even 30-column block on the console, even
+though some characters in the string require two columns to display and some
+characters require one column.
+
+= MORE
+
+The console homepage is <code>http://masanjin.net/console/</code>.
 The console git repo is <code>git://masanjin.net/console</code>.
+