[Catalyst-commits] r12388 - trunk/examples/CatalystAdvent/root/2009

[jester at dev.catalyst.perl.org]

Author: jester
Date: 2009-12-15 21:38:13 +0000 (Tue, 15 Dec 2009)
New Revision: 12388

Modified:
   trunk/examples/CatalystAdvent/root/2009/14.pod
   trunk/examples/CatalystAdvent/root/2009/15.pod
Log:
minor Advent edits

Modified: trunk/examples/CatalystAdvent/root/2009/14.pod
===================================================================
--- trunk/examples/CatalystAdvent/root/2009/14.pod	2009-12-15 10:21:32 UTC (rev 12387)
+++ trunk/examples/CatalystAdvent/root/2009/14.pod	2009-12-15 21:38:13 UTC (rev 12388)
@@ -1,4 +1,4 @@
-=head1 A Catalyst Carol
+=head1 Graphing Your Catalyst Application
 
 Sometimes our Catalyst applications are so large, with such complex
 business rules, that we could get a little overwhelmed by their myriad
@@ -13,10 +13,10 @@
 =head2 Ghost...erm...Graph of Model Past
 
 The amazing L<SQL::Translator|http://search.cpan.org/perldoc?SQL::Translator> 
-module can easily show you what your application's Schema looks like 
+module can easily show you what your application's schema looks like 
 directly from your database schema - be it MySQL, Oracle, PostreSQL, SQLite, 
 or any of the several other database parsers available. Just specify 
-it in the 'from' field, while choosing 'GraphViz' as destination.
+it in the "from" field, while choosing "GraphViz" as destination.
 
   use SQL::Translator;
 
@@ -27,7 +27,7 @@
 
   $translator->translate( 'MySchema.sql' );
 
-If you are using Catalyst with the ever popular DBIx::Class (DBIC) and
+If you are using Catalyst with the ever-popular DBIx::Class (DBIC) and
 would rather fetch database information from the schema modules,
 rejoice! Use C<< SQL::Translator::Parser::DBIx::Class >> as the
 parser, and pass the loaded schema in the "parser_args" parameter. The
@@ -104,7 +104,7 @@
   $graph->run;
 
 If the code above is successful, C<$graph> now holds a Graph::Easy object
-storing the actions graph. We can use the 'dot' external program
+storing the actions graph. We can use the C<dot> external program
 to output the result as a png file:
 
   if ( open( my $png, '|-', 'dot -Tpng -o ' . $graph->output ) ) {
@@ -134,7 +134,7 @@
 
 =head2 Graph of Template Future
 
-Just like schema and actions, you can view your entire template
+Just like the schema and actions, you can view your entire template
 structure as a directed graph. The
 L<Template::AsGraph|http://search.cpan.org/perldoc?Template::AsGraph>
 module can be easily invoked to generate such data from any template

Modified: trunk/examples/CatalystAdvent/root/2009/15.pod
===================================================================
--- trunk/examples/CatalystAdvent/root/2009/15.pod	2009-12-15 10:21:32 UTC (rev 12387)
+++ trunk/examples/CatalystAdvent/root/2009/15.pod	2009-12-15 21:38:13 UTC (rev 12388)
@@ -1,14 +1,23 @@
 =head1 Transactions and DBIx::Class
 
-Database transactions help ensure the integrity and consistency of your data.
-Here I will present a few (contrived) examples where they are useful.
+Database transactions help ensure the integrity and consistency of your
+data.  In brief, a transaction wraps a group of related data operations
+which must function together or the entire group will fail. The classic
+example is a purchase made by check: the amount of the payment must be
+added to the recipient's bank account and removed from the payer's bank
+account together. If the database crashes, or if either operation fails,
+the entire transaction will fail, and the database will be unaffected.
 
+Here I will present a few (contrived) examples where they are
+useful.
+
 =head2 Atomicity
 
-Often a Model operation, in the sense of business logic, requires a group of
-closely related (or dependent) database operations.  These should be
-atomic.  That is if any single operation in the group fails, then the whole
-group of operations will fail and your data remains consistent.
+Often a Model operation, in the sense of business logic, requires a
+group of closely related (or dependent) database operations.  These
+should be atomic.  That is, if any single operation in the group fails,
+then the whole group of operations will fail and your data remains
+consistent.
 
 Suppose you wrote some code such as:
 
@@ -41,10 +50,11 @@
 What could possibly go wrong between them? Lots of things, such as the web
 server going down in flames, the database server crashing, alien invasion, and
 so on. While the chances of this are small, repairing erroneous data in a
-database is a painful, expensive and hazardous process.
+database is a painful, expensive, and hazardous process.
 
-Also we had to use an unnatural control flow here, normally we'd validate the
-token before it is created, rather than before the user is created.
+Also, we had to use an unnatural control flow here: normally we'd
+validate the token before it is created, rather than before the user is
+created.
 
 Enter C<txn_do>, from L<DBIx::Class::Schema>.
 
@@ -76,7 +86,7 @@
 It is also recommended to factor out database code into the relevant
 L<DBIx::Class::ResultSet> methods. ResultSet classes go into the
 C<lib/MyApp/Schema/ResultSet> directory (for example), next to the C<Result>
-directory and inherit from C<DBIx::Class::ResultSet>.
+directory, and inherit from C<DBIx::Class::ResultSet>.
 
 =head2 txn_scope_guard
 
@@ -90,7 +100,7 @@
 This can be useful if you don't want to deal with catching exceptions from
 C<txn_do>.  Another reason you might choose to use C<txn_scope_guard> over
 C<txn_do> is that C<txn_do> will attempt to reconnect to the database and
-re-run your code if you lost your connection; C<txn_scope_guard> does not
+re-run your code if you lose your connection; C<txn_scope_guard> does not
 have this overhead.
 
 Here's the previous example using C<txn_scope_guard>:
@@ -127,7 +137,7 @@
 
 =head2 Nested Transactions
 
-Many databases support a feature called 'savepoints', which are nested
+Many databases support a feature called "savepoints", which are nested
 transactions. They allow you to roll back a group of operations that are part
 of a larger group of operations.
 
@@ -164,9 +174,9 @@
         });
     }
 
-In this example, we are validating a batch of URLs, if any single URL fails it
-will not be added to any tables in the database, if they all fail then nothing
-will be added to the database.
+In this example, we are validating a batch of URLs. If any single URL
+fails, it will not be added to any tables in the database; if they all
+fail, nothing will be added to the database.
 
 =head2 Transactions, a good idea!