From: Matt S Trout <mst@shadowcat.co.uk>
Date: Sat, 25 Mar 2006 19:32:46 +0000 (+0000)
Subject: Doc updates from the jester
X-Git-Tag: 5.7099_04~661
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=commitdiff_plain;h=56d8daebfb3b83c215625ae0fd3fddce455851c6

Doc updates from the jester
---

diff --git a/lib/Catalyst/Manual/About.pod b/lib/Catalyst/Manual/About.pod
index 60c8354..de2690c 100644
--- a/lib/Catalyst/Manual/About.pod
+++ b/lib/Catalyst/Manual/About.pod
@@ -18,7 +18,7 @@ used for the web. Catalyst is designed to make it easy to manage the
 various tasks you need to do to run an application on the web, either by
 doing them itself, or by letting you "plug in" existing Perl modules
 that do what you need. There are a number of things you typically do
-with a web application, for example:
+with a web application. For example:
 
 =over 4
 
@@ -26,10 +26,10 @@ with a web application, for example:
 
 If you're on the web, you're relying on a web server, a program that
 sends files over the web. There are a number of these, and your
-application has to do the right thing to make sure that your data works
-with the web server you're using. If you change your web server, you
-don't want to have to rewrite your entire application to work with the
-new one.
+application has to do the right thing to make sure that your program
+works with the web server you're using. If you change your web server,
+you don't want to have to rewrite your entire application to work with
+the new one.
 
 =item * Do something based on a URI
 
@@ -54,17 +54,18 @@ edit, and retrieve your data.
 
 =item * Handle forms
 
-When a user submits a form, you process it, and make sure it's been
-filled in properly, and then then do something based on the
-result--submitting an order, updating a record, sending e-mail, or going
-back to the form if there's an error.
+When a user submits a form, you receive it, process it to make sure it's
+been filled in properly, and then do something based on the
+result--submit an order, update a record, send e-mail, or return to the
+form if there's an error.
 
 =item * Display results
 
-You have an application running on the web, people need to see
-things. You usually want to display things on a web browser; you will
-probably be using a template system to help generate HTML code; you
-might need other kinds of display, such as PDF files or RSS feeds.
+If you have an application running on the web, people need to see
+things. You usually want your application displayed on a web browser, in
+which case you will probably be using a template system to help generate
+HTML code. But you might need other kinds of display, such as PDF files,
+or other forms of output, such as RSS feeds or e-mail.
 
 =item * Manage users
 
@@ -91,37 +92,63 @@ Catalyst makes it easy to do all of these tasks, and many more. It is
 extremely flexible in terms of what it allows you to do, and very fast.
 It has a very large number of "plugins" that interact with existing Perl
 modules so that you can easily use them from within your
-application. Interact with a web server? Catalyst lets you use a number
-of different ones, and even comes with a built-in server for testing or
-local deployment. Do something based on a URI? Catalyst has extremely
-flexible systems for figuring out what to do based on a URI. Interact
-with a data store?  Catalyst has many plugins for different databases
-and database frameworks, and for other non-database storage
-systems. Handle forms?  Catalyst has plugins available for several form
-creation and validation systems that make it easy for the programmer to
-manage. Display results?  Catalyst has plugins available for a number of
-template modules and other output packages. Manage users? Catalyst has
-plugins that handle sessions, authentication, and authorization, in any
-way you need. Developing the application? Catalyst has detailed logging
-built-in, which you can configure as necessary, and supports the easy
-creation of new tests--some of which are automatically created when you
-begin writing a new application.
+application. 
+
+=item * Interact with a web server? 
+
+Catalyst lets you use a number of different ones, and even comes with a
+built-in server for testing or local deployment.
+
+=item * Do something based on a URI? 
+
+Catalyst has extremely flexible systems for figuring out what to do
+based on a URI.
+
+=item * Interact with a data store?
+
+Catalyst has many plugins for different databases and database
+frameworks, and for other non-database storage systems.
+
+=item * Handle forms? 
+
+Catalyst has plugins available for several form creation and validation
+systems that make it easy for the programmer to manage.
+
+=item * Display results?
+
+Catalyst has plugins available for a number of template modules and
+other output packages.
+
+=item * Manage users? 
+
+Catalyst has plugins that handle sessions, authentication, and
+authorization, in any way you need.
+
+=item * Developing the application? 
+
+Catalyst has detailed logging built-in, which you can configure as
+necessary, and supports the easy creation of new tests--some of which
+are automatically created when you begin writing a new application.
 
 =head3 What B<isn't> Catalyst?
 
 Catalyst is not an out-of-the-box solution that allows you to set up a
 complete working e-commerce application in ten minutes. (There are,
 however, several systems built on top of Catalyst that can get you very
-close to a working app.) It is not designed for end users, but for
-working programmers.
+close to a working app.) 
+
+Catalyst is not designed for end users, but for working programmers.
 
 =head2 Web programming: The Olden Days
 
 Perl has long been favored for web applications. There are a wide
 variety of ways to use Perl on the web, and things have changed over
 time. It's possible to handle everything with very raw Perl code:
-C<print "Content-type: text/html\n\n<center><h1>Hello
-World!</h1></center>";> for example, or
+
+    print "Content-type: text/html\n\n<center><h1>Hello
+    World!</h1></center>";
+
+for example, or
 
     my @query_elements = split(/&/, $ENV{'QUERY_STRING'});
     foreach my $element (@query_elements) {
@@ -136,8 +163,8 @@ parsing, generating form elements from Perl data structures, printing
 http headers, escaping text, and very many more, all with your choice of
 functional or object-oriented style. While L<CGI> was revolutionary and
 is still widely used, it has various drawbacks that make it unsuitable
-for larger applications: it is slow, your code with it generally
-combines application logic and display code, and it makes it very
+for larger applications: it is slow; your code with it generally
+combines application logic and display code; and it makes it very
 difficult to handle larger applications with complicated control flow.
 
 A variety of frameworks followed, of which the most widely used is
@@ -147,8 +174,9 @@ plugins and templating systems, and the like. Other systems include
 L<AxKit>, which is designed for use with XML running under mod_perl, and
 L<Maypole>--upon which Catalyst was originally based--designed for the
 easy development of powerful web databases. Is it not the purpose of
-this document to criticize or even evaluate these other frameworks; they
-may be useful for you and if so we encourage you to give them a try.
+this document to criticize or even briefly evaluate these other
+frameworks; they may be useful for you and if so we encourage you to
+give them a try.
 
 =head2 The MVC pattern
 
@@ -166,23 +194,24 @@ history of the pattern, and exactly what "usually" or "should" go into
 the Controller or the Model. We have no interest in joining such a
 debate. In any case, Catalyst does not enforce any particular setup; you
 are free to put any sort of code in any part of your application, and
-this discussion (and others elsewhere in the Catalyst documentation) is
-only a suggestion based on what we think works well. In most Catalyst
-applications, each branch of MVC will be made of up of several Perl
-modules that can handle different needs in your application.
+this discussion, along with others elsewhere in the Catalyst
+documentation, are only suggestions based on what we think works
+well. In most Catalyst applications, each branch of MVC will be made of
+up of several Perl modules that can handle different needs in your
+application.
 
 The purpose of the B<Model> is to access and modify data. Typically
 the Model will interact with a relational database, but it's also
 common to use other data sources, such as the L<Plucene> search
-engine, an LDAP server, etc.
+engine or an LDAP server.
 
 The purpose of the B<View> is to present data to the user. Typical Views
 use a templating module to generate HTML code, using L<Template
 Toolkit|Template>, L<Mason|HTML::Mason>, L<HTML::Template>, or the like,
-but it's also possible to generate PDF output, send email, etc., from a
-View. In Catalyst the View is usually a small module, just gluing some
-other module into Catalyst; the display logic is written within the
-template itself.
+but it's also possible to generate PDF output, send e-mail, etc., from a
+View. In Catalyst applications the View is usually a small module, just
+gluing some other module into Catalyst; the display logic is written
+within the template itself.
 
 The Controller is Catalyst itself. When a request is made to Catalyst,
 it will be received by one of your Controller modules; this module
@@ -202,28 +231,29 @@ URL such as C<http://www.mysite.com/catalog/display/2782>. Now what?
 
 First, Catalyst figures out that you're using the "catalog" Controller
 (how Catalyst figures this out is entirely up to you; URL dispatching is
-I<extremely> flexible in Catalyst). Then Catalyst sees that you want to
-use a "display" method in your Controller. Somewhere in this process,
-it's possible that you'll have authentication and authorization routines
-to make sure that the user is registered and is allowed to display a
-record. The Controller's display method will then extract "2782" as the
-record you want to retrieve, and make a request to a Model for that
-record. The Controller will then look at what the Model returns: if
-there's no record, the Controller will ask the View to display an error
-message, otherwise it will hand the View the record and ask the View to
-display it. In either case, the View will then generate an HTML page,
-which Catalyst will display to the user's browser, using whatever web
-server you've configured.
+I<extremely> flexible in Catalyst). Then Catalyst determines that you
+want to use a C<display> method in your "catalog" Controller. (There
+could be other C<display> methods in other Controllers, too.) Somewhere
+in this process, it's possible that you'll have authentication and
+authorization routines to make sure that the user is registered and is
+allowed to display a record. The Controller's C<display> method will
+then extract "2782" as the record you want to retrieve, and make a
+request to a Model for that record. The Controller will then look at
+what the Model returns: if there's no record, the Controller will ask
+the View to display an error message, otherwise it will hand the View
+the record and ask the View to display it. In either case, the View will
+then generate an HTML page, which Catalyst will send to the user's
+browser, using whatever web server you've configured.
 
 How does this help you?
 
 In many ways. Suppose you have a small catalog now, and you're using a
-lightweight database such as SQLite, or even a text file. But eventually
-your site grows, and you need to upgrade to something more
+lightweight database such as SQLite, or maybe just a text file. But
+eventually your site grows, and you need to upgrade to something more
 powerful--MySQL or Postgres, or even Oracle or DB2. If your Model is
 separate, you only have to change one thing, the Model; your Controller
 can expect that if it issues a query to the Model, it will get the right
-kind of result back. 
+kind of result back.
 
 What about the View? The idea is that your template is concerned almost
 entirely with display, so that you can hand it off to a designer who
@@ -231,28 +261,34 @@ doesn't have to worry about how to write code. If you get all the data
 in the Controller and then pass it to the View, the template isn't
 responsible for any kind of data processing. And if you want to change
 your output, it's simple: just write a new View. If your Controller is
-already getting the data you need, you pass it in the same way, and
+already getting the data you need, you can pass it in the same way, and
 whether you display the results to a web browser, generate a PDF, or
 e-mail the results back to the user, the Controller hardly changes at
-all. 
+all--it's up to the View.
 
 And throughout the whole process, most of the tools you need are either
 part of Catalyst (the parameter-processing routines that extract "2782"
 from the URL, for example) or are easily plugged into it (the
-authentication routines, the plugins for using Template Toolkit as your
-View).
+authentication routines, or the plugins for using Template Toolkit as
+your View).
 
-Now, Catalyst doesn't enforce very much at all. You can connect to a
-database, issue queries, and act on them from within your View, if you
+Now, Catalyst doesn't enforce very much at all. Template Toolkit is a
+very powerful templating system, and you can connect to a database,
+issue queries, and act on them from within a TT-based View, if you
 want. You can handle paging (i.e. retrieving only a portion of the total
-records possible) in your Controller or your Model. It's up to you. In
-some cases there might be very good reasons to do things a certain way
-(issuing database queries from a template seems to defeat the whole
-purpose of separation-of-concerns, and will drive your designer crazy),
-while in others it's just a matter of personal preference (perhaps your
-template, rather than your Controller, is the better place to decide
-what to display if you get an empty result). Catalyst just gives you the
-tools.
+records possible) in your Controller or your Model. In the above
+example, your Controller looked at the query result, determining whether
+to ask the View for a no-result error message, or for a result display;
+but it's perfectly possible to hand your query result directly to the
+View, and let your template decide what to do. It's up to you; Catalyst
+doesn't enforce anything.
+
+In some cases there might be very good reasons to do things a certain
+way (issuing database queries from a template defeats the whole purpose
+of separation-of-concerns, and will drive your designer crazy), while in
+others it's just a matter of personal preference (perhaps your template,
+rather than your Controller, is the better place to decide what to
+display if you get an empty result). Catalyst just gives you the tools.
 
 =head1 AUTHOR
 
diff --git a/lib/Catalyst/Manual/Intro.pod b/lib/Catalyst/Manual/Intro.pod
index ae49942..a6da2a1 100644
--- a/lib/Catalyst/Manual/Intro.pod
+++ b/lib/Catalyst/Manual/Intro.pod
@@ -12,7 +12,7 @@ itself, and why you should be using it, see L<Catalyst::Manual::About>.
 =head2 What is Catalyst?
 
 Catalyst is an elegant web application framework, extremely flexible yet
-extremely simple. It's similar to Ruby on Rails, Spring (Java) and
+extremely simple. It's similar to Ruby on Rails, Spring (Java), and
 L<Maypole>, upon which it was originally based.
 
 =head3 MVC
@@ -42,15 +42,15 @@ L<Mason|HTML::Mason>, L<HTML::Template>...
 =item * B<Controller>
 
 Control the whole request phase, check parameters, dispatch actions, flow
-control. Catalyst!
+control. Catalyst itself!
 
 =back
 
 If you're unfamiliar with MVC and design patterns, you may want to check
 out the original book on the subject, I<Design Patterns>, by Gamma,
-Helm, Johnson, and Vlissides, also known as the Gang of Four (GoF). You
-can also just Google it.  Many, many web application frameworks are
-based on MVC, including all those listed above.
+Helm, Johnson, and Vlissides, also known as the Gang of Four (GoF).
+Many, many web application frameworks are based on MVC, including all
+those listed above.
 
 =head3 Flexibility
 
@@ -110,7 +110,7 @@ simple way.
 =item * B<Building Block Interface>
 
 Components interoperate very smoothly. For example, Catalyst
-automatically makes a L<Context> object available to every
+automatically makes a L<context> object available to every
 component. Via the context, you can access the request object, share
 data between components, and control the flow of your
 application. Building a Catalyst application feels a lot like snapping
@@ -169,7 +169,7 @@ Catalyst in action:
 
 =back
 
-Dead easy!
+Easy!
 
 =head2 How It Works
 
@@ -209,7 +209,7 @@ parameter:
 
 =item * B<name>
 
-Name of your application.
+The name of your application.
 
 =back
 
@@ -277,7 +277,6 @@ information.
 =item * L<Catalyst::Log>
 
     $c->log
-
     $c->log->debug('Something happened');
     $c->log->info('Something you should know');
 
@@ -308,18 +307,19 @@ to maintain more persistent data, use a session.
 
 =head3 Actions
 
-A Catalyst controller is defined by its actions. An action is a sub with
-a special attribute. You've already seen some examples of actions in
-this document. The URL (for example http://localhost.3000/foo/bar)
-consists of two parts, the base (http://localhost:3000/ in this example)
-and the path (foo/bar).  Please note that the trailing slash after the
-hostname[:port] always belongs to base and not to the action.
+A Catalyst controller is defined by its actions. An action is a
+subroutine with a special attribute. You've already seen some examples
+of actions in this document. The URL (for example
+http://localhost.3000/foo/bar) consists of two parts, the base
+(http://localhost:3000/ in this example) and the path (foo/bar).  Please
+note that the trailing slash after the hostname[:port] always belongs to
+base and not to the action.
 
 Catalyst supports several types of actions:
 
 =over 4
 
-=item * B<Literal>
+=item * B<Literal> (B<Path> actions)
 
     package MyApp::Controller::My::Controller;
     sub bar : Path('foo/bar') { }
@@ -379,7 +379,7 @@ C<$c-E<gt>req-E<gt>snippets-E<gt>[0]> would be "23". If you want to pass
 arguments at the end of your URL, you must use regex action keys. See
 L</URL Path Handling> below.
 
-=item * B<Top-level>
+=item * B<Top-level> (B<Global>)
 
     package MyApp; 
     sub foo : Global { }
@@ -387,7 +387,7 @@ L</URL Path Handling> below.
 Matches http://localhost:3000/foo. The function name is mapped directly
 to the application base.
 
-=item * B<Namespace-Prefixed>
+=item * B<Namespace-Prefixed> (B<Local>)
 
     package MyApp::Controller::My::Controller; 
     sub foo : Local { }
@@ -422,9 +422,9 @@ C<$c-E<gt>forward('/catalog/order/process/bar')>.
 =back
 
 B<Note:> After seeing these examples, you probably wonder what the point
-is of defining names for regex and path actions. Actually, every public
-action is also a private one, so you have one unified way of addressing
-components in your C<forward>s.
+is of defining names for regex and path actions. Every public action is
+also a private one, so you have one unified way of addressing components
+in your C<forward>s.
 
 =head4 Built-in Private Actions
 
@@ -678,12 +678,12 @@ method.
 
 =head3 Components
 
-Catalyst has an uncommonly flexible component system. You can define as many
-L<Models>, L<Views>, and L<Controllers> as you like.
+Catalyst has an uncommonly flexible component system. You can define as
+many L<Models>, L<Views>, and L<Controllers> as you like.
 
-All components must inherit from L<Catalyst::Base>, which provides a simple
-class structure and some common class methods like C<config> and C<new>
-(constructor).
+All components must inherit from L<Catalyst::Base>, which provides a
+simple class structure and some common class methods like C<config> and
+C<new> (constructor).
 
     package MyApp::Controller::Catalog;
 
diff --git a/lib/Catalyst/Manual/Tutorial.pod b/lib/Catalyst/Manual/Tutorial.pod
index b05112a..798b51c 100644
--- a/lib/Catalyst/Manual/Tutorial.pod
+++ b/lib/Catalyst/Manual/Tutorial.pod
@@ -15,7 +15,7 @@ is to install the Catalyst bundle from CPAN:
 
 This will retrieve Catalyst and a number of useful extensions and 
 install them for you. This process might not be totally painless
-though, and you might want to look at CatInABox 
+though, and you might want to look at CatInABox at
 L<http://use.perl.org/~jk2addict/journal/28071>, especially if you are
 on a system that lacks a compiler.
 
@@ -25,7 +25,7 @@ on a system that lacks a compiler.
 Catalyst includes a helper script, C<catalyst.pl>, that will set up a 
 skeleton application for you:
 
-    $ catalyst tutorial
+    $ catalyst.pl tutorial
 
     created "tutorial"
     created "tutorial/script"
@@ -58,7 +58,7 @@ Catalyst provides:
     | /default                             | tutorial                              |
     '--------------------------------------+---------------------------------------'
 
-    [...] [catalyst] [info] tutorial powered by Catalyst 5.66
+    [...] [catalyst] [info] tutorial powered by Catalyst 5.67
     You can connect to your server at http://localhost:3000
 
 (Note that each line logged by Catalyst begins with a timestamp, which has
@@ -80,7 +80,7 @@ and hit return twice):
     Content-Length: 5525
     Content-Type: text/html; charset=utf-8
     Status: 200
-    X-Catalyst: 5.66
+    X-Catalyst: 5.67
 
     [...]
     Connection closed by foreign host.
@@ -110,7 +110,7 @@ helper script, C<script/tutorial_test.pl>.
 
 =head2 Getting started
 
-So you picked Catalyst. Good choice. I assume you have installed it as
+So you picked Catalyst. Good choice. We assume you have installed it as
 well. For this tutorial you will also need the following modules:
 
 L<Catalyst::Plugin::Session>
@@ -157,16 +157,16 @@ If you now run the built-in mini-server with:
 it will show some standard debug messages in the console screen 
 (more about those in a minute), and then inform you that you can now 
 connect to the test server on port 3000. Point your browser at 
-http://localhost:3000/ to see the built-in catalyst welcome screen.
+http://localhost:3000/ to see the built-in Catalyst welcome screen.
 
 The other important thing B<catalyst.pl> did was create your root
-controller. This file is a standard perl module like all the other
+controller. This file is a standard Perl module like all the other
 controllers that you might add to your application. It lives in the
 F<lib/> directory, and will have the same name as you supplied to the
 command above. In our case it is F<tutorial.pm>. Alongside this file is
 a directory of the same name, which is the top level namespace for the
 entire application. Thus every other module we create will be
-"tutorial::something";
+"tutorial::something".
 
 The root controller is used to load plugins, to configure the
 application and its plugins, and for generic private actions.  We will
@@ -178,8 +178,8 @@ The simplest way to debug your Catalyst application is to run it using
 the built-in mini-server as described in L<Getting started>. 
 
 If you want to output any debugging information to the console, then
-call C<< $c->log->debug() >>, passing it a string to output. For
-data structures, use L<Data::Dumper> and call C<<
+call C<< $c->log->debug() >>, passing it a string to output. For data
+structures, C<use> L<Data::Dumper> and call C<<
 $c->log->debug(Dumper($structure)) >>
 
 =head2 Model/View/Controller
@@ -188,48 +188,49 @@ The recommended method for code organization in a Catalyst application
 is known as the "Model View Controller" design pattern (also referred to
 "MVC". See L<http://en.wikipedia.org/wiki/Model-view-controller>). 
 
-The point of the MVC pattern is to divorce the dependencies of
-parts of the application from each other, and give them standard
+The point of the MVC pattern is to separate the dependencies of parts of
+the application from each other, and give them standard
 interfaces. Following this theory of organization should give your code
 all the benefits of modularity. The main benefits are interchangeability
-of parts and reusable code.
+of parts and reusability of code.
 
-Thus you could replace your file data storage with a database or your
-Oracle database with a MySQL database and not have to change any of your
-controlling or view logic. Or you could later decide to output
-information from your application as RSS instead of HTML just by adding
-a new view module.
+Thus you could replace your flat-file data storage with a relational
+database, or your MySQL database with an Oracle database, and not have
+to change any of your Controller or View logic. Or you could later
+decide to output information from your application as RSS instead of
+HTML just by adding a new View module.
 
 =head3 Model
 
 Models deal with the storage of data. For a complex website, you may
-need multiple varied data sources, each will have it's own model class
-that provides an abstracted interface to it. In this tutorial we are
-going to be using a simple database.
+need multiple data sources, each having its own model class that
+provides an abstracted interface to it. In this tutorial we are going to
+be using a simple database.
 
 =head3 View
 
 Views are used to display information to the user. In a web framework,
-it is generally used to output HTML to the browser. As mentioned
-previously, views can also be used to output RSS or any other kind of
-data format.  One easy way to do this with Catalyst is to use a
-templating system such as Template Toolkit. If outputting HTML is all
-you are going to do, then you will probably only need one view.
+the View is generally used to output HTML to the browser. As mentioned
+previously, Views can also be used to output RSS or any other kind of
+data. One easy way to do this with Catalyst is to use a templating
+system such as L<Template Toolkit|Template>. If outputting HTML is all
+you are going to do, then you will probably only need one View.
 
 =head3 Controller
 
-A controller deals with reacting to user choices, and thus controls what
-the application does. Since this is a web framework, Catalyst
-controllers are frequently used to react directly to URLs requested by
-the user. This tutorial will describe the simplest way of using
-controllers, where each path or part of a path is assigned its own
+A controller is responsible for responding to user choices, and thus
+controls what the application does. Since this is a web framework,
+Catalyst controllers are frequently used to react directly to URLs
+requested by the user. This tutorial will describe the simplest way of
+using controllers, where each path or part of a path is assigned its own
 action (or subroutine). More complex controlling mechanisms will be
-mentioned briefly, and can be read about in detail in the manual.
+mentioned briefly, and can be read about in detail elsewhere in the
+manual.
 
 
 =head2 Controlling
 
-Now lets write our first bit of application code. First, we would like
+Now let's write our first bit of application code. First, we would like
 our application to greet our users. We'll assume for now that our users
 will be sent to the I<users/greet> URL. To create a controller that
 serves the I<users> namespace, we run the following command in our
@@ -239,7 +240,7 @@ F<tutorial> directory:
 
 This will create a Users.pm in F<lib/tutorial/Controller>. Open this
 file in an editor and take a look. You will notice there is some
-commented out code which we will ignore for now. To make something
+commented-out code which we will ignore for now. To make something
 happen when our URL is visited, we will write a "greet" action which
 looks like this:
 
@@ -260,13 +261,13 @@ looks like this:
     $c->stash->{template} = 'greet.tt';
   }
 
-Whew! So, what does all this do? Lets take it one step at a time.
-The subroutine declaration gives the action a name.  To the right of the
-name there is an attribute type that looks like this:   
+Whew! So, what does all this do? Let's take it one step at a time. The
+subroutine declaration gives the action a name. To the right of the name
+there is an attribute type that looks like this:
 
     : Local 
     
-That defines which URIs will translate to this action. "Local", matches
+That defines which URIs will translate to this action. "Local" matches
 exactly one URI: 
 
     /users/greet
@@ -282,9 +283,9 @@ the "greet" action defined above in the Users controller will be executed.
 
 The second line retrieves the parameters Catalyst gives us when it calls
 our method. The first is the instance of our Users class, and the second
-is commonly called the context, and named $c.  From now on, whenever we 
-are talking about the context object, it will be represented as $c in 
-the code.
+is commonly called the "context", held in C<$context>, or abbreviated to
+C<$c>.  From now on, whenever we are talking about the context object,
+it will be represented as C<$c> in the code.
 
 The context is the magical object containing any information you need from 
 catalyst, or want to send to it, and is passed from action to action. 
@@ -297,38 +298,38 @@ to retrieve one of the query parameters, just like in L<CGI>.
 On the fourth, we make a debug output of this object on the server console,
 or the error log if running under CGI or mod_perl.
 
-Next, if we have a post request, we check if the name field contains anything 
-(or is "true"), if it isn't, we assign an error message to a "message" field 
-in the stash. The stash is yet another method of the context object, it allows 
-us to pass data on to other methods we call later, most usefully the View 
-modules.
+Next, if we have a post request, we check if the name field contains
+anything (or is "true"). If it isn't, we assign an error message to a
+"message" field in the stash. The stash is a special hash of the context
+object, which allows us to pass data on to other methods we call later,
+typically in the View.
 
 If the username did contain a value, then we just set our message to
 greet the user by name.
 
 Finally, we set the special "template" variable in the stash to the name
-of the template we want our view to use to display this page.
+of the template we want our View to use to display this page.
 
 =head2 Viewing
 
-Ok, so reacting and checking the users data is all fine, but how do we
-actually display the page/form in the first place, and our results? As
-previously mentioned, we'll use Template Toolkit for our viewing. To
-create out TT based view, just run the following command:
+OK, so reacting and checking the users data is all fine, but how do we
+actually display the page/form in the first place, and our results? In
+this tutorial, we'll use Template Toolkit for our viewing. To create our
+TT-based view, just run the following command:
 
     script/tutorial_create.pl view TToolkit TT
 
 Notice that this time we not only gave it the type of module we wanted
 to create (a view), and a name, but also a third argument, "TT". This is
-a Catalyst helper module, which will make a standard template toolkit
+a Catalyst helper module, which will make a standard Template Toolkit
 module for you. And that's all you need to do there.
 
 To use the view, the easiest way is to set up a standard "end" action.
-This a private action which will not be matched to a path like our
-"greet" action, but instead will be called after all other processing is
-done. Only one end action will be called, if there is one in a
-controller, it will be preferred over one in the application module, and
-so on.
+This is a special private action which will not be matched to a path
+like our "greet" action, but instead will be called after all other
+processing is done. Only one end action will be called in any request
+cycle. If there is one in a controller, it will be preferred over one in
+the application module, and so on.
 
 Since we're writing a simple application, just add an end action like
 this to F<tutorial.pm>:
@@ -339,35 +340,37 @@ this to F<tutorial.pm>:
     }
 
 The first line declares the end sub, and marks it as a Private action.
-(The second and last attribute type we'll be using). The second line
-collects our standard parameters as shown in the controller's greet action.
+(This is the second and last attribute type we'll be using in this
+tutorial.) The second line collects our standard parameters as shown in
+the controller's greet action.
 
 The third line directs Catalyst to pass processing on to our TToolkit
-view. The forward method, when just passed a class name, calls process
-on that class. The standard TT view's process method renders the
-template named in the template variable in the stash, using all the
-other variables in the stash as values to fill it in.
+view. The forward method, when just passed a class name, calls
+C<process> on that class. The standard TT view's C<process> method
+renders the template named in the template variable in the stash, using
+all the other variables in the stash as values to fill it in.
 
-NB: This is such a common way to end you processing that there is a
+NB: This is such a common way to end your processing that there is a
 plugin which does it for you: L<Catalyst::Plugin::DefaultEnd>.
 
-Template Toolkit also has access to the entire context object via "c",
-for example, using [% c.config.name %] in our template will output
-"tutorial", our project name.
+Template Toolkit also has access to the entire context object via the
+special variable "c". For example, using C<[% c.config.name %]> in our
+template will output "tutorial", our project name.
 
 All that remains is to create a simple template called "greet.tt",
 containing a form with a text field called "name" like below.
 
     <html><head><title> [% c.name %]</head><body>
-    <p>[%message%]</p>
-    <form action="[%c.req.uri%]" method="post">
+    <p>[% message %]</p>
+    <form action="[% c.req.uri %]" method="post">
     <input type="text" name="name"/>
     <input type="submit" value="Submit" name="submit"/>
     </form>
     </body></html>
 
-In the example above, we use [%c.req.uri%], since we're posting to ourself.
-if we post to another action, we commonly use the uri_for method, like this:
+In the example above, we use C<[% c.req.uri %]>, since we're posting to
+ourself. If we post to another action, we commonly use the uri_for
+method, like this:
 
     [% c.uri_for('/users/greet')%]
 
@@ -376,10 +379,10 @@ searched for here, but we can change that, which brings us to...
 
 =head2 Configuring
 
-As previously mentioned, the configuration of modules, plugins and so on
-is done in the main application file. This is especially true for bits
-which need to be done before an instance of them is created, for example
-Template Toolkit.
+As previously mentioned, the configuration of modules, plugins, and so
+on is done in the main application file. This is especially true for
+bits which need to be done before an instance of them is created, for
+example Template Toolkit.
 
 The TT View looks for its templates in the F<root> directory by default.
 Since this is also the directory that static files go in, we'd rather
@@ -402,28 +405,28 @@ happens if you try to visit I<localhost:3000/users> ?
 
 =head2 Users and Authenticating
 
-One of the many reasons to write dynamic websites instead of just using static 
-HTML, is to allow us to produce different content for different users, as well
- as just restricting access to pages (which we could do with just Apaches 
-htpasswd system).
+One of the many reasons to write dynamic websites instead of just using
+static HTML is to allow us to produce different content for different
+users, as well as restricting access to pages (which we could do with
+just Apache's htpasswd system).
 
-In this tutorial, we will just be using basic authentication, when writing 
-a real application, you'll want to use a database or other secure store to 
-contain your user data.
+In this tutorial, we will just be using basic authentication. When
+writing a real application, you'll want to use a database or other
+secure store to contain your user data.
 
 To add authentication, all we need to do is add the
-L<Catalyst::Plugin::Authentication> module to our main application file. Then
-we need to pick a storage method (one of the
-L<Catalyst::Plugin::Authentication::Store> modules), and a method of verifying
-the users credentials (one of the
-L<Catalyst::Plugin::Authentication::Credential> modules), so just edit
-F<tutorial.pm> to look like this: 
+L<Catalyst::Plugin::Authentication> module to our main application
+file. Then we need to pick a storage method (one of the
+L<Catalyst::Plugin::Authentication::Store> modules), and a method of
+verifying the user's credentials (one of the
+L<Catalyst::Plugin::Authentication::Credential> modules). Edit
+F<tutorial.pm> to look like this:
 
  use Catalyst qw/-Debug Static::Simple Authentication 
                 Authentication::Store::Minimal 
                 Authentication::Credential::Password/;
 
-To configure, add some users to the config call, for example: 
+To configure, add some users to the config call. For example:
 
  authentication => { 'users' =>
                        { 'fred' =>
@@ -432,15 +435,17 @@ To configure, add some users to the config call, for example:
                        }
                    }
 
-Generally, setting up configuration data for plugins is done based on the 
-type of plugin. Check the documentation of the plugin for exact details. The 
-details of this one are in L<Catalyst::Plugin::Authentication::Store::Minimal>.
+Generally, setting up configuration data for plugins is done based on
+the type of plugin. Check the documentation of the plugin for exact
+details; in this example we should look in
+L<Catalyst::Plugin::Authentication::Store::Minimal>.
 
-Since our user data is in the config, we can update it at runtime, and thus 
-add users dynamically. (Of course, to keep them permanently we'll need to 
-export our data to disk and read it back into the config on startup)
+Since our user data is in the config, we can update it at runtime, and
+thus add users dynamically. (Of course, to keep them permanently we'd
+need to save our data to disk and read it back into the config on
+startup.)
 
-To allow creation of new users we'll add a create action to our Users 
+To allow creation of new users we'll add a C<create> action to our Users
 controller.
 
  sub create : Local {
@@ -450,7 +455,7 @@ controller.
 
     if($username && $passwd1 && $passwd2) {
        if($c->config->{authentication}{users}{$username}) {
-          $c->stash->{message} = 'Sorry that user already exists';
+          $c->stash->{message} = 'Sorry, that user already exists';
           $c->stash->{username} = $username;
        }
        elsif($passwd1 eq $passwd2) {
@@ -466,10 +471,10 @@ controller.
     $c->stash->{template} = 'usercreate.tt';
  }
 
-All this is doing is checking that all the appropriate fields are filled, 
-the password fields contain the same data, and then adding the user to the 
-config hash.  All the checks produce a message which can be displayed to 
-the user via the View.
+All this is doing is checking that all the appropriate fields are
+filled, and that the password fields contain the same data, and then
+adding the user to the config hash.  All the checks produce a message
+which can be displayed to the user via the View.
 
 The usercreate.tt template looks like this:
 
@@ -481,7 +486,7 @@ The usercreate.tt template looks like this:
         [% key %]<br/>
     [% END %]
  </p>
- <p> [% c.stash.message %] </p>
+ <p> [% message %] </p>
  <form action="/users/create" method="post">
  <p>User Name: <input type="text" name="username"/></p>
  <p>Password: <input type="password" name="password"/></p>
@@ -490,8 +495,8 @@ The usercreate.tt template looks like this:
  </form>
  </body></html>
 
-So our that users can login, we need a login action which we put in the
-Users controller:
+In order for our users to be able to login, we need a C<login> action
+which we put in the Users controller:
 
  sub login : Local {
      my ($self, $c) = @_;
@@ -508,7 +513,7 @@ Users controller:
 And the userlogin.tt template:
 
  <html><head><title>[% c.config.name %]</title></head><body>
- <p> [% c.stash.message %] </p>
+ <p> [% message %] </p>
  <form name='login' action='/users/login' method='post'>
  <p>Username: <input type='text' name='user' /></p>
  <p>Password: <input type='password' name='password' /></p>
@@ -516,12 +521,12 @@ And the userlogin.tt template:
  </body></html>
 
 
-Verrrry simple. Since Credential::Password's "login" call extracts the 
-username/password data from the query itself (assuming we use a standard 
+Very simple. Since Credential::Password's "login" call extracts the
+username/password data from the query itself (assuming we use a standard
 name for our form fields), we don't have to do anything but call it.
 
-To keep the user logged in, all we need to do is add the Session modules to 
-our collection, and the Auth modules will automatically use them; 
+To keep the user logged in, all we need to do is add the Session modules
+to our collection, and the Auth modules will automatically use them:
 
  use Catalyst qw/-Debug Static::Simple Authentication 
                  Authentication::Store::Minimal 
@@ -534,24 +539,23 @@ Magic!
 
 As an exercise for the reader, do the following:
 
-Change users/greet and greet.tt so that the welcome message greets the
-user by name.
+Change C<users/greet> and C<greet.tt> so that the welcome message greets
+the user by name.
 
-Enforce user logging in by adding an auto action in tutorial.pm (see
-the L<Catalyst> documentation to find out about the auto action).
+Enforce user logging in by adding an C<auto> action in tutorial.pm (see
+the L<Catalyst> documentation to find out about the C<auto> action).
 
-=head2 Authorising
+=head2 Authorizing
 
-Authentication is about verifying users, Authorisation is about
-allowing them to do things. Catalyst currently has two Authorisation
+Authentication is about verifying users, and authorization is about
+allowing them to do things. Catalyst currently has two Authorization
 modules, Roles and ACL. The Roles module allows you to define groups
 which you can assign your users to, and then allow access to areas of
-your website to the groups. The ACL module lets you do more fine
-grained access/restriction by allowing of denying access however you
-like (It also supports Roles as done by the roles module). This
-example uses L<Catalyst::Plugin::Authorization::Roles>. To use this add
-"Authorization::Roles" into the "use Catalyst" statement in
-tutorial.pm.
+your website to the groups. The ACL module lets you do more fine grained
+access/restriction by allowing of denying access however you like. (It
+also supports Roles as done by the roles module.) This example uses
+L<Catalyst::Plugin::Authorization::Roles>. To use this add
+"Authorization::Roles" into the "use Catalyst" statement in tutorial.pm.
 
 Adding Roles via the Minimal store we are already using is quite simple,
 we just add a roles key to each user, defining the names of the roles
@@ -574,7 +578,7 @@ make a restricted I<http://localhost:3000/users/groups> page like this:
     my ($self, $c) = @_;
     if($c->check_user_roles('admin')) {
        # Now we can do things only an admin will see
-       if(my $params = $c->req->params) {
+       if (my $params = $c->req->params) {
           my $users = $c->config->{authentication}{users};
           foreach my $u (keys %$params) {
              $users->{$u}{roles} = $params->{$u} if($users->{$u});
@@ -592,16 +596,17 @@ make a restricted I<http://localhost:3000/users/groups> page like this:
     }
  }
 
-What we are doing here is checking whether the logged in user (used by
-default in the check_user_roles method), is a member of the admin group.
-If it is, then we display the usergroups template, and update the users
-hash as required. Otherwise, we just show the user an error page.
+What we are doing here is checking whether the logged-in user (used by
+default in the C<check_user_roles> method) is a member of the admin
+group. If it is, then we display the usergroups template, and update
+the users hash as required. Otherwise, we just show the user an error
+page.
 
 For this simple example, the usersgroups.tt and error.tt templates could
 both look like this:
 
  <html><head><title>[% c.config.name %]</title></head><body>
- <p>[% c.stash.message %]</p>
+ <p>[% message %]</p>
  <p>[% c.stash.users %]</p>
  </body></html>
 
@@ -610,7 +615,7 @@ And that's all there is to it.
 =for authors
 So it's not clear what the groups action is doing - and with the
 current template, nothing happens.  Running through the sample code,
-it's clear what's happening, (which is very little), but the purpose,
+it's clear what's happening (which is very little), but the purpose,
 and how to display data is not clear.
 
 =cut
@@ -628,29 +633,29 @@ action in the Users controller:
 
 =head2 Data Storage (Modelling)
 
-Whether we want our users to be able to contribute to our website, or just
-create it from changeable data, we need to store the data somewhere. Generally
-this is done using a database, models can also be other data sources, for
-example another website, or RSS feeds. 
+Whether we want our users to be able to contribute to our website, or
+just create it from changeable data, we need to store the data
+somewhere. Generally this is done using a database, but models can also
+use other data sources, for example another website, or an RSS feed.
 
-If you have or want a database, there are still choices to be made, there are
-several modules about for accessing databases via OO. The best known are
-probably L<DBIx::Class> and L<Class::DBI>. Catalyst supports making models
-using either of these.  
+If you have or want a database, there are still choices to be
+made. There are several modules for accessing databases using an
+object-oriented wrapper. The best known are probably L<DBIx::Class> and
+L<Class::DBI>. Catalyst supports making models using either of these.
 
-For a simple example, we will allow our users to store their favourite
-greeting in our database. Create a table called "greetings" in a database,
-that contains a "user" field and a "greeting" field. The simplest way to
-create a model of your database is to use these helper modules, for example
-with L<DBIx::Class>: 
+For a simple example, we will allow our users to store their favorite
+greeting in our database. Create a table called "greetings" in a
+database, that contains a "user" field and a "greeting" field. The
+simplest way to create a model of your database is to use these helper
+modules, for example with L<DBIx::Class>:
 
     script/tutorial_create.pl model UserData DBIC dbi:SQLite:/path/to/mydb.db
 
 This will cause the DBIx::Class Loader to inspect your database, and create a
 module in the Model::UserData namespace for each table in your database. 
 
-Now we need a form for our users to enter/edit their personal greetings in,
-we'll make a I<http://localhost:3000/users/editgreeting> page: 
+Now we need a form for our users to enter/edit their personal greetings
+in, so we'll make a I<http://localhost:3000/users/editgreeting> page:
 
  sub editgreeting : Local {
     my ($self, $c) = @_;
@@ -670,16 +675,16 @@ we'll make a I<http://localhost:3000/users/editgreeting> page:
  }
 
 Using C<< $c->user_exists >> from the Authentication plugin, this checks
-whether the user is logged in already. If they are, if they are, and they have
-entered a new greeting, we use DBIx::Class' C<find_or_create> to fetch or
-create a new record in the greetings table for the user. Once we have the
-record, we change the value of the greeting field, and call C<update> to store
-the new value in the database. 
+whether the user is logged in already. If they are, and they have
+entered a new greeting, we use DBIx::Class' C<find_or_create> method to
+fetch or create a new record in the greetings table for the user. Once
+we have the record, we change the value of the greeting field, and call
+C<update> to store the new value in the database.
 
 =head2 Engines (Apache and FastCGI)
 
 Now that we have the basics together, we can try running our application on a
-"real" server instead of just using the test server that catalyst comes
+"real" server instead of just using the test server that Catalyst comes
 with. L<Catalyst::Engine> is the module used to implement various types of
 servers to run it on. The current popular ones are Apache and FastCGI.
 
@@ -691,24 +696,25 @@ subsections. Use the Location directive to choose a path to run your
 application under: 
 
  <Location />
-   SetHandler                perl-script
+   SetHandler           perl-script
    PerlResponseHandler  tutorial
  </Location>
 
-You will need to install the perl modules of your application into one of
-perls library directories, as listed by B<perl -V>, so that Apache can find
-them. Alternatively you can use the C<PerlSwitches> directive to tell Apache
-where to look: 
+You will need to install the perl modules of your application into one
+of perl's library directories, as listed by B<perl -V>, so that Apache
+can find them. Alternatively you can use the C<PerlSwitches> directive
+to tell Apache where to look:
 
  PerlSwitches -I/path/to/tutorial/
 
-These instructions are for using Apache2 and mod_perl 2.0. If you are using
-mod_perl 1.3 or 1.99, please refer to either L<Catalyst::Engine::Apache::MP13>
-or L<Catalyst::Engine::Apache2::MP19> for slightly different ways to do it. 
+These instructions are for using Apache2 and mod_perl 2.0. If you are
+using mod_perl 1.3 or 1.99, please refer to either
+L<Catalyst::Engine::Apache::MP13> or L<Catalyst::Engine::Apache2::MP19>
+for details of the slightly different ways to do it.
 
 If you wish to ensure that Apache pre-loads your application, use the
-PerlModule directive. This means that there will be less of a delay when your
-application is accessed. 
+PerlModule directive. This means that there will be less of a delay when
+your application is accessed.
 
  PerlModule tutorial
 
@@ -800,24 +806,23 @@ line of your application.
 
 =head2 Upgrading
 
-Upgrading your application to newer Catalyst versions is quite simple. After
-installing the new Catalyst package, just run: 
+Upgrading your application to newer Catalyst versions is quite
+simple. After installing the new Catalyst package, just run:
 
     catalyst.pl -scripts
 
-One level above your application directory. This will update the
-scripts directory only, and leave the rest of your app alone, If you
-wish to make use of other parts of Catalyst that have been updated,
-leave off the B<-scripts> argument, this will cause .new files to
-appear, for each module that has either been updated, or is different
-to the original because you have changed it. To find out what these
-changes are, type:
+One level above your application directory. This will update the scripts
+directory only, and leave the rest of your app alone. If you wish to
+make use of other parts of Catalyst that have been updated, leave off
+the B<-scripts> argument, this will cause .new files to appear, for each
+module that has either been updated, or is different to the original
+because you have changed it. To find out what these changes are, type:
 
     diff tutorial/lib/tutorial/View/TT.pm tutorial/lib/tutorial/View/TT.pm.new
 
-for each of the changed files. (This is a Unix command, Windows users
-will need to find some equivalent). Copy any changes you need into
-your original file, then remove the .new files. (This makes life less
+for each of the changed files. (This is a Unix command; Windows users
+will need to find some equivalent.) Copy any changes you need into your
+original file, then remove the .new files. (This makes life less
 complicated when the next upgrade comes around.)
 
 =head1 AUTHORS
@@ -833,10 +838,10 @@ jrobinson@cpan.org, ghenry@cpan.org
 
 =head1 TODO
 
-Finish DBIC examples with templates and tested code.  Make
-/users/groups do something "useful"
+Finish DBIC examples with templates and tested code. Make /users/groups
+do something "useful".
 
-Many other things..
+Many other things....
 
 =head1 COPYRIGHT