simplified synopsis and created deployment pod

diff --git a/lib/Web/Simple.pm b/lib/Web/Simple.pm
index bca9d85..b448799 100644 (file)
--- a/lib/Web/Simple.pm
+++ b/lib/Web/Simple.pm
@@ -39,18 +39,15 @@ Web::Simple - A quick and easy way to build simple web applications
 
   #!/usr/bin/env perl
 
-  use Web::Simple 'HelloWorld';
+  package HelloWorld;
+  use Web::Simple
 
-  {
-    package HelloWorld;
-
-    sub dispatch_request {
-      sub (GET) {
-        [ 200, [ 'Content-type', 'text/plain' ], [ 'Hello world!' ] ]
-      },
-      sub () {
-        [ 405, [ 'Content-type', 'text/plain' ], [ 'Method not allowed' ] ]
-      }
+  sub dispatch_request {
+    sub (GET) {
+      [ 200, [ 'Content-type', 'text/plain' ], [ 'Hello world!' ] ]
+    },
+    sub () {
+      [ 405, [ 'Content-type', 'text/plain' ], [ 'Method not allowed' ] ]
     }
   }
 
@@ -60,9 +57,13 @@ If you save this file into your cgi-bin as C<hello-world.cgi> and then visit:
 
   http://my.server.name/cgi-bin/hello-world.cgi/
 
-you'll get the "Hello world!" string output to your browser. For more complex
-examples and non-CGI deployment, see below. To get help with L<Web::Simple>,
-please connect to the irc.perl.org IRC network and join #web-simple.
+you'll get the "Hello world!" string output to your browser. At the same time
+this file will also act as a class module, so you can save it as HelloWorld.pm
+and use it as-is in test scripts or other deployment mechanisms.
+
+For more complex examples and non-CGI deployment, see
+L<Web::Simple::Deployment>. To get help with L<Web::Simple>, please connect to
+the irc.perl.org IRC network and join #web-simple.
 
 =head1 DESCRIPTION
 

diff --git a/lib/Web/Simple/Deployment.pod b/lib/Web/Simple/Deployment.pod
new file mode 100644 (file)
index 0000000..b480c3d
--- /dev/null
+++ b/lib/Web/Simple/Deployment.pod
@@ -0,0 +1,70 @@
+=head1 NAME
+
+Web::Simple::Deployment - various deployment options
+
+=head1 DESCRIPTION
+
+This file documents common deployment methods for Web::Simple. If you feel one
+is missing, please ask in the IRC channel and we'll work with you to add it.
+
+=head1 CGI
+
+The most basic deployment option is as a CGI script loading and running your
+Web::Simple-module:
+
+  #!/usr/bin/env perl
+
+  use Your::Web::Simple::App;
+  Your::Web::Simple::App->run_if_script;
+
+Save that as script.cgi and your web server will handle it correctly.
+
+=head2 Self-contained CGI
+
+Sometimes your app is so small that you have only one or two tiny classes that
+you want to run as a CGI script. Web::Simple offers a helpful mechanism to
+achieve that.
+
+  #!/usr/bin/env perl
+
+  use Web::Simple 'HelloWorld';   # enables strictures and warnings for the file
+                                  # additionally, HelloWorld is upgraded to a
+                                  # Web::Simple application
+  {
+    package HelloWorld;
+
+    sub dispatch_request {
+      sub (GET) {
+        [
+          200,
+          [ 'Content-type', 'text/plain' ],
+          [ 'Hello world! It is a fine ' . HelloWorld::Helper->day ]
+        ]
+      },
+      sub () {
+        [ 405, [ 'Content-type', 'text/plain' ], [ 'Method not allowed' ] ]
+      }
+    }
+  }
+
+  {
+    package HelloWorld::Helper;
+
+    use DateTime;
+
+    sub day {
+      return DateTime->now->day_name;
+    }
+  }
+
+  HelloWorld->run_if_script;
+
+=head1 AUTHORS
+
+See L<Web::Simple> for authors.
+
+=head1 COPYRIGHT AND LICENSE
+
+See L<Web::Simple> for the copyright and license.
+
+=cut