Rename the rest of the guides to Markdown

1 files changed, 0 insertions, 666 deletions

diff --git a/guides/source/initialization.textile b/guides/source/initialization.textile
deleted file mode 100644
index b23f31cb1a..0000000000
--- a/guides/source/initialization.textile
+++ /dev/null
@@ -1,666 +0,0 @@
-h2. The Rails Initialization Process
-
-This guide explains the internals of the initialization process in Rails
-as of Rails 4. It is an extremely in-depth guide and recommended for advanced Rails developers.
-
-* Using +rails server+
-
-endprologue.
-
-This guide goes through every method call that is
-required to boot up the Ruby on Rails stack for a default Rails 4
-application, explaining each part in detail along the way. For this
-guide, we will be focusing on what happens when you execute +rails
-server+ to boot your app.
-
-NOTE: Paths in this guide are relative to Rails or a Rails application unless otherwise specified.
-
-TIP: If you want to follow along while browsing the Rails "source
-code":https://github.com/rails/rails, we recommend that you use the +t+
-key binding to open the file finder inside GitHub and find files
-quickly.
-
-h3. Launch!
-
-A Rails application is usually started with the command +rails server+.
-
-h4. +bin/rails+
-
-The actual +rails+ command is kept in _bin/rails_:
-
-<ruby>
-#!/usr/bin/env ruby
-
-if File.exists?(File.join(File.expand_path('../../..', __FILE__), '.git'))
-  railties_path = File.expand_path('../../lib', __FILE__)
-  $:.unshift(railties_path)
-end
-require "rails/cli"
-</ruby>
-
-This file will first attempt to push the +railties/lib+ directory if
-present, and then requires +rails/cli+.
-
-h4. +railties/lib/rails/cli.rb+
-
-This file looks like this:
-
-<ruby>
-require 'rbconfig'
-require 'rails/script_rails_loader'
-
-# If we are inside a Rails application this method performs an exec and thus
-# the rest of this script is not run.
-Rails::ScriptRailsLoader.exec_script_rails!
-
-require 'rails/ruby_version_check'
-Signal.trap("INT") { puts; exit(1) }
-
-if ARGV.first == 'plugin'
-  ARGV.shift
-  require 'rails/commands/plugin_new'
-else
-  require 'rails/commands/application'
-end
-</ruby>
-
-The +rbconfig+ file from the Ruby standard library provides us with the +RbConfig+ class which contains detailed information about the Ruby environment, including how Ruby was compiled. We can see this in use in +railties/lib/rails/script_rails_loader+.
-
-<ruby>
-require 'pathname'
-
-module Rails
-  module ScriptRailsLoader
-    RUBY = File.join(*RbConfig::CONFIG.values_at("bindir", "ruby_install_name")) + RbConfig::CONFIG["EXEEXT"]
-    SCRIPT_RAILS = File.join('script', 'rails')
-    ...
-
-  end
-end
-</ruby>
-
-The +rails/script_rails_loader+ file uses +RbConfig::Config+ to obtain the +bin_dir+ and +ruby_install_name+ values for the configuration which together form the path to the Ruby interpreter. The +RbConfig::CONFIG["EXEEXT"]+ will suffix this path with ".exe" if the script is running on Windows. This constant is used later on in +exec_script_rails!+. As for the +SCRIPT_RAILS+ constant, we'll see that when we get to the +in_rails_application?+ method.
-
-Back in +rails/cli+, the next line is this:
-
-<ruby>
-Rails::ScriptRailsLoader.exec_script_rails!
-</ruby>
-
-This method is defined in +rails/script_rails_loader+:
-
-<ruby>
-def self.exec_script_rails!
-  cwd = Dir.pwd
-  return unless in_rails_application? || in_rails_application_subdirectory?
-  exec RUBY, SCRIPT_RAILS, *ARGV if in_rails_application?
-  Dir.chdir("..") do
-    # Recurse in a chdir block: if the search fails we want to be sure
-    # the application is generated in the original working directory.
-    exec_script_rails! unless cwd == Dir.pwd
-  end
-rescue SystemCallError
-  # could not chdir, no problem just return
-end
-</ruby>
-
-This method will first check if the current working directory (+cwd+) is a Rails application or a subdirectory of one. This is determined by the +in_rails_application?+ method:
-
-<ruby>
-def self.in_rails_application?
-  File.exists?(SCRIPT_RAILS)
-end
-</ruby>
-
-The +SCRIPT_RAILS+ constant defined earlier is used here, with +File.exists?+ checking for its presence in the current directory. If this method returns +false+ then +in_rails_application_subdirectory?+ will be used:
-
-<ruby>
-def self.in_rails_application_subdirectory?(path = Pathname.new(Dir.pwd))
-  File.exists?(File.join(path, SCRIPT_RAILS)) || !path.root? && in_rails_application_subdirectory?(path.parent)
-end
-</ruby>
-
-This climbs the directory tree until it reaches a path which contains a +script/rails+ file. If a directory containing this file is reached then this line will run:
-
-<ruby>
-exec RUBY, SCRIPT_RAILS, *ARGV if in_rails_application?
-</ruby>
-
-This is effectively the same as running +ruby script/rails [arguments]+, where +[arguments]+ at this point in time is simply "server".
-
-h3. Rails Initialization
-
-Only now we finally start the real initialization process, beginning
-with +script/rails+.
-
-TIP: If you execute +script/rails+ directly from your Rails app you will
-skip executing all the code that we've just described.
-
-h4. +script/rails+
-
-This file is as follows:
-
-<ruby>
-APP_PATH = File.expand_path('../../config/application',  __FILE__)
-require File.expand_path('../../config/boot',  __FILE__)
-require 'rails/commands'
-</ruby>
-
-The +APP_PATH+ constant will be used later in +rails/commands+. The +config/boot+ file referenced here is the +config/boot.rb+ file in our application which is responsible for loading Bundler and setting it up.
-
-h4. +config/boot.rb+
-
-+config/boot.rb+ contains:
-
-<ruby>
-# Set up gems listed in the Gemfile.
-ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', __FILE__)
-
-require 'bundler/setup' if File.exists?(ENV['BUNDLE_GEMFILE'])
-</ruby>
-
-In a standard Rails application, there's a +Gemfile+ which declares all
-dependencies of the application. +config/boot.rb+ sets
-+ENV['BUNDLE_GEMFILE']+ to the location of this file. If the Gemfile
-exists, +bundler/setup+ is then required.
-
-The gems that a Rails 4 application depends on are as follows:
-
-TODO: change these when the Rails 4 release is near.
-
-* abstract (1.0.0)
-* actionmailer (4.0.0.beta)
-* actionpack (4.0.0.beta)
-* activemodel (4.0.0.beta)
-* activerecord (4.0.0.beta)
-* activesupport (4.0.0.beta)
-* arel (2.0.7)
-* builder (3.0.0)
-* bundler (1.0.6)
-* erubis (2.6.6)
-* i18n (0.5.0)
-* mail (2.2.12)
-* mime-types (1.16)
-* polyglot (0.3.1)
-* rack (1.2.1)
-* rack-cache (0.5.3)
-* rack-mount (0.6.13)
-* rack-test (0.5.6)
-* rails (4.0.0.beta)
-* railties (4.0.0.beta)
-* rake (0.8.7)
-* sqlite3-ruby (1.3.2)
-* thor (0.14.6)
-* treetop (1.4.9)
-* tzinfo (0.3.23)
-
-h4. +rails/commands.rb+
-
-Once +config/boot.rb+ has finished, the next file that is required is +rails/commands+ which will execute a command based on the arguments passed in. In this case, the +ARGV+ array simply contains +server+ which is extracted into the +command+ variable using these lines:
-
-<ruby>
-ARGV << '--help' if ARGV.empty?
-
-aliases = {
-  "g"  => "generate",
-  "d"  => "destroy",
-  "c"  => "console",
-  "s"  => "server",
-  "db" => "dbconsole",
-  "r"  => "runner"
-}
-
-command = ARGV.shift
-command = aliases[command] || command
-</ruby>
-
-TIP: As you can see, an empty ARGV list will make Rails show the help
-snippet.
-
-If we used <tt>s</tt> rather than +server+, Rails will use the +aliases+ defined in the file and match them to their respective commands. With the +server+ command, Rails will run this code:
-
-<ruby>
-when 'server'
-  # Change to the application's path if there is no config.ru file in current dir.
-  # This allows us to run script/rails server from other directories, but still get
-  # the main config.ru and properly set the tmp directory.
-  Dir.chdir(File.expand_path('../../', APP_PATH)) unless File.exists?(File.expand_path("config.ru"))
-
-  require 'rails/commands/server'
-  Rails::Server.new.tap { |server|
-    # We need to require application after the server sets environment,
-    # otherwise the --environment option given to the server won't propagate.
-    require APP_PATH
-    Dir.chdir(Rails.application.root)
-    server.start
-  }
-</ruby>
-
-This file will change into the root of the directory (a path two directories back from +APP_PATH+ which points at +config/application.rb+), but only if the +config.ru+ file isn't found. This then requires +rails/commands/server+ which sets up the +Rails::Server+ class.
-
-<ruby>
-require 'fileutils'
-require 'optparse'
-require 'action_dispatch'
-
-module Rails
-  class Server < ::Rack::Server
-</ruby>
-
-+fileutils+ and +optparse+ are standard Ruby libraries which provide helper functions for working with files and parsing options.
-
-h4. +actionpack/lib/action_dispatch.rb+
-
-Action Dispatch is the routing component of the Rails framework.
-It adds functionalities like routing, session, and common middlewares.
-
-h4. +rails/commands/server.rb+
-
-The +Rails::Server+ class is defined in this file as inheriting from +Rack::Server+. When +Rails::Server.new+ is called, this calls the +initialize+ method in +rails/commands/server.rb+:
-
-<ruby>
-def initialize(*)
-  super
-  set_environment
-end
-</ruby>
-
-Firstly, +super+ is called which calls the +initialize+ method on +Rack::Server+.
-
-h4. Rack: +lib/rack/server.rb+
-
-+Rack::Server+ is responsible for providing a common server interface for all Rack-based applications, which Rails is now a part of.
-
-The +initialize+ method in +Rack::Server+ simply sets a couple of variables:
-
-<ruby>
-def initialize(options = nil)
-  @options = options
-  @app = options[:app] if options && options[:app]
-end
-</ruby>
-
-In this case, +options+ will be +nil+ so nothing happens in this method.
-
-After +super+ has finished in +Rack::Server+, we jump back to +rails/commands/server.rb+. At this point, +set_environment+ is called within the context of the +Rails::Server+ object and this method doesn't appear to do much at first glance:
-
-<ruby>
-def set_environment
-  ENV["RAILS_ENV"] ||= options[:environment]
-end
-</ruby>
-
-In fact, the +options+ method here does quite a lot. This method is defined in +Rack::Server+ like this:
-
-<ruby>
-def options
-  @options ||= parse_options(ARGV)
-end
-</ruby>
-
-Then +parse_options+ is defined like this:
-
-<ruby>
-def parse_options(args)
-  options = default_options
-
-  # Don't evaluate CGI ISINDEX parameters.
-  # http://hoohoo.ncsa.uiuc.edu/cgi/cl.html
-  args.clear if ENV.include?("REQUEST_METHOD")
-
-  options.merge! opt_parser.parse! args
-  options[:config] = ::File.expand_path(options[:config])
-  ENV["RACK_ENV"] = options[:environment]
-  options
-end
-</ruby>
-
-With the +default_options+ set to this:
-
-<ruby>
-def default_options
-  {
-    :environment => ENV['RACK_ENV'] || "development",
-    :pid         => nil,
-    :Port        => 9292,
-    :Host        => "0.0.0.0",
-    :AccessLog   => [],
-    :config      => "config.ru"
-  }
-end
-</ruby>
-
-There is no +REQUEST_METHOD+ key in +ENV+ so we can skip over that line. The next line merges in the options from +opt_parser+ which is defined plainly in +Rack::Server+
-
-<ruby>
-def opt_parser
-  Options.new
-end
-</ruby>
-
-The class *is* defined in +Rack::Server+, but is overwritten in +Rails::Server+ to take different arguments. Its +parse!+ method begins like this:
-
-<ruby>
-def parse!(args)
-  args, options = args.dup, {}
-
-  opt_parser = OptionParser.new do |opts|
-    opts.banner = "Usage: rails server [mongrel, thin, etc] [options]"
-    opts.on("-p", "--port=port", Integer,
-            "Runs Rails on the specified port.", "Default: 3000") { |v| options[:Port] = v }
-  ...
-</ruby>
-
-This method will set up keys for the +options+ which Rails will then be
-able to use to determine how its server should run. After +initialize+
-has finished, we jump back into +rails/server+ where +APP_PATH+ (which was
-set earlier) is required.
-
-h4. +config/application+
-
-When +require APP_PATH+ is executed, +config/application.rb+ is loaded.
-This file exists in your app and it's free for you to change based
-on your needs.
-
-h4. +Rails::Server#start+
-
-After +congif/application+ is loaded, +server.start+ is called. This method is defined like this:
-
-<ruby>
-def start
-  url = "#{options[:SSLEnable] ? 'https' : 'http'}://#{options[:Host]}:#{options[:Port]}"
-  puts "=> Booting #{ActiveSupport::Inflector.demodulize(server)}"
-  puts "=> Rails #{Rails.version} application starting in #{Rails.env} on #{url}"
-  puts "=> Call with -d to detach" unless options[:daemonize]
-  trap(:INT) { exit }
-  puts "=> Ctrl-C to shutdown server" unless options[:daemonize]
-
-  #Create required tmp directories if not found
-  %w(cache pids sessions sockets).each do |dir_to_make|
-    FileUtils.mkdir_p(Rails.root.join('tmp', dir_to_make))
-  end
-
-  unless options[:daemonize]
-    wrapped_app # touch the app so the logger is set up
-
-    console = ActiveSupport::Logger.new($stdout)
-    console.formatter = Rails.logger.formatter
-
-    Rails.logger.extend(ActiveSupport::Logger.broadcast(console))
-  end
-
-  super
-ensure
-  # The '-h' option calls exit before @options is set.
-  # If we call 'options' with it unset, we get double help banners.
-  puts 'Exiting' unless @options && options[:daemonize]
-end
-</ruby>
-
-This is where the first output of the Rails initialization happens. This
-method creates a trap for +INT+ signals, so if you +CTRL-C+ the server,
-it will exit the process. As we can see from the code here, it will
-create the +tmp/cache+, +tmp/pids+, +tmp/sessions+ and +tmp/sockets+
-directories. It then calls +wrapped_app+ which is responsible for
-creating the Rack app, before creating and assigning an
-instance of +ActiveSupport::Logger+.
-
-The +super+ method will call +Rack::Server.start+ which begins its definition like this:
-
-<ruby>
-def start &blk
-  if options[:warn]
-    $-w = true
-  end
-
-  if includes = options[:include]
-    $LOAD_PATH.unshift(*includes)
-  end
-
-  if library = options[:require]
-    require library
-  end
-
-  if options[:debug]
-    $DEBUG = true
-    require 'pp'
-    p options[:server]
-    pp wrapped_app
-    pp app
-  end
-
-  check_pid! if options[:pid]
-
-  # Touch the wrapped app, so that the config.ru is loaded before
-  # daemonization (i.e. before chdir, etc).
-  wrapped_app
-
-  daemonize_app if options[:daemonize]
-
-  write_pid if options[:pid]
-
-  trap(:INT) do
-    if server.respond_to?(:shutdown)
-      server.shutdown
-    else
-      exit
-    end
-  end
-
-  server.run wrapped_app, options, &blk
-end
-</ruby>
-
-The interesting part for a Rails app is the last line, +server.run+. Here we encounter the +wrapped_app+ method again, which this time
-we're going to explore more (even though it was executed before, and
-thus memorized by now).
-
-<ruby>
-@wrapped_app ||= build_app app
-</ruby>
-
-The +app+ method here is defined like so:
-
-<ruby>
-def app
-  @app ||= begin
-    if !::File.exist? options[:config]
-      abort "configuration #{options[:config]} not found"
-    end
-
-    app, options = Rack::Builder.parse_file(self.options[:config], opt_parser)
-    self.options.merge! options
-    app
-  end
-end
-</ruby>
-
-The +options[:config]+ value defaults to +config.ru+ which contains this:
-
-<ruby>
-# This file is used by Rack-based servers to start the application.
-
-require ::File.expand_path('../config/environment',  __FILE__)
-run <%= app_const %>
-</ruby>
-
-
-The +Rack::Builder.parse_file+ method here takes the content from this +config.ru+ file and parses it using this code:
-
-<ruby>
-app = eval "Rack::Builder.new {( " <plus> cfgfile <plus> "\n )}.to_app",
-    TOPLEVEL_BINDING, config
-</ruby>
-
-The +initialize+ method of +Rack::Builder+ will take the block here and execute it within an instance of +Rack::Builder+. This is where the majority of the initialization process of Rails happens. The +require+ line for +config/environment.rb+ in +config.ru+ is the first to run:
-
-<ruby>
-require ::File.expand_path('../config/environment',  __FILE__)
-</ruby>
-
-h4. +config/environment.rb+
-
-This file is the common file required by +config.ru+ (+rails server+) and Passenger. This is where these two ways to run the server meet; everything before this point has been Rack and Rails setup.
-
-This file begins with requiring +config/application.rb+.
-
-h4. +config/application.rb+
-
-This file requires +config/boot.rb+, but only if it hasn't been required before, which would be the case in +rails server+ but *wouldn't* be the case with Passenger.
-
-Then the fun begins!
-
-h3. Loading Rails
-
-The next line in +config/application.rb+ is:
-
-<ruby>
-require 'rails/all'
-</ruby>
-
-h4. +railties/lib/rails/all.rb+
-
-This file is responsible for requiring all the individual frameworks of Rails:
-
-<ruby>
-require "rails"
-
-%w(
-    active_record
-    action_controller
-    action_mailer
-    rails/test_unit
-    sprockets/rails
-).each do |framework|
-  begin
-    require "#{framework}/railtie"
-  rescue LoadError
-  end
-end
-</ruby>
-
-This is where all the Rails frameworks are loaded and thus made
-available to the application. We won't go into detail of what happens
-inside each of those frameworks, but you're encouraged to try and
-explore them on your own.
-
-For now, just keep in mind that common functionality like Rails engines,
-I18n and Rails configuration is all being defined here.
-
-h4. Back to +config/environment.rb+
-
-When +config/application.rb+ has finished loading Rails, and defined
-your application namespace, you go back to +config/environment.rb+,
-where your application is initialized. For example, if you application was called
-+Blog+, here you would find +Blog::Application.initialize!+, which is
-defined in +rails/application.rb+
-
-h4. +railties/lib/rails/application.rb+
-
-The +initialize!+ method looks like this:
-
-<ruby>
-def initialize!(group=:default) #:nodoc:
-  raise "Application has been already initialized." if @initialized
-  run_initializers(group, self)
-  @initialized = true
-  self
-end
-</ruby>
-
-As you can see, you can only initialize an app once. This is also where the initializers are run.
-
-TODO: review this
-
-The initializers code itself is tricky. What Rails is doing here is it
-traverses all the class ancestors looking for an +initializers+ method,
-sorting them and running them. For example, the +Engine+ class will make
-all the engines available by providing the +initializers+ method.
-
-After this is done we go back to +Rack::Server+
-
-h4. Rack: lib/rack/server.rb
-
-Last time we left when the +app+ method was being defined:
-
-<ruby>
-def app
-  @app ||= begin
-    if !::File.exist? options[:config]
-      abort "configuration #{options[:config]} not found"
-    end
-
-    app, options = Rack::Builder.parse_file(self.options[:config], opt_parser)
-    self.options.merge! options
-    app
-  end
-end
-</ruby>
-
-At this point +app+ is the Rails app itself (a middleware), and what
-happens next is Rack will call all the provided middlewares:
-
-<ruby>
-def build_app(app)
-  middleware[options[:environment]].reverse_each do |middleware|
-    middleware = middleware.call(self) if middleware.respond_to?(:call)
-    next unless middleware
-    klass = middleware.shift
-    app = klass.new(app, *middleware)
-  end
-  app
-end
-</ruby>
-
-Remember, +build_app+ was called (by wrapped_app) in the last line of +Server#start+.
-Here's how it looked like when we left:
-
-<ruby>
-server.run wrapped_app, options, &blk
-</ruby>
-
-At this point, the implementation of +server.run+ will depend on the
-server you're using. For example, if you were using Mongrel, here's what
-the +run+ method would look like:
-
-<ruby>
-def self.run(app, options={})
-  server = ::Mongrel::HttpServer.new(
-    options[:Host]           || '0.0.0.0',
-    options[:Port]           || 8080,
-    options[:num_processors] || 950,
-    options[:throttle]       || 0,
-    options[:timeout]        || 60)
-  # Acts like Rack::URLMap, utilizing Mongrel's own path finding methods.
-  # Use is similar to #run, replacing the app argument with a hash of
-  # { path=>app, ... } or an instance of Rack::URLMap.
-  if options[:map]
-    if app.is_a? Hash
-      app.each do |path, appl|
-        path = '/'+path unless path[0] == ?/
-        server.register(path, Rack::Handler::Mongrel.new(appl))
-      end
-    elsif app.is_a? URLMap
-      app.instance_variable_get(:@mapping).each do |(host, path, appl)|
-       next if !host.nil? && !options[:Host].nil? && options[:Host] != host
-       path = '/'+path unless path[0] == ?/
-       server.register(path, Rack::Handler::Mongrel.new(appl))
-      end
-    else
-      raise ArgumentError, "first argument should be a Hash or URLMap"
-    end
-  else
-    server.register('/', Rack::Handler::Mongrel.new(app))
-  end
-  yield server  if block_given?
-  server.run.join
-end
-</ruby>
-
-We won't dig into the server configuration itself, but this is
-the last piece of our journey in the Rails initialization process.
-
-This high level overview will help you understand when your code is
-executed and how, and overall become a better Rails developer. If you
-still want to know more, the Rails source code itself is probably the
-best place to go next.