make explanations a bit more accessible and clear and improve grammar…

lib/Dancer2/Manual.pod

@@ -20,13 +20,16 @@ way, easily.
 
 =head1 INSTALL
 
-Installation of Dancer2 is simple:
+Since Dancer2 is available on the Comprehensive Perl Archive Network (CPAN),
+the authoritative repository for Perl modules, Dancer 2 can be installed with
+one simple command. If you are familiar with Perl and use it, you probably
+already have L<cpan> configured on your machine and can install Dancer 2 with:
 
     perl -MCPAN -e 'install Dancer2'
 
-Thanks to the magic of cpanminus, if you do not have CPAN.pm configured, or
-just want a quickfire way to get running, the following should work, at
-least on Unix-like systems:
+But, if you are newer to Perl, you may not have L<cpan> configured. No worries.
+Thanks to the magic of the L<cpanminus> module, you can get up and running
+quickly on Unix-like systems with the following:
 
     wget -O - http://cpanmin.us | sudo perl - Dancer2
 
@@ -35,9 +38,13 @@ Dancer2 and prereqs into C<~/perl5>.)
 
 =head1 BOOTSTRAPPING A NEW APP
 
-Create a web application using the dancer script:
+The Dancer 2 distribution includes a script called L<dancer2> which you can use
+to automatically generate a new web application from the command line, like so:
 
     $ dancer2 -a MyApp && cd MyApp
+
+You will then see the following output:
+
     + MyApp
     + MyApp/config.yml
     + MyApp/Makefile.PL
@@ -73,12 +80,52 @@ Create a web application using the dancer script:
     + MyApp/views/layouts
     + MyApp/views/layouts/main.tt
 
-It creates a directory named after the name of the app, along with a
-configuration file, a views directory (where your templates and layouts
-will live), an environments directory (where environment-specific
-settings live), a module containing the actual guts of your application, and
-a script to start it. A default skeleton is used to bootstrap the new
-application, but you can use the C<-s> option to provide another skeleton.
+The L<dancer2> script creates the following:
+
+=over
+
+=item *
+a directory named after the name of the app, L<MyApp> in this case
+
+=item *
+
+a configuration file, l<MyApp/config.yml>.
+
+=item *
+
+a L<views> directory (where your templates and layouts will live),
+
+=item *
+
+an L<environments> directory (where environment-specific settings live),
+
+=item *
+
+a L<public> directory (where static assets like css file and javascrpt files can
+go)
+
+=item *
+
+a L<t> directory (where your tests can go)
+
+=item *
+
+a variety of files for helping you build your application into a
+module for release
+
+=item *
+
+a module containing the actual guts of your application in L<lib>
+
+=item *
+
+a script to start your appliaction in L<bin>.
+
+=back
+
+A default skeleton is used to generate the new application. You can use
+the C<-s> option to provide another skeleton.
+
 For example:
 
     $ dancer2 -a MyApp -s ~/mydancerskel
@@ -95,23 +142,45 @@ C<plackup> tool (provided by L<Plack>) for launching the application:
 
     plackup -p 5000 bin/app.psgi
 
-View the web application at:
+You can then access the web application with your favorite browser at:
 
     http://localhost:5000
 
 =head1 USAGE
 
-When Dancer2 is imported to a script, that script becomes a webapp, and at
-this point, all the script has to do is declare a list of B<routes>. A
-route handler is composed by an HTTP method, a path pattern and a code
-block. C<strict>, C<warnings> and C<utf8> pragmas are also imported with
-Dancer2.
+When Dancer2 is imported to a script with L<use Dancer2;>, that script
+becomes a Dancer 2 web app. First, the C<strict>, C<warnings> and C<utf8>
+pragmas are injected into the script by Dancer 2. The import function of the 
+script is also modified so that Dancer 2's keywords can be imported and used by
+the script.
+
+Now, all the script needs to do is declare its B<route handlers>. A route
+handler is a list of three elements: a Dancer 2 keyword for the HTTP method,
+a path pattern, and a block of code. For example, here is a simple route handler:
+
+    get '/' => sub { return 'Hello World!'; };
+
+Here, the HTTP method is C<get>, the pattern to match is C</>, which is the root
+directory of the website. When a browser visits C</> with a C<GET> request, 
+the string 'Hello World!' generated by our block of code will be sent back in the
+response to the browser.
 
 The code block given to the route handler has to return a string which will
-be used as the content to render to the client.
+be used as the content to render for the client.
+
+Each route handler you create inside of your script is stored in your app so
+your app can handle the requests as they come in.
+
+You can make your route handler dynamic with parameters. As a simiple example:
+
+    get '/hello/:name' => sub {
+      return "Hi there " . route_parameters->get('name');
+    };
 
-Routes are defined for a given HTTP method. For each method supported, a
-keyword is exported by the module.
+This will create a page that greets the visitor with the string of text that
+follows C</hello/> in the path. More typically, parameters are use to 
+query a database or determine which page to show. See the 
+L<Dancer2::Manual/Route Patterns> for more details on route patterns.
 
 =head2 HTTP Methods
 
@@ -122,27 +191,30 @@ route handlers.
 
 =item * B<GET> The GET method retrieves information, and is the most common
 
-GET requests should be used for typical "fetch" requests - retrieving
-information. They should not be used for requests which change data on the
-server or have other effects.
+GET requests are typically used as "fetch" requests to retreive information.
+They should not be used for requests which change data on the server or
+have other side effects.
 
-When defining a route handler for the GET method, Dancer2 automatically
-defines a route handler for the HEAD method (in order to honour HEAD
-requests for each of your GET route handlers).
+When defining GET route hander, Dancer2 also automatically 
+defines a route handler for the HEAD method in order to honour HEAD
+requests for each of your GET route handlers.
 
 To define a GET action, use the L<get|Dancer2::Manual/get> keyword.
 
 =item * B<POST> The POST method is used to create a resource on the server.
 
+POST requests are typically used to submit data to the web application. The
+most common example is by sending data from an HTML form.
+
 To define a POST action, use the L<post|Dancer2::Manual/post> keyword.
 
 =item * B<PUT> The PUT method is used to replace an existing resource.
 
 To define a PUT action, use the L<put|Dancer2::Manual/put> keyword.
 
-a PUT request should replace the existing resource with that specified - for
-instance - if you wanted to just update an email address for a user, you'd
-have to specify all attributes of the user again; to make a partial update,
+A PUT request should replace the existing resource with that specified. For
+instance, if you wanted to just update an email address for a user, you'd
+have to specify all attributes of the user again. To make a partial update,
 a PATCH request is used.
 
 =item * B<PATCH> The PATCH method updates some attributes of an existing resource.
@@ -172,51 +244,38 @@ The following will match GET or POST requests to C</myaction>:
         # code
     };
 
-For convenience, any route which matches GET requests will also match HEAD
-requests.
-
-=head2 Route Handlers
-
-The route action is the code reference declared. It can access parameters
-through the specific C<route_parameters>, C<query_parameters>, and 
-C<body_parameters> keywords, which return a L<Hash::MultiValue> object. 
-This hashref is a merge of the route pattern matches and the request params.
+As mentioned previously, any route which matches GET requests will also
+match HEAD requests. This is just convenience for web app developers.
 
-You can have more details about how params are built and how to access them
-in the L<Dancer2::Core::Request> documentation.
-
-=head3 Declaring Routes
+=head2 Route Patterns
 
-To control what happens when a web request is received by your webapp,
-you'll need to declare C<routes>. A route declaration indicates which HTTP
-method(s) it is valid for, the path it matches (e.g. C</foo/bar>), and a
-coderef to execute, which returns the response.
+After the declaration of the HTTP method, your route handler must supply
+a pattern that will be used to match against the path of the incoming request.
 
-    get '/hello/:name' => sub {
-        return "Hi there " . route_parameters->get('name');
-    };
+The simplest route patterns provide an exact match to the requested path:
 
-The above route specifies that, for GET requests to C</hello/...>, the code
-block provided should be executed.
+    get '/foo/bar' => sub {
+      return 'You are on page /foo/bar';
+    }
 
-=head3 Retrieving request parameters
+This route will be activated when a client requests the C</foo/bar>) path.
 
-The L<query_parameters|Dancer2::Manual/query_parameters>,
-L<route_parameters|Dancer2::Manual/route_parameters>, and
-L<body_parameters|Dancer2::Manual/body_parameters> keywords provide
-a L<Hash::MultiValue> result from the three different parameters.
+Your route patterns can be much more sophisticated and be used to create
+parameters to pass data into your action. More advanced types of route
+patterns are described below.
 
 =head3 Named matching
 
 A route pattern can contain one or more tokens (a word prefixed with ':').
 Each token found in a route pattern is used as a named-pattern match. Any
-match will be set in the route parameters.
+match will be found in the C<route_parameters> variable and can be retrieved
+in the block of code.
 
     get '/hello/:name' => sub {
         "Hey " . route_parameters->get('name') . ", welcome here!";
     };
 
-Tokens can be optional, for example:
+Tokens can be optional by tacking a question mark to the end of it, for example:
 
     get '/hello/:name?' => sub {
         my $name = route_parameters->get('name') //= 'Whoever you are';
@@ -295,6 +354,29 @@ user_agent, content_length and path_info):
       'all browsers except songbird'
     }
 
+=head2 Route Action
+
+The route action is the code reference in the route handler which follows the
+HTTP method and the route pattern. As we saw in the previous section, your
+action can access parameters through the specific C<route_parameters>,
+C<query_parameters>, and C<body_parameters> keywords, which return a
+L<Hash::MultiValue> object. This hashref is a merge of the route pattern
+matches and the request params.
+
+=head3 Retrieving request parameters
+
+As we saw in the previous section, your action can access parameters through
+the specific C<route_parameters>, C<query_parameters>, and C<body_parameters> 
+keywords, which together return a L<Hash::MultiValue> object. This hashref is
+a combination of the route pattern matches and the request params.
+
+For more information on these types of parameters, see the  L<query_parameters|Dancer2::Manual/query_parameters>,
+L<route_parameters|Dancer2::Manual/route_parameters>, and
+L<body_parameters|Dancer2::Manual/body_parameters> documentation.
+
+More details about how params are built and how to access them are available
+in the L<Dancer2::Core::Request> documentation.
+
 =head2 Prefix
 
 A prefix can be defined for each route handler, like this: