From: Kennedy Clark <hkclark@gmail.com>
Date: Tue, 3 Mar 2009 01:19:03 +0000 (+0000)
Subject: Suggestions and fixes with thanks to Murray Walker (along with a few other minor... 
X-Git-Tag: v5.8005~196
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=commitdiff_plain;h=1435672d3f51326b8f15006abcfe98180e89becb

Suggestions and fixes with thanks to Murray Walker (along with a few other minor adjustments)
---

diff --git a/Changes b/Changes
index 254ae59..73a0a84 100644
--- a/Changes
+++ b/Changes
@@ -1,5 +1,9 @@
 Revision history for Catalyst-Manual
 
+5.7XXX
+        - Suggestions and fixes with thanks to Murray Walker
+        - Misc updates and fixes
+
 5.7017  28 Feb 2009
         - Main change = adding Chained dispatch starting in BasicCRUD (Part 4)
         - Add some "getting started" links to the Catalyst::Manual page
diff --git a/lib/Catalyst/Manual/Tutorial.pod b/lib/Catalyst/Manual/Tutorial.pod
index 6d914a5..38c6145 100644
--- a/lib/Catalyst/Manual/Tutorial.pod
+++ b/lib/Catalyst/Manual/Tutorial.pod
@@ -11,7 +11,7 @@ commonly used features while focusing on real-world best practices.
 
 The tutorial is divided into the following sections:
 
-B<NOTE:> CLICK THESE LINKS TO JUMP TO CHAPTERS (the index links above
+B<NOTE: CLICK THESE LINKS TO JUMP TO CHAPTERS> (the index links above
 only navigate inside this page).
 
 =over 4
@@ -604,13 +604,14 @@ PostgreSQL content in the Appendix.
 =item *
 
 People who have emailed me with corrections and suggestions on the 
-tutorial.  As of the most recent release, this include: Florian Ragwitz, 
-Mauro Andreolini, Jim Howard, Giovanni Gigante, William Moreno,  Bryan 
-Roach, Ashley Berlin, David Kamholz, Kevin Old, Henning Sprang, Jeremy 
-Jones, David Kurtz, Ingo Wichmann, and Shlomi Fish.  Also, thanks to 
-Devin Austin for coming up with an initial version of a non-TTSite 
-wrapper page.  I'm sure I am missing some names here... apologies for 
-that (please let me know if you name should be here).
+tutorial.  As of the most recent release, this include: Florian 
+Ragwitz, Mauro Andreolini, Jim Howard, Giovanni Gigante, William 
+Moreno,  Bryan Roach, Ashley Berlin, David Kamholz, Kevin Old, Henning 
+Sprang, Jeremy Jones, David Kurtz, Ingo Wichmann, Shlomi Fish, Murray 
+Walker.  Also, thanks to Devin Austin for coming up with an initial 
+version of a non-TTSite wrapper page.  I'm sure I am missing some 
+names here... apologies for that (please let me know if you name 
+should be here).
 
 =back
 
diff --git a/lib/Catalyst/Manual/Tutorial/Authentication.pod b/lib/Catalyst/Manual/Tutorial/Authentication.pod
index 0410643..be80e98 100644
--- a/lib/Catalyst/Manual/Tutorial/Authentication.pod
+++ b/lib/Catalyst/Manual/Tutorial/Authentication.pod
@@ -158,7 +158,7 @@ C<lib/MyApp/Schema/Users.pm>:
     #   args:
     #     1) Name of relationship, DBIC will create accessor with this name
     #     2) Name of the model class referenced by this relationship
-    #     3) Column name in *foreign* table
+    #     3) Column name in *foreign* table (aka, foreign key in peer table)
     __PACKAGE__->has_many(map_user_role => 'MyApp::Schema::UserRoles', 'user_id');
     
     # many_to_many():
@@ -180,7 +180,7 @@ C<lib/MyApp/Schema/Roles.pm>:
     #   args:
     #     1) Name of relationship, DBIC will create accessor with this name
     #     2) Name of the model class referenced by this relationship
-    #     3) Column name in *foreign* table
+    #     3) Column name in *foreign* table (aka, foreign key in peer table)
     __PACKAGE__->has_many(map_user_role => 'MyApp::Schema::UserRoles', 'role_id');
 
 
diff --git a/lib/Catalyst/Manual/Tutorial/CatalystBasics.pod b/lib/Catalyst/Manual/Tutorial/CatalystBasics.pod
index 1de9f96..b288293 100644
--- a/lib/Catalyst/Manual/Tutorial/CatalystBasics.pod
+++ b/lib/Catalyst/Manual/Tutorial/CatalystBasics.pod
@@ -220,8 +220,7 @@ server:
     [info] Hello powered by Catalyst 5.7014
     You can connect to your server at http://localhost:3000
 
-Point your web browser to 
-L<http://localhost:3000|http://localhost:3000> (substituting a 
+Point your web browser to L<http://localhost:3000> (substituting a 
 different hostname or IP address as appropriate) and you should be 
 greeted by the Catalyst welcome screen.  Information similar to the 
 following should be appended to the logging output of the development 
@@ -323,13 +322,28 @@ To create a TT view, run:
     $ script/hello_create.pl view TT TT
 
 This creates the C<lib/Hello/View/TT.pm> module, which is a subclass of 
-C<Catalyst::View::TT>. The "view" keyword tells the create script that 
-you are creating a view, the second "TT" tells it that you are creating 
-a Template Toolkit view, and the first "TT" tells the script to name 
-the View module "TT.pm", which is a commonly used name for TT views. 
-(You can name it anything you want, such as "HTML.pm".) If you look at 
-TT.pm, you will find that it only contains a config statement to set 
-the TT extension to ".tt".
+C<Catalyst::View::TT>. 
+
+=over 4
+
+=item *
+
+The "view" keyword tells the create script that you are creating a view.
+
+=item *
+
+The first "TT" tells the script to name the View module "TT.pm", which is a
+commonly used name for TT views.  (You can name it anything you want, such as
+"HTML.pm".)
+
+=item *
+
+The final "TT" tells it that you are creating a Template Toolkit view.
+
+=back
+
+If you look at C<lib/Hello/View/TT.pm> you will find that it only contains a
+config statement to set the TT extension to ".tt".
 
 Now that the TT.pm "View" exists, Catalyst will autodiscover it and be 
 able to use it to display the view templates, using the "process" 
@@ -345,15 +359,17 @@ Create a C<root/hello.tt> template file (put it in the C<root> under
 the C<Hello> directory that is the base of your application). Here is 
 a simple sample:
   
-    [% META title = 'Hello, World!' %]
     <p>
-        This is a TT view template, located in the 'root/' directory.
+        This is a TT view template, called '[% template.name %]'.
     </p>
 
 [% and %] are markers for the TT parts of the template. Inside you can 
-access Perl variables and classes, and use TT directives. The rest of 
-the template is normal HTML. Change the hello method in 
-C<lib/Hello/Controller/Root.pm> to the following:
+access Perl variables and classes, and use TT directives. In this 
+case, we're using a special TT variable that defines the name of the 
+template file (C<hello.tt>).  The rest of the template is normal HTML. 
+
+Change the hello method in C<lib/Hello/Controller/Root.pm> to the 
+following:
 
     sub hello : Global {
         my ( $self, $c ) = @_;
@@ -361,13 +377,13 @@ C<lib/Hello/Controller/Root.pm> to the following:
         $c->stash->{template} = 'hello.tt';
     }
 
-This time, instead of doing C<$c-E<gt>response->body()>, you are setting 
+This time, instead of doing C<$c-E<gt>response-E<gt>body()>, you are setting 
 the value of the "template" hash key in the Catalyst "stash", an area 
 for putting information to share with other parts of your application. 
 The "template" key determines which template will be displayed at the 
 end of the method. Catalyst controllers have a default "end" action 
 for all methods which causes the first (or default) view to be 
-rendered (unless there's a C<$c-E<gt>response->body()> statement). So your 
+rendered (unless there's a C<$c-E<gt>response-E<gt>body()> statement). So your 
 template will be magically displayed at the end of your method.
 
 After saving the file, restart the development server, and look at 
@@ -395,16 +411,23 @@ In C<lib/Hello/Controller/Site.pm>, add the following method:
         $c->stash->{template} = 'site/test.tt';
     }
 
-Notice the "Local" attribute on the method. This will allow the action 
-to be executed on the "controller/method" URL, or, in this case, 
-"site/test", instead of at the root site URL, like "Global". It's not 
-actually necessary to set the template value, since by default TT will 
-attempt to render a template that follows the naming pattern 
-"controller/method.tt", and we're following that pattern here, but in 
-other situations you will need to specify the template (such as if 
-you've "forwarded" to the method, or if it doesn't follow the default 
-naming convention). We've also put the variable "name" into the stash, 
-for use in the template.
+Notice the "Local" attribute on the C<test> method. This will cause 
+the C<test> action (now that we have assigned an action type to the 
+method it appears as a controller "action" to Catalyst) to be executed 
+on the "controller/method" URL, or, in this case, "site/test".  We 
+will see additional information on controller actions throughout the 
+rest of the tutorial, but if you are curious take a look at 
+L<Catalyst::Manual::Intro/Actions>.
+
+It's not actually necessary to set the template value as we do here. 
+By default TT will attempt to render a template that follows the 
+naming pattern "controller/method.tt", and we're following that 
+pattern here. However, in other situations you will need to specify 
+the template (such as if you've "forwarded" to the method, or if it 
+doesn't follow the default naming convention).
+
+We've also put the variable "username" into the stash, for use in the 
+template.
 
 Make a subdirectory "site" in the "root" directory. Copy the hello.tt 
 file into the directory as C<root/site/test.tt>, or create a new 
diff --git a/lib/Catalyst/Manual/Tutorial/Intro.pod b/lib/Catalyst/Manual/Tutorial/Intro.pod
index fdce808..0454a3a 100644
--- a/lib/Catalyst/Manual/Tutorial/Intro.pod
+++ b/lib/Catalyst/Manual/Tutorial/Intro.pod
@@ -383,7 +383,7 @@ NetBSD Package Collection on Solaris
 
 The 2008 Advent Day 15 entry has more information on using C<pkgsrc> and 
 NetBSD packages on Solaris: 
-L<http://www.catalystframework.org/calendar/2008/15|>.
+L<http://www.catalystframework.org/calendar/2008/15>.
 
 =item * 
 
diff --git a/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod b/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
index 8c1734e..24c9157 100644
--- a/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
+++ b/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
@@ -140,20 +140,21 @@ very similar to Apache configuration files.  We will see how to use
 this feature of Catalyst during the authentication and authorization
 sections (Part 5 and Part 6).
 
-B<IMPORTANT NOTE:> If you are using a version of
-L<Catalyst::Devel|Catalyst::Devel> prior to version 1.06, you need to
-be aware that Catalyst changed from a default format of YAML to the
-more straightforward C<Config::General> format.  This tutorial use the
-newer C<myapp.conf> configuration file for C<Config::General> instead
-of C<myapp.yml> for YAML. However, Catalyst has long supported both
-formats and Catalyst will automatically use either C<myapp.conf> or
-C<myapp.yml> (or any other format supported by
-L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader> and
-L<Config::Any|Config::Any>).  If you are using a versions of
-Catalyst::Devel prior to 1.06, you can convert to the newer format by
-simply creating the C<myapp.conf> file manually and deleting
-C<myapp.yml>.  The default contents of C<myapp.conf> should only
-consist of one line: C<name MyApp>.
+B<IMPORTANT NOTE:> If you are using a version of 
+L<Catalyst::Devel|Catalyst::Devel> prior to version 1.06, be aware 
+that Catalyst changed the default format from YAML to the more 
+straightforward C<Config::General> style.  This tutorial uses the 
+newer C<myapp.conf> file for C<Config::General>. However, Catalyst 
+supports both formats and will automatically use either C<myapp.conf> 
+or C<myapp.yml> (or any other format supported by 
+L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader> and 
+L<Config::Any|Config::Any>).  If you are using a version of 
+Catalyst::Devel prior to 1.06, you can convert to the newer format by 
+simply creating the C<myapp.conf> file manually and deleting 
+C<myapp.yml>.  The default contents of the C<myapp.conf> you create 
+should only consist of one line: 
+
+    name MyApp
 
 B<TIP>: This script can be useful for converting between configuration
 formats:
@@ -161,10 +162,6 @@ formats:
     perl -Ilib -e 'use MyApp; use Config::General;
         Config::General->new->save_file("myapp.conf", MyApp->config);'
 
-B<NOTE:> The default C<myapp.conf> should look like:
-
-    name   MyApp
-
 =item *
 
 L<Catalyst::Plugin::Static::Simple|Catalyst::Plugin::Static::Simple>
@@ -664,19 +661,37 @@ starts:
     created "/home/me/MyApp/script/../t/model_DB.t"
 
 
+The C<script/myapp_create.pl> command breaks down like this:
+
+=over 4
+
+=item *
+
 C<DB> is the name of the model class to be created by the helper in 
-C<lib/MyApp/Model>.  C<DBIC::Schema> is the type of the model to 
-create. C<MyApp::Schema> is the name of the DBIC schema file written 
-to C<lib/MyApp/Schema.pm>.  Because we specified C<create=dynamic> to 
-the helper, it use 
+C<lib/MyApp/Model>.
+
+=item *
+
+C<DBIC::Schema> is the type of the model to create.
+
+=item *
+
+C<MyApp::Schema> is the name of the DBIC schema file written to
+C<lib/MyApp/Schema.pm>.
+
+=item *
+
+Because we specified C<create=dynamic> to the helper, it use 
 L<DBIx::Class::Schema::Loader|DBIx::Class::Schema::Loader> to 
 dynamically load the schema information from the database every time 
-the application starts. DBIC uses the schema to load other classes 
-that represent the tables in your database (DBIC refers to these 
-"table objects" as "result sources," see 
-L<DBIx::Class::ResultSource|DBIx::Class::ResultSource>). And finally, 
-C<dbi:SQLite:myapp.db> is the standard DBI connect string for use with 
-SQLite.
+the application starts.
+
+=item *
+
+And finally, C<dbi:SQLite:myapp.db> is the standard DBI connect string 
+for use with SQLite.
+
+=back
 
 B<NOTE:> Although the C<create=dynamic> option to the DBIC helper
 makes for a nifty demonstration, is only really suitable for very
@@ -712,8 +727,8 @@ C<[$c-E<gt>model('DB::Books')-E<gt>all]> and delete the next 2 lines):
         $c->stash->{template} = 'books/list.tt2';
     }
 
-B<TIP>: You may see the C<$c-E<gt>model('DB::Book')> un-commented 
-above written as C<$c-E<gt>model('DB')-E<gt>resultset('Book')>.  The 
+B<TIP>: You may see the C<$c-E<gt>model('DB::Books')> un-commented 
+above written as C<$c-E<gt>model('DB')-E<gt>resultset('Books')>.  The 
 two are equivalent.  Either way, C<$c-E<gt>model> returns a 
 L<DBIx::Class::ResultSet|DBIx::Class::ResultSet> which handles queries 
 against the database and iterating over the set of results that are 
@@ -736,9 +751,10 @@ and L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema>.
 
 =head2 Test Run The Application
 
-First, let's enable an environment variable option that causes
-DBIx::Class to dump the SQL statements it's using to access the database
-(this option can provide extremely helpful troubleshooting information):
+First, let's enable an environment variable that causes DBIx::Class to 
+dump the SQL statements usedß to access the database.  This is a 
+helpful trick when you are trying to debug your database-oriented 
+code:
 
     $ export DBIC_TRACE=1
 
@@ -1106,7 +1122,7 @@ comment:
     #   args:
     #     1) Name of relationship, DBIC will create accessor with this name
     #     2) Name of the model class referenced by this relationship
-    #     3) Column name in *foreign* table
+    #     3) Column name in *foreign* table (aka, foreign key in peer table)
     __PACKAGE__->has_many(book_authors => 'MyApp::Schema::BookAuthors', 'book_id');
     
     # many_to_many():
@@ -1148,7 +1164,7 @@ below the C<# DO NOT MODIFY THIS OR ANYTHING ABOVE!> comment):
     #   args:
     #     1) Name of relationship, DBIC will create accessor with this name
     #     2) Name of the model class referenced by this relationship
-    #     3) Column name in *foreign* table
+    #     3) Column name in *foreign* table (aka, foreign key in peer table)
     __PACKAGE__->has_many(book_author => 'MyApp::Schema::BookAuthors', 'author_id');
     
     # many_to_many():