[Catalyst-dev] Tutorial documentation fixes - branch review request

[Tom Eliaz]

Good day Catalyst developers,

I'm new to catalyst, so I followed the tutorial in the manual. I
spotted a few small issues that may need fixing, and I created a
branch with my suggested changes hoping you may find some of them
helpful. Since I was playing with the tutorial, I also took a look at
the open Manual bugs on rt to see if I could fix any. I was able to
fix one (49825), and I noticed that a few others which are open are
actually already fixed. I included my novice triage below.

My updates to the Tutorial can be found in the branch:
http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.80/branches/tome_tutorial_fixes

I updated this branch using git svn, and I haven't used that tool much
in the past so I may have made some mistakes.

Thanks to everyone who has helped me on #catalyst thusfar.

Tom E

Below is:
1- Branch Changes: My checkin comment describing the changes I made in my branch
2- RT Bugs: My look at some open Tutorial rt bugs
3- The Diff of my branch changes for your convenience

1. BRANCH CHANGES
Tutorial/03_MoreCatalystBasics.pod
- Change two references from DBIx::Class:Schema::Loader to
DBIx::Class::Schema::Loader
- Remove reference to components=timestamp (not in the command, only
in description) since Tutorial/04 is where it is first used, and there
it is described as being added to the command.

Tutorial/04_BasicCRUD.pod
- properly indent pod for author_count sub (it should be in the sub
example, not as pod in the tutorial).

Tutorial/05_Authentication.pod
- The myapp.conf configuration for Plugin::Authentication has the
use_session 1 entry. However, use_session  is not explicit in the
MyApp.pm example above this section. Since use_session is not required
(Catalyst::Plugin::Session is being used) and it does not exist in the
MyApp.pm which the conf is supposed to follow and it is not discussed
in the tutorial text, I suggest we omit it.

Tutorial/08_Testing.pod
- Change test for 'Create' to 'Admin Create' (see bug #49825
http://rt.cpan.org/Public/Bug/Display.html?id=49825)


2. RT BUGS
- http://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual

Fixed By Me Above:
- #49825: Typo in sample code
  Fixed test code

Fixed Already: (I suggest closing as fixed)
- #42062: Error in grammar of tutorial
  This is already fixed
- #42050: Misleading direction in tutorial
  This is already fixed

Not Reproducible: (I suggest returning to submitter)
- #48953: Bad example code
  I don't see this bug, the hello method is created in the preceding section.
- #46664: Possible error in Catalyst::Manual::Tutorial re: roles
  I didn't have this problem, and it seems as if the user is not using TT.


3. DIFF
diff --git a/lib/Catalyst/Manual/Tutorial/03_MoreCatalystBasics.pod
b/lib/Catalyst/Manual/Tutorial/
index ffd01be..c2fc6fe 100644
--- a/lib/Catalyst/Manual/Tutorial/03_MoreCatalystBasics.pod
+++ b/lib/Catalyst/Manual/Tutorial/03_MoreCatalystBasics.pod
@@ -649,13 +649,13 @@ required if you do a single SQL statement on the
command line).  Use
 your OS command prompt.

 Please note that here we have chosen to use 'singular' table names. This
-is because the default inflection code for L<DBIx::Class:Schema::Loader>
+is because the default inflection code for L<DBIx::Class::Schema::Loader>
 does NOT handle plurals. There has been much philosophical discussion
 on whether table names should be plural or singular. There is no one
 correct answer, as long as one makes a choice and remains consistent
 with it. If you prefer plural table names (e.g. they are easier and
 more natural to read) then you will need to pass it an inflect_map
-option. See L<DBIx::Class:Schema::Loader> for more information.
+option. See L<DBIx::Class::Schema::Loader> for more information.

 For using other databases, such as PostgreSQL or MySQL, see
 L<Appendix 2|Catalyst::Manual::Tutorial::10_Appendices>.
@@ -754,11 +754,6 @@ into files.

 =item *
castro% cat /tmp/gitdiff
diff --git a/lib/Catalyst/Manual/Tutorial/03_MoreCatalystBasics.pod
b/lib/Catalyst/Manual/Tutorial/03_MoreCatalystBasics.pod
index ffd01be..c2fc6fe 100644
--- a/lib/Catalyst/Manual/Tutorial/03_MoreCatalystBasics.pod
+++ b/lib/Catalyst/Manual/Tutorial/03_MoreCatalystBasics.pod
@@ -649,13 +649,13 @@ required if you do a single SQL statement on the
command line).  Use
 your OS command prompt.

 Please note that here we have chosen to use 'singular' table names. This
-is because the default inflection code for L<DBIx::Class:Schema::Loader>
+is because the default inflection code for L<DBIx::Class::Schema::Loader>
 does NOT handle plurals. There has been much philosophical discussion
 on whether table names should be plural or singular. There is no one
 correct answer, as long as one makes a choice and remains consistent
 with it. If you prefer plural table names (e.g. they are easier and
 more natural to read) then you will need to pass it an inflect_map
-option. See L<DBIx::Class:Schema::Loader> for more information.
+option. See L<DBIx::Class::Schema::Loader> for more information.

 For using other databases, such as PostgreSQL or MySQL, see
 L<Appendix 2|Catalyst::Manual::Tutorial::10_Appendices>.
@@ -754,11 +754,6 @@ into files.

 =item *

-C<components=TimeStamp> causes the help to include the
-L<DBIx::Class::TimeStamp|DBIx::Class::TimeStamp> DBIC component.
-
-=item *
-
 And finally, C<dbi:SQLite:myapp.db> is the standard DBI connect string
 for use with SQLite.

diff --git a/lib/Catalyst/Manual/Tutorial/04_BasicCRUD.pod
b/lib/Catalyst/Manual/Tutorial/04_BasicCRUD.pod
index dfee243..f8f3467 100644
--- a/lib/Catalyst/Manual/Tutorial/04_BasicCRUD.pod
+++ b/lib/Catalyst/Manual/Tutorial/04_BasicCRUD.pod
@@ -1362,9 +1362,9 @@ clean this up.  First, let's add a method to our
Book Result Class to
 return the number of authors for a book.  Open
 C<lib/MyApp/Schema/Result/Book.pm> and add the following method:

-=head2 author_count
+    =head2 author_count

-Return the number of authors for the current book
+    Return the number of authors for the current book

     =cut

diff --git a/lib/Catalyst/Manual/Tutorial/05_Authentication.pod
b/lib/Catalyst/Manual/Tutorial/05_Authentication.pod
index 5effaac..7872409 100644
--- a/lib/Catalyst/Manual/Tutorial/05_Authentication.pod
+++ b/lib/Catalyst/Manual/Tutorial/05_Authentication.pod
@@ -334,7 +334,6 @@ for the tutorial, but if you wish to use
C<myapp.conf>, just convert
 to the following code:

     <Plugin::Authentication>
-        use_session 1
         <default>
             password_type clear
             user_model    DB::User
diff --git a/lib/Catalyst/Manual/Tutorial/08_Testing.pod
b/lib/Catalyst/Manual/Tutorial/08_Testing.pod
index 2776f6f..95bb753 100644
--- a/lib/Catalyst/Manual/Tutorial/08_Testing.pod
+++ b/lib/Catalyst/Manual/Tutorial/08_Testing.pod
@@ -270,7 +270,7 @@ editor and enter the following:
     # Make sure the appropriate logout buttons are displayed
     $_->content_contains("/logout\">User Logout</a>",
         "Both users should have a 'User Logout'") for $ua1, $ua2;
-    $ua1->content_contains("/books/form_create\">Create</a>",
+    $ua1->content_contains("/books/form_create\">Admin Create</a>",
         "Only 'test01' should have a create link");

     $ua1->get_ok("http://localhost/books/list", "View book list as 'test01'");