Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

`README` fixes: Bundler, detailed per-version setup info.

  • Loading branch information...
commit 39bcc0f81aed292922700498b523a646c9345e60 1 parent 75668fa
Alex Fortuna authored
Showing with 389 additions and 267 deletions.
  1. +1 −6 .gitignore
  2. +0 −158 README.html
  3. +242 −88 README.md
  4. +146 −0 README_RI_CORE.md
  5. +0 −15 Rakefile
View
7 .gitignore
@@ -1,12 +1,7 @@
# General Ruby.
.ref-*
-.ref-*/
-.old/
+.old*
*-old*
-*-old*/
-.proto-*
-.proto-*/
-*.rbx
# Project-specific.
/*.rb
View
158 README.html
@@ -1,158 +0,0 @@
-<head>
- <meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
- <link href="dev/github.css" rel="stylesheet" type="text/css" />
-</head>
-<h1 id="object-oriented-ri-for-irb-console">Object-Oriented RI for IRB Console</h1>
-
-<h2 id="introduction">Introduction</h2>
-
-<p>Finding documentation for Ruby gems and libraries is often time-consuming.
-ORI addresses this issue by bringing RI documentation right to your IRB console in a <strong>simple</strong>, <strong>consistent</strong> and truly <strong>object-oriented</strong> way.</p>
-
-<p>If you’re too lazy to read this README, <a href="http://www.screencast-o-matic.com/watch/cXVVYuXpH">watch this screencast</a> instead.</p>
-
-<h2 id="setup">Setup</h2>
-
-<pre><code>$ gem sources --add http://rubygems.org
-$ gem install ori
-</code></pre>
-
-<p>Add to your <code>~/.irbrc</code>:</p>
-
-<pre><code>require "rubygems"
-require "ori"
-</code></pre>
-
-<h2 id="setup-in-rvm">Setup in RVM</h2>
-
-<p>If you’re using <a href="http://rvm.beginrescueend.com/">RVM</a> (Ruby Version Manager), install the gem into <code>global</code> gemset of Rubies you’re actively using:</p>
-
-<pre><code>$ rvm 1.9.2
-$ rvm gemset use global
-$ gem install ori
-</code></pre>
-
-<h2 id="requirements">Requirements</h2>
-
-<p>It is recommended that you have Ruby &gt;= <strong>1.8.7</strong> and RDoc &gt;= <strong>2.5.3</strong>. Issue reports for older versions will, most probably, be ignored.</p>
-
-<h2 id="usage">Usage</h2>
-
-<p>All commands listed below are assumed to be typed in IRB. Example:</p>
-
-<pre><code>$ irb
-irb&gt; Array.ri
-</code></pre>
-
-<h3 id="request-ri-on-a-class">Request RI on a Class</h3>
-
-<pre><code>Array.ri
-String.ri
-[].ri
-"".ri
-5.ri
-</code></pre>
-
-<p>So that’s fairly straightforward – grab a class or class instance and call <code>ri</code> on it:</p>
-
-<pre><code>obj = SomeKlass.new
-obj.ri
-</code></pre>
-
-<h3 id="request-ri-on-a-method">Request RI on a Method</h3>
-
-<pre><code>String.ri :upcase
-"".ri :upcase
-[].ri :sort
-Hash.ri :[]
-Hash.ri "::[]"
-Hash.ri "#[]"
-</code></pre>
-
-<h3 id="request-interactive-method-list">Request Interactive Method List</h3>
-
-<pre><code># Regular expression argument denotes list request.
-String.ri //
-"".ri //
-
-# Show method names matching a regular expression.
-"".ri /case/
-"".ri /^to_/
-[].ri /sort/
-{}.ri /each/
-
-# Show ALL methods, including those private of Kernel.
-Hash.ri //, :all =&gt; true
-Hash.ri //, :all
-
-# Show class methods or instance methods only.
-Module.ri //, :access =&gt; "::"
-Module.ri //, :access =&gt; "#"
-
-# Show own methods only.
-Time.ri //, :own =&gt; true
-Time.ri //, :own
-
-# Specify visibility: public, protected or private.
-Module.ri //, :visibility =&gt; :private
-Module.ri //, :visibility =&gt; [:public, :protected]
-
-# Filter fully formatted name by given regexp.
-Module.ri //, :fullre =&gt; /\(Object\)::/
-
-# Combine options.
-Module.ri //, :fullre =&gt; /\(Object\)::/, :access =&gt; "::", :visibility =&gt; :private
-</code></pre>
-
-<h3 id="request-interactive-method-list-for-more-than-1-object-at-once">Request Interactive Method List for More Than 1 Object at Once</h3>
-
-<p>By using the <code>:join</code> option it’s possible to fetch methods for more
-than 1 object at once. Value of <code>:join</code> (which can be an object or an array)
-is joined with the original receiver, and then a combined set is queried.</p>
-
-<pre><code># List all division-related methods from numeric classes.
-Fixnum.ri /div/, :join =&gt; [Float, Rational]
-5.ri /div/, :join =&gt; [5.0, 5.to_r]
-
-# List all ActiveSupport extensions to numeric classes.
-5.ri //, :join =&gt; [5.0, 5.to_r], :fullre =&gt; /ActiveSupport/
-
-# Query entire Rails family for methods having the word "javascript".
-rails_modules = ObjectSpace.each_object(Module).select {|mod| mod.to_s.match /Active|Action/}
-"".ri /javascript/, :join =&gt; rails_modules
-</code></pre>
-
-<h2 id="configuration">Configuration</h2>
-
-<p>You can configure ORI via <code>ORI.conf</code> object. By default it’s autoconfigured based on your OS and environment.</p>
-
-<pre><code># Enable color.
-ORI.conf.color = true
-
-# RI frontend command to use. `%s` is replaced with sought topic.
-ORI.conf.frontend = "ri -T -f ansi %s"
-
-# Paging program to use.
-ORI.conf.pager = "less -R"
-</code></pre>
-
-<h2 id="compatibility">Compatibility</h2>
-
-<p>Prior to publication, ORI gem has been thoroughly tested on:</p>
-
-<ul>
- <li>Ruby 1.9.2-p0 under Linux with RVM</li>
- <li>Ruby 1.8.7-p302 under Linux with RVM</li>
- <li>Ruby 1.8.7-p72 under Cygwin</li>
- <li>Ruby 1.8.7-p72 under 32-bit Windows Vista</li>
-</ul>
-
-<h2 id="copyright">Copyright</h2>
-
-<p>Copyright © 2011 Alex Fortuna.</p>
-
-<p>Licensed under the MIT License.</p>
-
-<h2 id="feedback">Feedback</h2>
-
-<p>Send bug reports, suggestions and criticisms through <a href="http://github.com/dadooda/ori">project’s page on GitHub</a>.</p>
View
330 README.md
@@ -1,127 +1,276 @@
-Object-Oriented RI for IRB Console
-==================================
+Object-oriented `ri` for IRB console
+====================================
-Introduction
-------------
+
+* [Introduction](#introduction)
+* [Setup](#setup)
+ * [Regular setup](#regular_setup)
+ * [RVM setup](#rvm_setup)
+ * [Rails 3.x+Bundler setup](#rails_3_bundler_setup)
+* [Configuration](#configuration)
+* [Compatibility](#compatibility)
+* [Copyright](#copyright)
+* [Feedback](#feedback)
+
+
+<a name="introduction" /> Introduction
+--------------------------------------
Finding documentation for Ruby gems and libraries is often time-consuming.
-ORI addresses this issue by bringing RI documentation right to your IRB console in a **simple**, **consistent** and truly **object-oriented** way.
+ORI addresses this issue by bringing `ri` documentation right to your IRB console in a **simple**, **consistent** and truly **object-oriented** way.
If you're too lazy to read this README, [watch this screencast](http://www.screencast-o-matic.com/watch/cXVVYuXpH) instead.
-Setup
------
+<a name="setup" /> Setup
+------------------------
+
+[Click here](#usage) to skip the boring setup part and see live examples right away.
+
+### Pre-setup (test your environment)
+
+1. Check your Ruby version. Should be at least **1.8.7**.
+
+ ~~~
+ $ ruby -v
+ ruby 1.9.2p290 (2011-07-09 revision 32553) [i686-linux]
+ ~~~
+
+2. Check your `ri` version. Should be at least version **2.5**:
+
+ ~~~
+ $ ri --version
+ ri 2.5.8
+ ~~~
+
+3. Check if core `ri` documentation is available:
+
+ ~~~
+ $ ri Array.each
+ ~~~
- $ gem sources --add http://rubygems.org
- $ gem install ori
+ You should see the doc article. If you see `Nothing known about Array`, **you are missing the core `ri` documentation**. To set it up, please follow the steps from [README_RI_CORE](/dadooda/ori/blob/master/README_RI_CORE.md).
+
+
+### <a name="regular_setup" /> Regular setup ###
+
+Install the gem:
+
+~~~
+$ gem sources --add http://rubygems.org
+$ gem install ori
+~~~
Add to your `~/.irbrc`:
- require "rubygems"
- require "ori"
+~~~
+require "rubygems"
+require "ori"
+~~~
+
+Test:
+
+~~~
+$ irb
+irb> Array.ri //
+irb> Array.ri :each
+~~~
-Setup in RVM
-------------
+### <a name="rvm_setup" /> RVM setup ###
+
+Under Ruby Version Manager ([RVM](http://rvm.beginrescueend.com/)), install the gem into `global` gemset of Ruby versions you're using:
+
+~~~
+$ rvm 1.9.2
+$ rvm gemset use global
+$ gem install ori
+~~~
+
+Add to your `~/.irbrc`:
+
+~~~
+require "rubygems"
+require "ori"
+~~~
-If you're using [RVM](http://rvm.beginrescueend.com/) (Ruby Version Manager), install the gem into `global` gemset of Rubies you're actively using:
+Test:
- $ rvm 1.9.2
- $ rvm gemset use global
- $ gem install ori
+~~~
+$ irb
+irb> Array.ri //
+irb> Array.ri :each
+~~~
-Requirements
-------------
+### <a name="rails_3_bundler_setup" /> Rails 3.x+Bundler setup ###
-It is recommended that you have Ruby >= **1.8.7** and RDoc >= **2.5.3**. Issue reports for older versions will, most probably, be ignored.
+Start by stepping into your Rails project directory:
+~~~
+$ cd myrailsproject
+~~~
-Usage
------
+Tell Bundler to include the `rdoc` gem in `:development` environment. Add to your `Gemfile`:
+
+~~~
+group :development do
+ gem "rdoc"
+end
+~~~
+
+Test:
+
+~~~
+$ ri Array.each
+$ bundle exec ri Array.each
+~~~
+
+You should see the doc article in **both** cases.
+
+And finally:
+
+~~~
+$ rails console
+>> Array.ri :each
+~~~
+
+#### Further important Bundler information ####
+
+At the moment of this writing (2012-01-09) `bundle install` installs gems without `ri` documentation and it's not possible to change this behavior.
+
+It means that you need to **manually re-install** the gems for which you need `ri` documentation. Example:
+
+~~~
+$ rails console
+>> ActiveRecord::Base.ri :validate
+No articles found
+~~~
+
+The above means that Rails components have been installed via `bundle install` and have no `ri` documentation. Let's fix it:
+
+~~~
+$ grep rails Gemfile
+gem "rails", "3.0.7"
+$ gem install rails -v 3.0.7
+~~~
+
+Rails gems are now re-installed, let's try again:
+
+~~~
+$ rails console
+>> ActiveRecord::Base.ri :validate
+ActiveModel::Validations::ClassMethods#validate
+
+(from gem activemodel-3.0.7)
+------------------------------------------------------------------------------
+ validate(*args, &block)
+
+------------------------------------------------------------------------------
+
+Adds a validation method or block to the class. This is useful when overriding
+the validate instance method becomes too unwieldy and you're looking
+for more descriptive declaration of your validations.
+...
+~~~
+
+Seems to work now.
+
+
+<a name="usage" /> Usage
+------------------------
All commands listed below are assumed to be typed in IRB. Example:
- $ irb
- irb> Array.ri
+~~~
+$ irb
+irb> Array.ri
+~~~
-### Request RI on a Class ##
+### Request `ri` on a class ###
- Array.ri
- String.ri
- [].ri
- "".ri
- 5.ri
+It's fairly straightforward -- grab a class or class instance and call `ri` on it:
-So that's fairly straightforward -- grab a class or class instance and call `ri` on it:
+~~~
+Array.ri
+String.ri
+[].ri
+"".ri
+ar = Array.new
+ar.ri
+~~~
- obj = SomeKlass.new
- obj.ri
+### Request `ri` on a method ###
-### Request RI on a Method ###
+~~~
+String.ri :upcase
+"".ri :upcase
+[].ri :each
+Hash.ri :[]
+Hash.ri "::[]"
+Hash.ri "#[]"
+~~~
- String.ri :upcase
- "".ri :upcase
- [].ri :sort
- Hash.ri :[]
- Hash.ri "::[]"
- Hash.ri "#[]"
+### Request interactive method list ###
-### Request Interactive Method List ###
+Interactive method list lets you explore the particular class or object by listing the methods it actually has. This powerful feature is my personal favorite. Try it once and you'll like it, too.
- # Regular expression argument denotes list request.
- String.ri //
- "".ri //
+~~~
+# Regular expression argument denotes list request.
+String.ri //
+"".ri //
- # Show method names matching a regular expression.
- "".ri /case/
- "".ri /^to_/
- [].ri /sort/
- {}.ri /each/
+# Show method names matching a regular expression.
+"".ri /case/
+"".ri /^to_/
+[].ri /sort/
+{}.ri /each/
- # Show ALL methods, including those private of Kernel.
- Hash.ri //, :all => true
- Hash.ri //, :all
+# Show own methods only.
+Time.ri //, :own => true
+Time.ri //, :own
- # Show class methods or instance methods only.
- Module.ri //, :access => "::"
- Module.ri //, :access => "#"
+# Show ALL methods, including those private of Kernel.
+Hash.ri //, :all => true
+Hash.ri //, :all
- # Show own methods only.
- Time.ri //, :own => true
- Time.ri //, :own
+# Show class methods or instance methods only.
+Module.ri //, :access => "::"
+Module.ri //, :access => "#"
- # Specify visibility: public, protected or private.
- Module.ri //, :visibility => :private
- Module.ri //, :visibility => [:public, :protected]
+# Specify visibility: public, protected or private.
+Module.ri //, :visibility => :private
+Module.ri //, :visibility => [:public, :protected]
- # Filter fully formatted name by given regexp.
- Module.ri //, :fullre => /\(Object\)::/
+# Filter fully formatted name by given regexp.
+Module.ri //, :fullre => /\(Object\)::/
- # Combine options.
- Module.ri //, :fullre => /\(Object\)::/, :access => "::", :visibility => :private
+# Combine options.
+Module.ri //, :fullre => /\(Object\)::/, :access => "::", :visibility => :private
+~~~
-### Request Interactive Method List for More Than 1 Object at Once ###
+### Request interactive method list for more than 1 object at once ###
By using the `:join` option it's possible to fetch methods for more
than 1 object at once. Value of `:join` (which can be an object or an array)
is joined with the original receiver, and then a combined set is queried.
- # List all division-related methods from numeric classes.
- Fixnum.ri /div/, :join => [Float, Rational]
- 5.ri /div/, :join => [5.0, 5.to_r]
+~~~
+# List all division-related methods from numeric classes.
+Fixnum.ri /div/, :join => [Float, Rational]
+5.ri /div/, :join => [5.0, 5.to_r]
- # List all ActiveSupport extensions to numeric classes.
- 5.ri //, :join => [5.0, 5.to_r], :fullre => /ActiveSupport/
+# List all ActiveSupport extensions to numeric classes.
+5.ri //, :join => [5.0, 5.to_r], :fullre => /ActiveSupport/
- # Query entire Rails family for methods having the word "javascript".
- rails_modules = ObjectSpace.each_object(Module).select {|mod| mod.to_s.match /Active|Action/}
- "".ri /javascript/, :join => rails_modules
+# Query entire Rails family for methods having the word "javascript".
+rails_modules = ObjectSpace.each_object(Module).select {|mod| mod.to_s.match /Active|Action/}
+"".ri /javascript/, :join => rails_modules
+~~~
-Configuration
--------------
+<a name="configuration" /> Configuration
+----------------------------------------
You can configure ORI via `ORI.conf` object. By default it's autoconfigured based on your OS and environment.
@@ -135,26 +284,31 @@ You can configure ORI via `ORI.conf` object. By default it's autoconfigured base
ORI.conf.pager = "less -R"
-Compatibility
--------------
+<a name="compatibility" /> Compatibility
+----------------------------------------
+
+Tested to run on:
-Prior to publication, ORI gem has been thoroughly tested on:
+* Ruby 1.9.3-p0, Linux, RVM
+* Ruby 1.9.2-p290, Linux, RVM
+* Ruby 1.9.2-p0, Linux, RVM
+* Ruby 1.8.7-p352, Linux, RVM
+* Ruby 1.8.7-p302, Linux, RVM
+* Ruby 1.8.7-p72, Windows, Cygwin
+* Ruby 1.8.7-p72, Windows
-* Ruby 1.9.2-p0 under Linux with RVM
-* Ruby 1.8.7-p302 under Linux with RVM
-* Ruby 1.8.7-p72 under Cygwin
-* Ruby 1.8.7-p72 under 32-bit Windows Vista
+Compatibility issue reports will be greatly appreciated.
-Copyright
----------
+<a name="copyright" /> Copyright
+--------------------------------
-Copyright &copy; 2011 Alex Fortuna.
+Copyright &copy; 2011-2012 Alex Fortuna.
Licensed under the MIT License.
-Feedback
---------
+<a name="feedback" /> Feedback
+------------------------------
Send bug reports, suggestions and criticisms through [project's page on GitHub](http://github.com/dadooda/ori).
View
146 README_RI_CORE.md
@@ -0,0 +1,146 @@
+Setting up core `ri` documentation for your version of Ruby
+===========================================================
+
+
+All versions, general procedure
+-------------------------------
+
+* Compile and install Ruby without ri/rdoc documentation.
+* Install the latest `rdoc` gem before you install any other gems.
+* Generate `ri` documentation using the latest `rdoc` gem.
+* Test if `ri` documentation is installed correctly.
+
+
+RVM
+---
+
+### 1.9.x ###
+
+Install, select, switch to `global` gemset:
+
+~~~
+$ rvm install 1.9.2
+$ rvm 1.9.2
+$ rvm gemset use global
+~~~
+
+Although not absolutely required (the default version 2.5 works fairly well), I still recommend to install the most recent `rdoc` gem:
+
+~~~
+$ gem install rdoc
+~~~
+
+Generate and install the docs (takes a while):
+
+~~~
+$ rvm docs generate
+~~~
+
+Test:
+
+~~~
+$ ri Array.each
+~~~
+
+
+### 1.8.x ###
+
+Install, select, switch to `global` gemset:
+
+~~~
+$ rvm install 1.8.7
+$ rvm 1.8.7
+$ rvm gemset use global
+~~~
+
+Now install the most recent `rdoc` gem. For 1.8 you **must** do it since the default version is slow, buggy, and uses the outdated data storage format:
+
+~~~
+$ gem install rdoc
+~~~
+
+Generate and install the docs (takes a while):
+
+~~~
+$ rvm docs generate
+~~~
+
+Test:
+
+~~~
+$ ri Array.each
+~~~
+
+
+Non-RVM, from source
+--------------------
+
+### 1.9.x ###
+
+`rdoc` 2.5 shipped with Ruby 1.9 seems to do the job. No tweaking is required, just build and install:
+
+~~~
+$ make
+$ make install
+~~~
+
+Test:
+
+~~~
+$ ri Array.each
+~~~
+
+
+### 1.8.x ###
+
+If installed with `make install` by default, `ri` documentation will be generated in an outdated format, which is no longer supported. Please follow these steps to generate the documentation correctly.
+
+Unpack source:
+
+~~~
+$ tar xjvf ruby-1.8.7-p352.tar.bz2
+~~~
+
+Build:
+
+~~~
+$ cd ruby-1.8.7-p352
+$ ./configure
+$ make
+~~~
+
+Install without doc:
+
+~~~
+$ make install-nodoc
+~~~
+
+Install the latest rdoc gem:
+
+~~~
+$ gem install rdoc
+~~~
+
+Now fix `Makefile` to use the new rdoc generator instead of the shipped one. Replace the line:
+
+~~~
+$(RUNRUBY) "$(srcdir)/bin/rdoc" --all --ri --op "$(RDOCOUT)" "$(srcdir)"
+~~~
+
+with:
+
+~~~
+rdoc --all --ri --op "$(RDOCOUT)" "$(srcdir)"
+~~~
+
+Generate and install the docs:
+
+~~~
+$ make install-doc
+~~~
+
+Test:
+
+~~~
+$ ri Array.each
+~~~
View
15 Rakefile
@@ -36,21 +36,6 @@ task :push do
Kernel.system("gem", "push", pkgfile)
end
-desc "Generate README.html"
-task :readme do
- require "kramdown"
-
- doc = Kramdown::Document.new(File.read "README.md")
-
- fn = "README.html"
- puts "Writing '#{fn}'..."
- File.open(fn, "w") do |f|
- f.write(File.read "dev/head.html")
- f.write(doc.to_html)
- end
- puts ": ok"
-end
-
desc "Generate rdoc documentation"
Rake::RDocTask.new(:rdoc) do |rdoc|
rdoc.rdoc_dir = "doc"
Please sign in to comment.
Something went wrong with that request. Please try again.