README.md in rails_dt-0.1.1 vs README.md in rails_dt-0.1.2
- old
+ new
@@ -2,56 +2,91 @@
===================
Introduction
------------
-`rails_dt` gem gives you `DT.p()` method you can use anywhere in your project to print variable dumps, debug messages etc.
+`rails_dt` gem gives you `DT.p()` method you can use anywhere in your project to print your debug messages.
-It's similar to Ruby's native `p()` with output being sent to browser, console and log.
+It's somewhat similar to Ruby's native `p()` with output being sent to log, console and web.
+For example, `DT.p "Hello, world!"` invoked in `RootController` will give you a:
-Setup
------
+ [DT app/controllers/root_controller.rb:3] Hello, world!
- $ gem sources --add http://rubygems.org
- $ gem install rails_dt
-In your application root, do a:
+The Ideas Behind It
+-------------------
- $ script/generate rails_dt
+* Debug message printer must **not require initialization**.
+* Debug message printer must be **nothing else**, but a debug message printer.
+* Debug message printer must be simple and invoked **always the same way** regardless of where you call it from.
+* Debug message printer calls must be **clearly visible** in the code.
+* Debug message printer must **print its location in code** so you can find and modify/remove it as easy as possible.
-Follow the instructions the generator gives you (they are listed below):
+Express Setup (Rails 3)
+-----------------------
+
+In your `Gemfile`, add:
+
+ gem "rails_dt"
+
+Then do a `bundle install`.
+
+This gives you an express (zero-conf) setup, which outputs messages to log, `log/dt.log` and console.
+
+
+Express Setup (Rails 2)
+-----------------------
+
+ $ gem sources --add http://rubygems.org
+ $ gem install rails_dt
+
In your `config/environment.rb`, add:
config.gem "rails_dt"
+
+Setting Up Web Output (Both Rails 3 and Rails 2)
+------------------------------------------------
+
+In your application root, do a:
+
+ $ rails generate rails_dt # Rails 3
+ $ script/generate rails_dt # Rails 2
+
+Follow the instructions the generator gives you then. They are listed below.
+
Inside your `ApplicationController` class, add:
handles_dt
-In your `app/views/layouts/application.html.erb` `<head>` section, add:
+Inside your `app/views/layouts/application.html.erb` `<head>` section, add:
<%= stylesheet_link_tag "dt" %>
-Somewhere at the end of your `app/views/layouts/application.html.erb` `<body>` section, add:
+Inside your `app/views/layouts/application.html.erb` `<body>` section, add:
<div class="DT">
- <%= DT.to_html %>
+ <%= DT.web_messages_as_html %>
</div>
Checking Setup
--------------
Somewhere in your `app/views/layouts/application.html.erb`, add:
- <% DT.p "hello, world" %>
+ <% DT.p "hello, world!" %>
-Refresh a page that uses this layout. You should see "hello, world" beneath your main page content.
+Refresh the page. You should see "hello, world!":
+* In your application log.
+* In `log/dt.log`.
+* On the web page, if you've set it up (see above).
+
Debugging...
------------
### ...Models ###
@@ -87,11 +122,39 @@
$ tail -f log/dt.log
### ...Anything! ###
-To conclude it, `DT.p` is the universal method you can print your debug messages with.
+Just use `DT.p` anywhere you want.
+
+Customizing Output Format
+-------------------------
+
+Create a sample initializer, by doing a:
+
+ $ rails generate rails_dt # Rails 3
+ $ script/generate rails_dt # Rails 2
+
+In `config/initializers/dt.rb` you'll see something like:
+
+ # Customize your DT output.
+ #DT.log_prefix = "[DT <%= file_rel %>:<%= line %>] "
+ #DT.console_prefix = "[DT <%= file_rel %>:<%= line %>] "
+ #DT.web_prefix = '<a href="txmt://open?url=file://<%= file %>&line=<%= line %>"><%= file_rel %>:<%= line %></a> '
+
+Uncomment and edit lines appropriately. Restart server for changes to take effect.
+
+Values are in ERB format. The following macros are available:
+
+* `file` -- full path to file.
+* `file_base` -- file base name.
+* `file_rel` -- file name relative to Rails application root.
+* `line` -- line number.
+
+You can also disable particular output target by setting its prefix to `nil`:
+
+ DT.console_prefix = nil # Disable console output.
Feedback
--------