From: Matt S Trout <mst@shadowcat.co.uk>
Date: Thu, 22 Jun 2006 14:50:57 +0000 (+0000)
Subject: Editing and neatening in ChildOf docs
X-Git-Tag: 5.7099_04~499
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=commitdiff_plain;h=2c23b46d57d31a415a6676656ea86d26599af52a

Editing and neatening in ChildOf docs
r10022@cain (orig r4381):  jester | 2006-06-13 19:31:40 +0000
---

diff --git a/lib/Catalyst/Manual/Intro.pod b/lib/Catalyst/Manual/Intro.pod
index 5e3e764..5bdac66 100644
--- a/lib/Catalyst/Manual/Intro.pod
+++ b/lib/Catalyst/Manual/Intro.pod
@@ -349,12 +349,8 @@ this:
     }
     1;
 
-
 =back
 
-For most applications, Catalyst requires you to define only one config
-parameter:
-
 =head4 Action types
 
 Catalyst supports several types of actions:
@@ -425,10 +421,9 @@ L</URL Path Handling> below.
 
     sub section :PathPart('section') :ChildOf('/') :Captures(1) { }
 
-ChildOf is a powerful way to handle canonical URIs of the form 
-/section/1/item/2 
-
-Taking the above URI as an example in Controller::Root you can do the following :-
+ChildOf is a powerful way to handle canonical URIs of the form
+C<http://localhost:3000/section/1/item/2>. Using this URI as an example,
+in Controller::Root you can do the following:
 
   sub section_handler :PathPart('section') :ChildOf('/') :Captures(1) {
       my ( $self, $c ) = @_;
@@ -436,34 +431,40 @@ Taking the above URI as an example in Controller::Root you can do the following
         $c->Model('Sections')->find($c->req->captures->[0]);
   }
 
-  sub item_handler :PathPart('item') :ChildOf('/section_handler') :Args(1) {
+  sub item_handler :PathPart('item') :ChildOf('/section') :Args(1) {
       my ( $self, $c ) = @_;
       $c->stash->{'item'} =
         $c->stash->{'section'}->find_related('item',$c->args->[0]);
   }
 
-The subroutine section_handler matched the path segment 'section' as a child of '/'. It 
-then took the next path segment, as referenced by :Captures(1) and stashed it in the 
-arrayref $c->req->captures. Since there was also a child of this handler - it also gets run.
-The same rules apply here - This time however it has the 'Args' attribute which means
-this particular routine will run if there is exactly 1 argument. See Args below for more 
-options.
+The subroutine C<section_handler> matches the path segment "section" as
+a child of "/". It then takes the next path segment, as referenced by
+C<:Captures(1)>, and stashes it in the arrayref
+C<$c-E<gt>req-E<gt>captures>. Since there is also a child of this
+handler, it also gets run, functioning in the same way. However, the
+C<item_handler> subroutine has the C<Args> attribute which means this
+particular routine will only run if there is exactly one argument. See
+L</Args> below for more options.
+
+A parent action can be in any controller or namespace.  
 
-It is not important in which controller or on which namespace level a parent action is.
-Also, there can be more than one action using another one as parent by specifying C<ChildOf>.
+Multiple actions can specify the same parent action in their C<ChildOf>;
+that is, one action can have multiple children.
 
 =item ChildOf('xyz')
 
-The action of the parent - for instance, if you have method item_handler in controller
-SuperMarket::Aisle, the action would be /supermarket/aisle/item_handler. For a root handler
-this would be '/'. For an action in the same controller namespace you can use a relative
-name like C<:ChildOf('foo')>.
+The action of the parent. For instance, if you have a method
+C<item_handler> in the controller C<SuperMarket::Aisle>, the action
+would be C</supermarket/aisle/item_handler>. For a Root handler this
+would be '/'. For an action in the same controller namespace you can use
+a relative name like C<:ChildOf('foo')>.
 
 =item PathPart('xyz')
 
-The name of this path section in the ChildOf tree mapping to the URI. If you specify 
-C<:PathPart> without arguments, it takes the name of the action specifying the argument.
-For example, these two declarations have the same effect:
+The name of this path section in the ChildOf tree mapping to the URI. If
+you specify C<:PathPart> without arguments, it takes the name of the
+action specifying the argument.  For example, these two declarations
+have the same effect:
 
   sub foo :PathPart('foo') :ChildOf('bar') :Args(1) {
       ...
@@ -483,19 +484,20 @@ The value can also contain a slash, for example:
 
 would be involved in matches on C</bar/baz/*/...> paths.
 
-=item Captures(int)
+=item Captures(integer)
 
-Will 'collapse' the next x path segments in the request URI and push them into 
-the arrayref $c->req->captures. An action specifying C<Captures> is thought to
-be used as target for C<ChildOf> specifications. Also see the C<Args> attribute
-below, which is used for endpoints.
+Will 'collapse' the next C<integer> path segments in the request URI and
+push them into the arrayref C<$c-E<gt>req-E<gt>captures>. An action
+specifying C<Captures> is thought to be used as target for C<ChildOf>
+specifications. Also see the C<Args> attribute below, which is used for
+endpoints.
 
 =item Args(int)
 
-The number of path segments to capture at the end of a request URI. This *must* be
-included in your leaf nodes. You can use Args(0) for an equivalent of the index
-action.
-Args with no parameters will capture every postfixed segment into $c->req->args.
+The number of path segments to capture at the end of a request URI. This
+B<must> be included in your leaf nodes. You can use C<Args(0)> for an
+equivalent of the index action.  Args with no parameters will capture
+every postfixed segment into C<$c-E<gt>req-E<gt>args>.
 
 A specification of C<Args> is seen as endpoint in regard to an additional
 C<ChildOf> specification.