Merge remote-tracking branch 'upstream/master'

miyagawa · Oct 16, 2012 · ca4e85a · ca4e85a
2 parents 2bc1fe3 + 11abc24
commit ca4e85a
Show file tree

Hide file tree

Showing 62 changed files with 1,583 additions and 328 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,4 @@
-book.*
+book*
+plack-handbook*
 _site
+bin/export_html.rb
diff --git a/00_intro.md b/00_intro.md
diff --git a/01_getting_plack.md b/01_getting_plack.md
diff --git a/02_hello_world.md b/02_hello_world.md
diff --git a/03_using_plackup.md b/03_using_plackup.md
diff --git a/04_reloading_applications.md b/04_reloading_applications.md
diff --git a/05_run_a_static_web_server_with_plack.md b/05_run_a_static_web_server_with_plack.md
diff --git a/06_convert_cgi_apps_to_psgi.md b/06_convert_cgi_apps_to_psgi.md
diff --git a/07_use_web_application_framework_in_psgi.md b/07_use_web_application_framework_in_psgi.md
diff --git a/Makefile b/Makefile
diff --git a/bin/export_html.rb b/bin/export_html.rb
diff --git a/en/00_intro.md b/en/00_intro.md
@@ -0,0 +1,11 @@
+## Introduction
+
+This little handbook is based on the content of the [Plack Advent Calendar](http://advent.plackperl.org/) website. The calendar had 24 useful short posts explaining the concept of PSGI and how to adapt existing web applications to Plack.
+
+The calendar was so successful it's been considered a canonical reference for many beginners trying to learn Plack and for web framework authors trying to adapt their code to work with PSGI.
+
+But the content was written 3 years ago and some of it is a little dated. In this book I tried to get it correct and up-to-date, and it will continue to be updated as we find errata and get feedback from the reader community.
+
+Raw source code of the book, in Markdown format, is available on [GitHub repository](https://github.com/miyagawa/plack-handbook) under the Creative Commons license. See the LICENSE file for details.
+
+2012 September, Tatsuhiko Miyagawa
diff --git a/en/01_getting_plack.md b/en/01_getting_plack.md
@@ -0,0 +1,21 @@
+## Day 1: Getting Plack
+
+The most important step to get started is to install [Plack](http://search.cpan.org/dist/Plack) and other utilities. Because PSGI and Plack are just normal Perl module distributions the installation is easy: just launch your CPAN shell and type:
+
+```
+cpan> install PSGI Plack
+```
+
+[PSGI](http://search.cpan.org/dist/PSGI) is a specification document for the PSGI interface. By installing the distribution you can read the documents in your shell with the `perldoc PSGI` or `perldoc PSGI::FAQ` commands. Plack gives you the standard server implementations, core middleware components, and utilities like plackup and Plack::Test.
+
+Plack doesn't depend on any non-core XS modules so with any Perl distribution later than 5.8.1 (which was released more than 6 years ago!) it can be installed very easily, even on platforms like Win32 or Mac OS X without developer tools (i.e. C compilers).
+
+If you're a developer of web applications or frameworks (I suppose you are!), it's highly recommended you install the optional module bundle [Task::Plack](http://search.cpan.org/dist/Task-Plack) as well. The installation is as easy as typing:
+
+```
+cpan> install Task::Plack
+```
+
+You will be prompted with a couple of questions depending on your environment. If you're unsure whether you should or should not install, just type return to select the default. You'll get optional XS speedups by default, while other options like non-blocking environments are disabled by default.
+
+Start reading the documentation with `perldoc Plack` to get prepared.