Being that this is your first time using BlueCloth, you're not exactly sure how to use it. You need some API documentation to get started. Fortunately, with the addition of the --rdoc option to the install command, RubyGems will generate RDoc documentation for the gem it is installing.
% gem install -r BlueCloth --rdoc
Having generated all this useful HTML documentation, how can you view it? You have at least two options. The hard way (though it really isn't hard) is to open RubyGems' documentation directory and browse the documentation directly. As with most things in Rubygems, the documentation for each gem is stored in a central, protected, Rubygems-specified place. This will vary by system and by where you may explicity choose to install you gems. The most realiable way to find the documents is to ask the gem command where your RubyGems main directory is located. For example:
% gem enviroment gemdir
/usr/local/lib/ruby/gems/1.8
RubyGems stores generated documentation in the doc/ subdirectory of this directory, in this case /usr/local/lib/ruby/gems/1.8.7/doc. You can open the file index.html and view the documentation. If you find yourself using this path often, you can create a shortcut.Here's one way to do that on Mac Os X boxes.
% gemdoc=`gem enviroment gemdir `/doc
% ls $gemdoc
BlueCloth-0.0.4
% open $gemdoc/BlueCloth-0.0.4/rdoc/index.html
To save time, you could declare $gemdoc in your login shell's profile or rc file.
The second (and easier) way to views gems, Rdoc documentation is to use RubyGems' included gem_server utility. To start gem_server, simply type
%gem_server
gem_server starts a Web server running on whatever computer you can run it on. By default, it will start on port 8808 and will serve gems and their documentation from the default RubyGems installion directory. Both the port and the gem directory are overridable via command-line options, using the -p and -d options, respectively.
Once you've started the gem_server program, if you are running it in your local computer, you can access the documentation for your installed gems by pointing your Web browser to http://localhost:8808. There, you will see a list of the gems you have installed with their description and links to their Rdoc documentation.
Now you've got BlueCloth installed and you know how to use it, you're ready to write some code. Having used to RubyGems to download the library, we can now also use it to load the library components into our application. Prior to RubyGems, we'd say something like
require 'bluecloth'
With RubyGems, though, we can take advantage of its packaging and versioning support. To do this, we use require_gem in place of require.
require 'rubygems'
require_gem 'BlueCloth' , ''>= 0.0.4"
doc = BlueCloth::new
This line adds the BlueCloth gem to Ruby's $LOAD_PATH and users require to load any libraries that's the gem's creator specified to be autoloaded. Lets's say that again a slightly different way.
Each gem is consider to be bundle of resources. It may contain one library file or a one hundred. In an old-fashioned, non-RubyGems library, all these files would be copied into some shared location in the Ruby library tree, a location that was in Ruby's predefined load path.
RubyGems doesn't work this way. Instead, it keeps each version of each gem in its own self-contained directory tree. The gems are not injected into the standard Ruby library directories. As a result, RubyGems needs to do some fancy footwork so that you can get to these files. It does this by adding the gems's directory tree to ruby's load path. From inside a running program, the effect is the same: require just works. From the outside, though, RubyGems gives you far better control over what's loaded into your Ruby programs.
In the case of BlueCloth, the templating code is distributed as one file, bluecloth.rb; that's the file that require_gem will load. require_gem has an optional second argument, which specifies a version requirement. In this example, you've specified that BlueCloth version 0.0.4 or greater be installed to use this code. If you had required version 0.0.5 or greater, this program would fail, because the version you've just installed is too low to meet the requirement of the program.
require 'rubygems'
require_gem 'BlueCloth ' , '>= 0.0.5'
As i said earlier, the version requirement argument is optional, and this example is obviously contrived. But, its easy to imagine how this features can be useful as different projects begin to depend on multiple, potentially incompatible, versions of the same library.
