Added advanced server command and a mini-generator tutorial.

1 files changed, 129 insertions, 10 deletions

diff --git a/railties/guides/source/command_line.textile b/railties/guides/source/command_line.textile
index 259cfb5bb9..788629617b 100644
--- a/railties/guides/source/command_line.textile
+++ b/railties/guides/source/command_line.textile
@@ -8,7 +8,7 @@ Rails comes with every command line tool you'll need to
 * Mess with objects through an interactive shell
 * Profile and benchmark your new creation
 
-This tutorial assumes you have basic Rails knowledge from reading the Getting Started with Rails Guide.
+NOTE: This tutorial assumes you have basic Rails knowledge from reading the "Getting Started with Rails Guide":getting_started.html.
 
 endprologue.
 
@@ -28,7 +28,7 @@ h4. rails
 
 The first thing we'll want to do is create a new Rails application by running the +rails+ command after installing Rails.
 
-NOTE: You know you need the rails gem installed by typing +gem install rails+ first, right? Okay, okay, just making sure.
+WARNING: You know you need the rails gem installed by typing +gem install rails+ first, right? Okay, okay, just making sure.
 
 <shell>
 $ rails commandsapp
@@ -46,15 +46,15 @@ $ rails commandsapp
 
 Rails will set you up with what seems like a huge amount of stuff for such a tiny command! You've got the entire Rails directory structure now with all the code you need to run our simple application right out of the box.
 
-NOTE: This output will seem very familiar when we get to the +generate+ command. Creepy foreshadowing!
+INFO: This output will seem very familiar when we get to the +generate+ command. Creepy foreshadowing!
 
 h4. server
 
 Let's try it! The +server+ command launches a small web server named WEBrick which comes bundled with Ruby. You'll use this any time you want to view your work through a web browser.
 
-NOTE: WEBrick isn't your only option for serving Rails. We'll get to that in a later section. [XXX: which section]
+INFO: WEBrick isn't your only option for serving Rails. We'll get to that in a later section.
 
-Without any prodding of any kind, `server` will run our new shiny Rails app:
+Without any prodding of any kind, +server+ will run our new shiny Rails app:
 
 <shell>
 $ cd commandsapp
@@ -95,7 +95,7 @@ Using generators will save you a large amount of time by writing *boilerplate co
 
 Let's make our own controller with the controller generator. But what command should we use? Let's ask the generator:
 
-NOTE: All Rails console utilities have help text. As with most *NIX utilities, you can try adding +--help+ or +-h+ to the end, for example +./script/server --help+.
+INFO: All Rails console utilities have help text. As with most *NIX utilities, you can try adding +--help+ or +-h+ to the end, for example +./script/server --help+.
 
 <shell>
 $ ./script/generate controller
@@ -166,7 +166,7 @@ $ ./script/server
 
 The URL will be +http://localhost:3000/greetings/hello+. I'll wait for you to be suitably impressed.
 
-NOTE: With a normal, plain-old Rails application, your URLs will generally follow the pattern of http://(host)/(controller)/(action), and a URL like http://(host)/(controller) will hit the *index* action of that controller.
+INFO: With a normal, plain-old Rails application, your URLs will generally follow the pattern of http://(host)/(controller)/(action), and a URL like http://(host)/(controller) will hit the *index* action of that controller.
 
 "What about data, though?", you ask over a cup of coffee. Rails comes with a generator for data models too. Can you guess its generator name?
 
@@ -229,7 +229,7 @@ Taking it from the top - the generator checks that there exist the directories f
 
 The migration requires that we *migrate*, that is, run some Ruby code (living in that +20081217071914_create_high_scores.rb+) to modify the schema of our database. Which database? The sqlite3 database that Rails will create for you when we run the +rake db:migrate+ command. We'll talk more about Rake in-depth in a little while.
 
-NOTE: Hey. Install the sqlite3-ruby gem while you're at it. +gem install sqlite3-ruby+
+CAUTION: Hey. Install the sqlite3-ruby gem while you're at it. +gem install sqlite3-ruby+
 
 <shell>
 $ rake db:migrate
@@ -240,7 +240,7 @@ $ rake db:migrate
   CreateHighScores: migrated (0.0077s)
 </shell>
 
-NOTE: Let's talk about unit tests. Unit tests are code that tests and makes assertions about code. In unit testing, we take a little part of code, say a method of a model, and test its inputs and outputs. Unit tests are your friend. The sooner you make peace with the fact that your quality of life will drastically increase when you unit test your code, the better. Seriously. We'll make one in a moment.
+INFO: Let's talk about unit tests. Unit tests are code that tests and makes assertions about code. In unit testing, we take a little part of code, say a method of a model, and test its inputs and outputs. Unit tests are your friend. The sooner you make peace with the fact that your quality of life will drastically increase when you unit test your code, the better. Seriously. We'll make one in a moment.
 
 Let's see the interface Rails created for us. ./script/server; http://localhost:3000/high_scores
 
@@ -389,4 +389,123 @@ development:
 ...
 </shell>
 
-It also generated some lines in our database.yml configuration corresponding to our choice of PostgreSQL for database. The only catch with using the SCM options is that you have to make your application's directory first, then initialize your SCM, then you can run the `rails` command to generate the basis of your app.
+It also generated some lines in our database.yml configuration corresponding to our choice of PostgreSQL for database. The only catch with using the SCM options is that you have to make your application's directory first, then initialize your SCM, then you can run the +rails+ command to generate the basis of your app.
+
+h4. server with different backends
+
+Many people have created a large number different web servers in Ruby, and many of them can be used to run Rails. Since version 2.3, Rails uses Rack to serve its webpages, which means that any webserver that implements a Rack handler can be used. This includes WEBrick, Mongrel, Thin, and Phusion Passenger (to name a few!).
+
+NOTE: For more details on the Rack integration, see "Rails on Rack":rails_on_rack.html.
+
+To use a different server, just install its gem, then use its name for the first parameter to +script/server+:
+
+<shell>
+$ sudo gem install mongrel
+Building native extensions.  This could take a while...
+Building native extensions.  This could take a while...
+Successfully installed gem_plugin-0.2.3
+Successfully installed fastthread-1.0.1
+Successfully installed cgi_multipart_eof_fix-2.5.0
+Successfully installed mongrel-1.1.5
+...
+...
+Installing RDoc documentation for mongrel-1.1.5...
+$ script/server mongrel
+=> Booting Mongrel (use 'script/server webrick' to force WEBrick)
+=> Rails 2.2.0 application starting on http://0.0.0.0:3000
+...
+</shell>
+
+h4. The Rails Generation: Generators
+
+INFO: For a good rundown on generators, see "Understanding Generators":http://wiki.rubyonrails.org/rails/pages/UnderstandingGenerators. A lot of its material is presented here.
+
+Generators are code that generates code. Let's experiment by building one. Our generator will generate a text file.
+
+The Rails generator by default looks in these places for available generators, where RAILS_ROOT is the root of your Rails application, like /home/foobar/commandsapp:
+
+* RAILS_ROOT/lib/generators
+* RAILS_ROOT/vendor/generators
+* Inside any plugin with a directory like "generators" or "rails_generators"
+* ~/.rails/generators
+* Inside any Gem you have installed with a name ending in "_generator"
+* Inside *any* Gem installed with a "rails_generators" path, and a file ending in "_generator.rb"
+* Finally, the builtin Rails generators (controller, model, mailer, etc.)
+
+Let's try the fourth option (in our home directory), which will be easy to clean up later:
+
+<shell>
+$ mkdir -p ~/.rails/generators/tutorial_test/templates
+$ touch ~/.rails/generators/tutorial_test/templates/tutorial.erb
+$ touch ~/.rails/generators/tutorial_test/tutorial_test_generator.rb
+</shell>
+
+We'll fill +tutorial_test_generator.rb+ out with:
+
+<ruby>
+class TutorialTestGenerator < Rails::Generator::Base
+  def initialize(*runtime_args)
+    super(*runtime_args)
+    @tut_args = runtime_args
+  end
+  
+  def manifest
+    record do |m|
+      m.directory "public"
+      m.template "tutorial.erb", File.join("public", "tutorial.txt"),
+        :assigns => { :args => @tut_args }
+    end
+  end
+end
+</ruby>
+
+We take whatever args are supplied, save them to an instance variable, and literally copying from the Rails source, implement a +manifest+ method, which calls +record+ with a block, and we:
+
+* Check there's a *public* directory. You bet there is.
+* Run the ERb template called "tutorial.erb".
+* Save it into "RAILS_ROOT/public/tutorial.txt".
+* Pass in the args we saved through the +:assign+ parameter.
+
+Next we'll build the template:
+
+<shell>
+$ cat ~/.rails/generators/tutorial_test/templates/tutorial.erb 
+I'm a template!
+
+I got assigned some args: 
+<%= require 'pp'; PP.pp(args, "") %>
+</shell>
+
+Then we'll make sure it got included in the list of available generators:
+
+<shell>
+$ ./script/generate
+...
+...
+Installed Generators
+  User: tutorial_test
+</shell>
+
+SWEET! Now let's generate some text, yeah!
+
+<shell>
+$ ./script/generate tutorial_test arg1 arg2 arg3
+      exists  public
+      create  public/tutorial.txt
+</shell>
+
+And the result:
+
+<shell>
+$ cat public/tutorial.txt 
+I'm a template!
+
+I got assigned some args: 
+[["arg1", "arg2", "arg3"],
+ {:collision=>:ask,
+  :quiet=>false,
+  :generator=>"tutorial_test",
+  :command=>:create}]
+</shell>
+
+Tada!
\ No newline at end of file