Permalink
Browse files

New system based on asciidoc, chapters still need proper ordering, bu…

…t this is very promising
  • Loading branch information...
1 parent 2ec5483 commit 35aad070e346ed23db4c2addd78fd25f171cd314 @manveru committed Apr 1, 2009
Showing with 381 additions and 36 deletions.
  1. +36 −0 README.markdown
  2. +46 −0 Rakefile
  3. +2 −0 chapter/attributes.txt
  4. +127 −0 chapter/ch01.txt
  5. 0 chapter/{ramaze-session.mkd → ch02.txt}
  6. 0 chapter/{basic-usage.mkd → ch03.txt}
  7. 0 chapter/{configuration.mkd → ch04.txt}
  8. 0 chapter/{ramaze-action.mkd → ch05.txt}
  9. 0 chapter/{ramaze-adapter.mkd → ch06.txt}
  10. 0 chapter/{ramaze-controller.mkd → ch07.txt}
  11. 0 chapter/{ramaze-current.mkd → ch08.txt}
  12. 0 chapter/{ramaze-helper.mkd → ch09.txt}
  13. 0 chapter/{ramaze-installation.mkd → ch10.txt}
  14. 0 chapter/{ramaze-request.mkd → ch11.txt}
  15. 0 chapter/{ramaze-response.mkd → ch12.txt}
  16. +66 −0 chapter/ch13.txt
  17. 0 chapter/{ramaze-template.mkd → ch14.txt}
  18. 0 chapter/{ramaze-trinity.mkd → ch15.txt}
  19. 0 chapter/{security.mkd → ch16.txt}
  20. +0 −10 chapter/head.mkd
  21. +0 −25 chapter/introduction.mkd
  22. +52 −0 chapter/preface.txt
  23. 0 { → chapter}/source/action/create_an_action_1.rb
  24. 0 { → chapter}/source/action/render_an_action_1.rb
  25. 0 { → chapter}/source/adapter/create_own_adapter.rb
  26. 0 { → chapter}/source/adapter/create_your_own_adapter_1.rb
  27. 0 { → chapter}/source/adapter/mongrel.rb
  28. 0 { → chapter}/source/adapter/thin.rb
  29. 0 { → chapter}/source/controller/change_mapping.rb
  30. 0 { → chapter}/source/controller/default_mapping_1.rb
  31. 0 { → chapter}/source/controller/main_controller.rb
  32. 0 { → chapter}/source/export_env
  33. 0 { → chapter}/source/global/directory_convention_inspect.rb
  34. 0 { → chapter}/source/global/various_source.rb
  35. +1 −1 { → chapter}/source/hello_world.rb
  36. 0 { → chapter}/source/helper/exposing_methods_to_routing.rb
  37. 0 { → chapter}/source/helper/simley_helper_1.rb
  38. 0 { → chapter}/source/helper/using_helper_1.rb
  39. 0 { → chapter}/source/session/what_are_sessions_1.rb
  40. +12 −0 custom.conf
  41. +39 −0 journey_to_ramaze.txt
View
@@ -17,3 +17,39 @@ developer and passionate Rubyist.
The source is kept in a git repository at
[github](http://github.com/manveru/ramaze-book)
+
+## Building
+
+This book is written in AsciiDoc format, this allows for a number of target
+formats.
+The Rakefile contains instructions to build following formats:
+
+* chunked html
+* dvi
+* htmlhelp
+* manpage
+* pdf
+* ps
+* tex
+* text
+* xhtml
+
+If you invoke `rake`, the default being built is xhtml, see `rake -T` for a
+list of all possible tasks.
+
+See below for instructions on how to install the required dependencies on
+different distributions.
+
+To get proper syntax highlighting you will need to install
+[GNU source-highlight](http://www.gnu.org/software/src-highlite/).
+This usually is available in repositories.
+
+You will also need the DocBook XML scheme 4.5 and DocBook XML stylesheets
+installed.
+
+The dblatex package is required for generation of pdf, tex, ps, and dvi.
+
+### Installation of dependencies
+#### ArchLinux
+
+ pacman -S asciidoc dblatex source-highlight
View
@@ -0,0 +1,46 @@
+require 'rake/clean'
+require 'fileutils'
+
+task :default => 'build:xhtml'
+
+JTR_TXT = "journey_to_ramaze.txt"
+JTR_XML = "journey_to_ramaze.xml"
+SOURCE_FILES = Dir['chapter/*.txt']
+formats = %w[chunked htmlhelp manpage pdf text xhtml dvi ps tex]
+
+OPTS = [
+ "--asciidoc-opts=--conf-file=custom.conf",
+ "--asciidoc-opts=--verbose",
+ "--doctype=book",
+ '--icons',
+ '--copy',
+ '--verbose',
+]
+
+file JTR_XML => [JTR_TXT, *SOURCE_FILES] do
+ sh('asciidoc', '-v', '-b', 'docbook', '-d', 'book', '-f', 'custom.conf', JTR_TXT)
+end
+
+formats.each do |format|
+ dest = format.dup
+ jtr_file = "#{dest}/journey_to_ramaze.#{format}"
+
+ desc "Build #{jtr_file}"
+ task "build:#{format}" => jtr_file
+
+ file jtr_file => [dest, JTR_XML] do
+ opts = OPTS + [
+ "--destination-dir=#{dest}",
+ "--format=#{format}",
+ "-s",
+ JTR_XML,
+ ]
+
+ sh("a2x", *opts)
+ end
+
+ file(dest){ FileUtils.mkdir(dest) }
+ CLOBBER.include(dest)
+end
+
+CLOBBER.include('journey_to_ramaze.xml')
View
@@ -0,0 +1,2 @@
+:ruby-lang: http://ruby-lang.org[the official Ruby programming language website]
+:ch-developing: <<X400,developing Ramaze>>
View
@@ -0,0 +1,127 @@
+= Tutorial introduction to Ramaze
+== Installation
+
+The easiest way to get to know Ramaze is by example, so we will start out with
+that, covering installation and a few simple applications so you can get a
+feeling for it.
+
+In order to use Ramaze, you will have to install it on your system.
+This is usually fairly straight-forward.
+
+First of all we need to install Ruby, then Ramaze.
+
+=== Installing Ruby
+
+Since Ramaze is written in the Ruby programming language, which doesn't ship by
+default with most systems, you will have to install it first.
+
+For this book we assume an installation of Ruby 1.9.x, which ships with
+RubyGems, the package manager for ruby libraries and applications.
+
+The reasoning behind using 1.9.x is that this book might take some time to get
+finished, by then I hope that all major development in Ruby will happen on the
+basis of the 1.9 spec.
+
+You can obtain Ruby from {ruby-lang}, they have instructions for installation
+on most systems.
+Linux users can simply use their package manager to install Ruby.
+
+
+=== Installing Ramaze
+
+Once Ruby is installed correctly, you can install Ramaze simply by:
+
+[source,sh]
+--------------------------------------------------------------------------------
+gem install ramaze
+--------------------------------------------------------------------------------
+
+This will take care of installing all dependencies as well.
+There are a lot of libraries that we will install in the course of this book,
+but installing them is usually just a command away, so we defer it to when we
+actually need them.
+
+Ramaze is a project that is developed in an open manner by the community.
+In order to work together we utilize git for revision control. You can obtain
+your own copy of the repository if you are interested in helping the
+development or simply would like to browse through the project history.
+We will cover this subject in {ch-developing}.
+
+== Hello, World!
+
+A short introductory example is always "Hello world". In Ramaze this looks like
+following.
+
+[source,ruby]
+--------------------------------------------------------------------------------
+include::source/hello_world.rb[tabsize=2]
+--------------------------------------------------------------------------------
+
+First we require RubyGems, the package managing wrapper that allows us to
+require the ramaze library and framework. Next we define a Controller and
+method that will show up when accessing 'http://localhost:7000/', `7000` being
+the default port of Ramaze.
+
+To start this application we can now simply:
+
+[source,sh]
+--------------------------------------------------------------------------------
+ruby start.rb
+--------------------------------------------------------------------------------
+
+That will start an instance of Ruby and start the WEBrick HTTP server that
+ships with Ruby.
+
+This will output something along the lines of:
+
+[source,sh]
+--------------------------------------------------------------------------------
+delta ~/c/ramaze-book;master % ruby19 source/hello_world.rb
+W [2009-04-01 15:35:24 $17562] WARN | : No explicit root folder found, assuming it is source
+D [2009-04-01 15:35:24 $17562] DEBUG | : Using webrick
+I [2009-04-01 15:35:24 $17562] INFO | : WEBrick 1.3.1
+I [2009-04-01 15:35:24 $17562] INFO | : ruby 1.9.2 (2009-03-02) [i686-linux]
+D [2009-04-01 15:35:24 $17562] DEBUG | : TCPServer.new(0.0.0.0, 7000)
+D [2009-04-01 15:35:24 $17562] DEBUG | : Rack::Handler::WEBrick is mounted on /.
+I [2009-04-01 15:35:24 $17562] INFO | : WEBrick::HTTPServer#start: pid=17562 port=7000
+--------------------------------------------------------------------------------
+
+Now you can open your browser, and go to http://localhost:7000/.
+
+Sometimes you will get an error when starting Ramaze that looks like:
+
+[source,sh]
+--------------------------------------------------------------------------------
+/usr/lib/ruby19/1.9.1/webrick/utils.rb:73:in `initialize': Address already in use - bind(2) (Errno::EADDRINUSE)
+ from /usr/lib/ruby19/1.9.1/webrick/utils.rb:73:in `new'
+ from /usr/lib/ruby19/1.9.1/webrick/utils.rb:73:in `block in create_listeners'
+ from /usr/lib/ruby19/1.9.1/webrick/utils.rb:70:in `each'
+ from /usr/lib/ruby19/1.9.1/webrick/utils.rb:70:in `create_listeners'
+ from /usr/lib/ruby19/1.9.1/webrick/server.rb:74:in `listen'
+ from /usr/lib/ruby19/1.9.1/webrick/server.rb:62:in `initialize'
+ from /usr/lib/ruby19/1.9.1/webrick/httpserver.rb:24:in `initialize'
+ from /home/manveru/c/rack/lib/rack/handler/webrick.rb:9:in `new'
+ from /home/manveru/c/rack/lib/rack/handler/webrick.rb:9:in `run'
+ from /home/manveru/c/innate/lib/innate/adapter.rb:66:in `start_webrick'
+ from /home/manveru/c/innate/lib/innate/adapter.rb:40:in `start'
+ from /home/manveru/c/innate/lib/innate.rb:139:in `start!'
+ from /home/manveru/c/innate/lib/innate.rb:135:in `start'
+ from source/hello_world.rb:10:in `<main>'
+zsh: exit 1 ruby19 source/hello_world.rb
+--------------------------------------------------------------------------------
+
+This means that you already have a server running on this port, and you will
+have to use another port to run your application or shutdown the application
+occupying the port.
+
+If you don't know what is running on this port, you can find out by using the
+'lsof' command (on Linux).
+
+[source,sh]
+--------------------------------------------------------------------------------
+delta ~/c/ramaze-book;master % lsof -i -P
+COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
+ruby19 17806 manveru 3u IPv4 462149 0t0 TCP *:7000 (LISTEN)
+--------------------------------------------------------------------------------
+
+With this information you know the Process ID, and can, for example `kill 17806`.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
View
@@ -0,0 +1,66 @@
+# Ramaze::Session
+
+Sessions are an essential part of most dynamic web applications and so Ramaze makes it very simple to use them. We will see how to use the automated sessions, handle cookies manually and change the backend where session information is stored on the serverside.
+
+## What are sessions
+
+Although I said that they are essential, some people may not yet be familiar with sessions and what use cases exist for them, so let's take a look at a simple application using sessions first.
+
+
+ require 'ramaze'
+
+ class MainController < Ramaze::Controller
+ HELLO = {
+ 'en' => "Hello, world!",
+ 'de' => "Hallo Welt!",
+ 'it' => "Ciao, mondo!",
+ }
+
+ def index
+ language = HELLO.keys.sort_by{ rand }.first
+ session[:language] = language
+ redirect Rs(:greet)
+ end
+
+ def greet
+ HELLO[session[:language]]
+ end
+ end
+{:ruby}
+
+
+In this, we select a random language key that we then set in our session. The browser that hits the index action will from now on always have this language associated to it and you can see it in your controller and templates inside the session object.
+
+Now a few details on how this works exactly.
+
+
+
+On every request, as we mentioned in the chapter about Ramaze::Current already, a Session is initialized and put into `Ramaze::STATE[:session]`. This makes it possible to access the session during the whole request. The initialization will set a cookie in the current response, setting the key `_ramaze_session_id` with a unique value representing the key to the data stored on the server.
+
+Cookies are basically a part of the response headers, a simple string that is being sent back and forth during the request/response cycle. Everytime a browser sends a request it will also send the cookie in the header with it, that way we can look up which data belongs to that browser.
+
+In Ramaze this data is stored in a cache, at the time of writing the two most commonly used ones are MemcachedCache and MemoryCache.
+
+
+
+Although they may sound similar, they are quite different concepts, MemoryCache equals a Ruby Hash, it doesn't put any restrains on the kind or amount of data stored, which can become problematic for larger applications. MemcachedCache on the other hand utilizes the MemCache library to communicate with an (usually) local memcache daemon that handles caching of key/value pairs in namespaces. It allows you to control the way caching happens very well, one commonly used option is to put a limit on the overall amount of data stored. However, old data is thrown away if your application tries to cache more data than allowed.
+
+There is a third way which was contributed recently, to utilize the Sequel ORM and use a relational database for storage, which gives both control and persistence as old data is never thrown away unless explicitly ordered to do so.
+
+## Configuration
+
+A number of options lets you decide how to use sessions and their behaviour.
+
+To disable them, simply assign:
+
+ Ramaze::Global.sessions = false
+{:ruby}
+
+This will give you some speedup and less data being transferred between server and client, it does not affect the ability to manually set cookies in the response.
+
+To change the backend for the session cache only (as opposed to it for all caches in your Ramaze, we talk about that in the Ramaze::Cache section) do following:
+
+ Ramaze::Global.cache_alternative[:sessions] = Ramaze::MemcachedCache
+{:ruby}
+
+Please make sure you have the memcached server running before starting an application with this setting.
File renamed without changes.
File renamed without changes.
File renamed without changes.
View
@@ -1,10 +0,0 @@
-# Ramaze
-
-## About Ramaze
-
-Ramaze is a simple but powerful web application development framework. This book is an in-depth walk-through of Ramaze's features and behaviour.
-
-* This list will contain the table of contents
-{:toc}
-
-[Introduction](/introduction)
View
@@ -1,25 +0,0 @@
-# Introduction
-
-## About Ramaze
-
-Ramaze is a modular web application framework. It provides you with just about everything you need to make your daily web development simple and fun. Making programming fun is a concept popularized by the Ruby programming language.
-
-Ramaze is written in Ruby. This document assumes at least basic knowledge about Ruby. If you do not know what Ruby is yet, visit [ruby] and find out; but beware, it may change your life.
-
-### Important Links
-
-Naturally, since Ramaze is an open source web framework, most help can be found online (apart from reading the source code itself). So here are some links to provide more information on all the topics covered in this book.
-
-* [Ramaze] provides further documentation, screencasts, links and news.
-* [Ramaze google group] hosts the mailing list for discussion with the developers and users of the framework.
-* [Github ramaze] hosts the source. Ramaze is freely available under the [Ruby license].
-
-## About the author
-
-Michael Fellinger (a.k.a. manveru) is the creator and core developer of the Ramaze framework.
-
-His programming language of choice is, as you might have guessed already, Ruby, having worked with it since 2005.
-
-Michael has been living in Tokyo, Japan since 2006, but is of Austrian nationality, speaking German, English and currently learning Japanese.
-
-You can reach him by mailing to <m.fellinger@gmail.com>
View
@@ -0,0 +1,52 @@
+Preface
+=======
+
+Ramaze is a simple but powerful web application development framework. This
+book is an in-depth walk-through of Ramaze's features and behaviour.
+
+Ramaze is a modular web application framework.
+It provides you with just about everything you need to make your daily web
+development simple and fun.
+Making programming fun is a concept popularized by the Ruby programming
+language.
+
+It is written in Ruby. This book assumes at least basic knowledge about
+Ruby.
+If you do not know what Ruby is yet, visit http://ruby-lang.org[ruby-lang.org],
+the official website for the Ruby programming language and find out; but
+beware, it may change your life.
+
+It features a readable open source codebase licensed under the Ruby license
+(optionally GPL version 2).
+
+The strengths of Ramaze, as described by its users, are a free style of
+development, affording all the benefits of the underlying Ruby programming
+language. It gets out of your way as you do things, helping you along as you
+require it.
+
+Important links
+~~~~~~~~~~~~~~~
+
+Naturally, since Ramaze is an open source web framework, most help can be found
+on the web.
+Some links to provide more information on all the topics covered in this book.
+
+* http://ramaze.net[ramaze.net] is the official homepage for the Ramaze project.
+* http://ramaze.googlegroups.com[The mailing list] where most developers using
+ Ramaze are subscribed and share help and information.
+* http://github.com/manveru/ramaze[Ramaze on Github] provides immediate access
+ to the source and commit-history of the project.
+
+About the author
+~~~~~~~~~~~~~~~
+
+Michael Fellinger (a.k.a. manveru) is the creator and core developer of the
+Ramaze framework.
+
+His programming language of choice is, as you might have guessed already, Ruby,
+having worked with it since 2005.
+
+Michael has been living in Tokyo, Japan since 2006, but is of Austrian
+nationality, speaking German, English and currently learning Japanese.
+
+You can reach him by mailing to <m.fellinger@gmail.com>
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -1,7 +1,7 @@
require 'rubygems'
require 'ramaze'
-class MainController < Ramaze::Controller
+class Hello < Ramaze::Controller
def index
"Hello, World"
end
View
@@ -0,0 +1,12 @@
+[attributes]
+encoding=UTF-8
+textwidth=80
+tabsize=2
+pagewidth=425
+toc_title=Table of Contents
+newline=\n
+iconsdir=./images/icons
+
+[header-declarations]
+<?xml version="1.0" encoding="{encoding}"?>
+<!DOCTYPE {doctype-article?article}{doctype-book?book}{doctype-manpage?refentry} PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "/usr/share/xml/docbook/xml-dtd-4.5/docbookx.dtd">
Oops, something went wrong.

0 comments on commit 35aad07

Please sign in to comment.