Add additional information for transition from YAML to Config::General

[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / Tutorial / MoreCatalystBasics.pod

diff --git a/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod b/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
index c52f435..4c9fda5 100644 (file)
--- a/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
+++ b/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
@@ -133,12 +133,36 @@ free to make use of it in your own projects.
 L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader>
 
 C<ConfigLoader> provides an automatic way to load configurable
-parameters for your application from a central YAML file (versus having
-the values hard-coded inside your Perl modules).  If you have not been
-exposed to YAML before, it is a human-readable data serialization format
-that can be used to read (and write) values to/from text files.  We will
-see how to use this feature of Catalyst during the authentication and
-authorization sections (Part 5 and Part 6).
+parameters for your application from a central
+L<Config::General|Config::General> file (versus having the values
+hard-coded inside your Perl modules).  Config::General uses syntax
+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 following along in Ubuntu 8.04 or 
+otherwise using a version of Catalyst prior to v5.7014, you need to be 
+aware that Catalyst changed from a default format of YAML to the more 
+straightforward C<Config::General> format.  Because Catalyst has long 
+supported both formats, this tutorial will simply use a configuration 
+file called C<myapp.conf> instead of C<myapp.yml> and Catatlyst will 
+automcatically use the new format.  Just be aware that earlier versions 
+of Catalyst will still create the C<myapp.yml> file and that you will 
+need to B<remove C<myapp.yml>> and create a new C<myapp.conf> file by 
+hand, but otherwise this transition is very painless.  The default 
+contents of C<myapp.conf> should only consist of one line: C<name 
+MyApp>.  Also be aware that you can continue to use any format
+supported by 
+L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader> and 
+L<Config::Any|Config::Any>, including YAML -- Catalyst will 
+automatically look for any of the supported configuration file formats.
+
+C<TIP>: This script can be useful for converting between configuration 
+formats:
+
+    perl -Ilib -e 'use MyApp; use Config::General; 
+        Config::General->new->save_file("myapp.conf", MyApp->config);'
+
 
 =item *
 
@@ -570,13 +594,13 @@ in the past, Matt Trout's L<DBIx::Class|DBIx::Class> (abbreviated
 as "DBIC") has rapidly emerged as the Perl-based ORM technology of choice.  
 Most new Catalyst applications rely on DBIC, as will this tutorial.
 
-=head2 Create a Dynamic DBIC Model
+=head2 Create a DBIC Model
 
-Use the C<create=dynamic> model helper option to build a model that 
+Use the C<create=static> model helper option to build a model that 
 dynamically reads your database structure every time the application
 starts:
 
-    $ script/myapp_create.pl model MyAppDB DBIC::Schema MyApp::Schema::MyAppDB create=dynamic dbi:SQLite:myapp.db
+    $ script/myapp_create.pl model MyAppDB DBIC::Schema MyApp::Schema::MyAppDB create=static dbi:SQLite:myapp.db
      exists "/home/me/MyApp/script/../lib/MyApp/Model"
      exists "/home/me/MyApp/script/../t"
     created "/home/me/MyApp/script/../lib/MyApp/Schema"
@@ -597,13 +621,6 @@ the schema information from the database every time the application
 starts.  And finally, C<dbi:SQLite:myapp.db> is the standard DBI connect 
 string for use with SQLite.
 
-B<NOTE>: Although the C<create=dynamic> option to the DBIC helper 
-makes for a nifty demonstration, is not suitable for real world 
-applications. Moreover, it may not be supported in future versions of 
-DBIC.  After this demonstration, please use the C<create=static> 
-option that we switch to below.
-
-
 =head1 RUN THE APPLICATION
 
 First, let's enable an environment variable option that causes