5. Chapter 1
Introduction
This is a sample document for what will become the Ruby on Rails Tutorial book. It is by no means a real
book yet—there’s even some lorem ipsum text in what follows (see, e.g., Box 1.1 and Chapter 2). Its purpose
is to show that all the elements are in place to produce a pleasing final product, and to give a hint of what that
final product might eventually look like.
Box 1.1. Cicero dixit
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et
dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex
ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Ex-
cepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
1.1 Technology
Rails Tutorial is written in PolyTEXnic, a dialect of the LTEX technical typesetting system (which in turn
A
is based on TEX). I wrote PolyTEXnic because I wanted to produce both beautiful PDF (and hence print)
documents and pretty HTML documents at the same time, from the same source file. As a result, this
sample document is available both as HTML and as a PDF download. Both formats come with plenty of rich
book-y goodness, including a linked table of contents; numbered sections, tables, figures, and code listings;
linked cross references; syntax highlighting; numbered, shaded sidebars (Box 1.1); footnotes1 ; and even math
(Section 1.4).
Currently, PolyTEXnic is only available for my private use, but I plan to release it as an open-source
project once it’s battle-tested and ready for general consumption.
1 Like this.
5
6. 6 CHAPTER 1. INTRODUCTION
1.2 Sample code and such
Often, Rails books include lots of code samples and such. Let’s look at some examples of how PolyTEXnic
makes them both useful and pretty.
1.2.1 Code samples
We’ll likely have some Ruby code in our Rails tutorial, with snippets such as the following:
Listing 1.1. Part of the ClassMethods module in ActiveRecord::Validations.
module ClassMethods
.
.
.
# File rails-2.3.2/activerecord/lib/active_record/validations.rb, line 511
def validates_presence_of(*attr_names)
configuration = { :on => :save }
configuration.update(attr_names.extract_options!)
# can’t use validates_each here, because it cannot cope with
# nonexistent attributes, while errors.add_on_empty can
send(validation_method(configuration[:on]), configuration) do |record|
record.errors.add_on_blank(attr_names, configuration[:message])
end
end
.
.
.
end
Note that Listing 1.1 is both syntax-highlighted and numbered—and, as you can see, it can be cross-
referenced as well.
Of course, we’re not limited to vanilla Ruby; let’s also include some embedded Ruby:
Listing 1.2. The index.html.erb file for the People controller.
<%- column_div :type => :primary do -%>
<% unless @people.empty? -%>
<h2>People</h2>
<%= will_paginate %>
<ul class="list people">
<%= render :partial => @people %>
</ul>
<%= will_paginate %>
<% end -%>
<%- end -%>
<%- column_div :type => :secondary do -%>
7. 1.3. FIGURES AND TABLES 7
<%= render :partial => ’searches/box’ %>
<%= render :partial => ’shared/minifeed’ %>
<%- end -%>
In fact, we can include code in virtually any language and get nice syntax highlighting for free via the
excellent Pygments program:
;; Common Lisp
;; Return the square of the given number.
(defun square (x)
"Calculates the square of the single-float x."
(declare (single-float x) (optimize (speed 3) (debug 0) (safety 1)))
(* x x))
Note here that we have a nice highlighted code block, but no listing number. This is useful for short
snippets that aren’t likely ever to be referenced.
1.2.2 And such
Code isn’t everything; sometimes you just want to show shell commands. No problem:
$ rake -T db
(in /Users/mhartl/rails/rails_tutorial)
rake backup:db # Backup the current database.
rake db:avatars:delete # Delete all the avatars.
rake db:avatars:load # Make sample avatars.
.
.
.
We can also include console sessions:
>> a = 1
=> 1
>> puts a
1
=> nil
1.3 Figures and tables
It’s easy to include figures, such as screenshots (Fig. 1.1). (These are particularly useful for a tutorial.) We
can also make tables. I don’t have nice styling yet, but you get the idea (Table 1.1).
8. 8 CHAPTER 1. INTRODUCTION
Figure 1.1: A screenshot of the Rails Tutorial site.
Foo bar Baz Quux
foo bar baz quux
Table 1.1: An ugly table.
9. 1.4. MATH 9
1.4 Math
While LTEX is great for writing a programming book, DocBook might have worked as well, and rumor has
A
it DocBook can be converted to HTML. So why bother writing my own system? I went with LTEX for two
A
main reasons:
1. I don’t know DocBook, but I know LTEX well, so I could be confident in being able to hack something
A
together.
2. LTEX is great at math typesetting.
A
Though I expect Rails Tutorial will have little or no math, eventually I’d like to use this system to write
math-heavy articles and books, and DocBook can’t do math typesetting. So, in reality, the second consid-
eration alone was decisive, and—if you care about math typesetting—it’s not hard to see why; consider,
for example, the exponential decay factor e−t/τ , or the time-independent Schr¨ dinger equation in quantum
o
mechanics:
¯2
h 2
− +V ψ = Eψ
2m
Both these math examples look great by construction in the PDF version of this document (since LTEX is a
A
master math typesetter), but if you’re viewing them on the web you’ll see that they look great there, too.
How does this work? I began with the only place I’d seen nice math typesetting on the web: Wikipedia’s
math articles.2 This had always been a mystery, because all the nice math typesetting I’d ever seen was
produced by LTEX(or by TEX itself). So how does Wikipedia do it? Well, Wikipedia is built on top of
A
MediaWiki, and MediaWiki comes bundled with a program called texvc that converts wiki math markup to
pretty PNGs using—wait for it—LTEX. So PolyTEXnic, like MediaWiki, just uses texvc under the hood.3
A
2 Not quite true: MathWorld looks nice, too, but it’s closed-source.
3 Ifyou look at the MediaWiki source to find out how it does math conversion, you’ll see that it’s literally just a shell call to texvc,
so that’s what I did as well.
11. Chapter 2
Lorem ipsum
We certainly expect to have more than one chapter in this book. Here’s the start of a second one.
2.1 Lorem
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et
dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex
ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat
nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim
id est laborum.
Listing 2.1. The Forum model.
# == Schema Information
# Schema version: 20080916002106
#
# Table name: forums
#
# id :integer(4) not null, primary key
# name :string(255)
# description :text
# topics_count :integer(4) default(0), not null
# created_at :datetime
# updated_at :datetime
#
class Forum < ActiveRecord::Base
attr_accessible :name, :description
has_many :topics, :order => "created_at DESC", :dependent => :destroy
has_many :posts, :through => :topics
validates_length_of :name, :maximum => 255, :allow_nil => true
11
12. 12 CHAPTER 2. LOREM IPSUM
validates_length_of :description, :maximum => 1000, :allow_nil => true
end
2.2 Ipsum
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et
dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex
ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat
nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim
id est laborum.
