Updated all the documentation and wrote more docs for the win32 service support.

git-svn-id: svn+ssh://rubyforge.org/var/svn/mongrel/trunk@58 19e92222-5c0b-0410-8929-a290d50e31e9

README

@@ -14,7 +14,8 @@ scream without too many portability issues.
 The 0.3.6 release supports Ruby On Rails much better than previously, and also
 sports the beginning of a command and plugin infrastructure.  There is now a more
 complete CGIWrapper that handles most of the CGI usage, but still doesn't do the
-MIME decoding or file upload/send (it leaves that to CGI).
+MIME decoding or file upload/send (it leaves that to CGI).  Finally, there's a
+great mongrel_rails_service script for running under Win32 as a service.
 
 After you've installed (either with gem install mongrel or via source) you should
 have the mongrel_rails command available in your PATH.  Then you just do the following:
@@ -42,6 +43,32 @@ There are also many more new options for configuring the rails runner including
 changing to a different directory, adding more MIME types, and setting processor
 threads and timeouts.
 
+
+=== Win32 Service Support
+
+Mongrel now has support for running as a Win32 service right out of the
+box.  The support is still rough but works well enough that we decided
+to release it.  You can thank Luis Lavena for working on this and making
+it so nice.
+
+After you do the gem install, find a Rails application you want to run
+and do:
+
+ $ mongrel_rails_service install -n myapp \ 
+     -r c:\my\path\to\myapp -p 4000 -e production
+ $ mongrel_rails_service start -n myapp
+
+Now hit the port and poof, works.  *Stopping the service is a little problematic right now.*
+
+If you run into an app that's not running right, my suggestion is to run it with
+the regular mongrel_rails runner:
+
+ $ cd c:\my\path\to\myapp
+ $ mongrel_rails start -p 4500
+
+Since that will spit out error messages and stuff to the console.  *Use CTRL-Pause/Break to stop.*
+
+
 == Install
 
 It doesn't explicitly require Camping, but if you want to run the examples/camping/

doc/site/src/attributions.page

@@ -10,6 +10,12 @@ There's quite a few people who either directly or indirectly helped to
 make Mongrel.  If I missed anyone then just e-mail me and I'll put your
 name here.
 
+* Mongrel was started by "Zed A. Shaw":http://www.zedshaw.com/
+* Win32 support for services was done by Luis Lavena.
+* Specialized Win32 gems were setup by Wilson Bilkovich.
+
+Also with lots of testing from tons of people who are really appreciated.
+
 h2. Site Template
 
 The site's look and template is blatantly stolen from "OWD":http://openwebdesign.org

doc/site/src/default.template

@@ -46,15 +46,27 @@
         <h4>NEWS</h4>
 
         <dl>
+          <dt>Feb-22-2006</dt>
+          <dd>
+            <h5><a href="{relocatable: news.html}">Mongrel 0.3.6 -- Win32 Service!</a></h5>
+
+            <p>This release is gonna make the win32 folks scream.  Runs Rails great, can
+	    host the whole Rails app, and <b>has a full win32 service runner.</b>
+	    </p>
+	      <a href="http://rubyforge.org/frs/?group_id=1306" title="Downloads">Download</a>
+	      <a href="{relocatable: news.html}"><img src="{relocatable: images/li4.gif}" alt="more" /><br /></a></p>
+          </dd>
+
           <dt>Feb-18-2006</dt>
           <dd>
             <h5><a href="{relocatable: news.html}">Mongrel 0.3.5 -- CGI Fixed</a></h5>
 
             <p>A complete rewrite of the CGIWrapper that actually works.</p>
 	      <a href="http://rubyforge.org/frs/?group_id=1306" title="Downloads">Download</a>
-	      <a href="{relocatable: news.html}"><img src="images/li4.gif" alt="more" /><br /></a></p>
+	      <a href="{relocatable: news.html}"><img src="{relocatable: images/li4.gif}" alt="more" /><br /></a></p>
           </dd>
 
+
           <dt>Feb-16-2006</dt>
           <dd>
             <h5><a href="{relocatable: news.html}">Mongrel 0.3.4 -- Win32 Baby</a></h5>
@@ -62,7 +74,7 @@
             <p>CGI cleanups getting closer to full Rails support.  Win32 pre-built gems
 	    available.</p>
 	      <a href="http://rubyforge.org/frs/?group_id=1306" title="Downloads">Download</a>
-	      <a href="{relocatable: news.html}"><img src="images/li4.gif" alt="more" /><br /></a></p>
+	      <a href="{relocatable: news.html}"><img src="{relocatable: images/li4.gif}" alt="more" /><br /></a></p>
           </dd>
 
           <dt>Feb-14-2006</dt>
@@ -71,7 +83,7 @@
 
             <p>Very small bug fix that repairs a missing require.</p>
 	      <a href="http://rubyforge.org/frs/?group_id=1306" title="Downloads">Download</a>
-	      <a href="{relocatable: news.html}"><img src="images/li4.gif" alt="more" /><br /></a></p>
+	      <a href="{relocatable: news.html}"><img src="{relocatable: images/li4.gif}" alt="more" /><br /></a></p>
           </dd>
 
           <dt>Feb-13-2006</dt>
@@ -81,7 +93,7 @@
             <p>Lots of little fixes and enhancements on the 0.3.1 release.  Still need to test
 	      this release on win32.
 	      <a href="http://rubyforge.org/frs/?group_id=1306" title="Downloads">Download</a>
-	      <a href="{relocatable: news.html}"><img src="images/li4.gif" alt="more" /><br /></a></p>
+	      <a href="{relocatable: news.html}"><img src="{relocatable:images/li4.gif}" alt="more" /><br /></a></p>
           </dd>
 
           <dt>Feb-12-2006</dt>
@@ -92,7 +104,7 @@
             <p><a href="http://rubyforge.org/frs/?group_id=1306" title="Downloads">
 		Download</a> the 0.3.1 release featuring better Rails support and a 
 		major bug fix.
-	      <a href="{relocatable: news.html}"><img src="images/li4.gif" alt="more" /><br /></a></p>
+	      <a href="{relocatable: news.html}"><img src="{relocatable: images/li4.gif}" alt="more" /><br /></a></p>
           </dd>
 
           <dt>Feb-12-2006</dt>
@@ -101,7 +113,7 @@
             <h5><a href="{relocatable: news.html}">Site now up!</a></h5>
 
             <p>The new website is up and now running. 
-	      <a href="{relocatable: news.html}"><img src="images/li4.gif" alt="more" /><br /></a></p>
+	      <a href="{relocatable: news.html}"><img src="{relocatable: images/li4.gif}" alt="more" /><br /></a></p>
           </dd>
         </dl>
       </div>
@@ -117,34 +129,34 @@
       </div>
 
       <dl id="ads">
-        <dt><a href="http://rubyforge.org/frs/?group_id=1306" title="Downloads"><img src="images/3colls_p3.jpg" /></a><br /></a></dt>
+        <dt><a href="http://rubyforge.org/frs/?group_id=1306" title="Downloads"><img src="{relocatable: images/3colls_p3.jpg}" /></a><br /></a></dt>
         <dd>
           <p><b>Downloads:</b> Grab new gear.</p>
         </dd>
 
-        <dt><a href="{relocatable: documentation.html}" title="Documentation"><img src="images/3colls_p2.jpg" /></a><br /></a></dt>
+        <dt><a href="{relocatable: docs/index.html}" title="Documentation"><img src="{relocatable: images/3colls_p2.jpg}" /></a><br /></a></dt>
         <dd>
           <p><b>Documentation:</b>  RTFM.</p>
         </dd>
 
-        <dt><a href="http://rubyforge.org/tracker/?atid=5145&group_id=1306&func=browse"><img src="images/side_p2.gif" alt="Bugs" /><br /></a></dt>
+        <dt><a href="http://rubyforge.org/tracker/?atid=5145&group_id=1306&func=browse"><img src="{relocatable: images/side_p2.gif}" alt="Bugs" /><br /></a></dt>
         <dd>
           <p><b>Tracker:</b> Found a bug? Well then report it already?!</p>
         </dd>
 
-        <dt><a href="http://rubyforge.org/forum/?group_id=1306"><img src="images/side_p1.gif" alt=
+        <dt><a href="http://rubyforge.org/forum/?group_id=1306"><img src="{relocatable: images/side_p1.gif}" alt=
         "Sad Dog" /><br /></a></dt>
         <dd>
           <p><b>Forums:</b> Mongrel making you sad? Why not say something?</p>
         </dd>
 
         <dt>
-<a href="http://rubyforge.org/project/memberlist.php?group_id=1306" title="Contact"><img src="images/3colls_p1.jpg" /></a><br /></a></dt>
+<a href="http://rubyforge.org/project/memberlist.php?group_id=1306" title="Contact"><img src="{relocatable: images/3colls_p1.jpg}" /></a><br /></a></dt>
         <dd>
           <p><b>People:</b> Contact project people.</p>
         </dd>
 
-        <dt><a href="http://rubyforge.org/projects/mongrel/"><img src="images/side_p3.gif" alt=
+        <dt><a href="http://rubyforge.org/projects/mongrel/"><img src="{relocatable: images/side_p3.gif}" alt=
         "Tools" /><br /></a></dt>
         <dd>
           <p><b>Other:</b> Hit the project page for all sorts of other

doc/site/src/docs/howto.page

@@ -0,0 +1,12 @@
+---
+title: HOWTO
+inMenu: true
+directoryName: Documentation
+---
+
+h1.  Mongrel HOWTO
+
+Coming soon...
+
+
+

doc/site/src/docs/index.page

@@ -2,11 +2,20 @@
 title: Documentation
 inMenu: true
 directoryName: Documentation
-ordering: 3
 ---
 
 h1. Available Documentation
 
+We've got a small set of documentation to get people going.  Most of it is 
+geared toward Ruby on Rails but other projects using Mongrel should have their own
+docs that you can refer to based on these.
+
+* "Getting Started":started.html -- Installing and Other things
+* "HOWTO":howto.html -- Doing advanced stuff with Mongrel.
+* "Win32 HOWTO":win32.html -- Specific instructions for running on windows.
+
+If there's documentation you'd like then feel free to e-mail the list or post
+to the tracker.
 
 h2. RDoc API Documentation
 

doc/site/src/docs/started.page

@@ -0,0 +1,94 @@
+---
+title: Getting Started
+inMenu: true
+directoryName: Documentation
+---
+
+h1.  Getting Started
+
+The easiest way to get started with Mongrel is to install it via RubyGems
+and then run a Ruby on Rails application.  You can do this easily:
+
+ $ sudo gem install mongrel
+ $ cd myrailsapp
+ $ mongrel_rails start -d
+
+Which runs Mongrel in the background.  You can stop it with:
+
+ $ mongrel_rails stop
+
+And you're all set.  There's quite a few options you can set for the
+start command.  Use the *mongrel_rails start -h* to see them all.
+
+
+h2. Win32 Install
+
+Windows has a slight difference since it seems that the win32-service doesn't
+get picked up for some people as a dependency.  You'll need to do this instead:
+
+ $ gem install win32-service (pick the most recent one)
+ $ gem install mongrel (pick the win32 pre-built)
+
+Now you're installed.  "Read the Win32 HOWTO for more instructions.":win32.html
+
+
+h2. Updating
+
+You should be able to do an *gem update* and get the latest version of Mongrel
+on any platform you've already installed it on.  The caveat to this is if
+you've been grabbing test releases from any of the authors directly then 
+you'll need to *gem uninstall* first to make sure you don't have any buggy
+stuff lying around.
+
+
+h1. Help For Commands
+
+Mongrel uses a fairly comprehensive command/plugin system (documented in the near
+future) that has built-in help thanks to optparse.  Just pass a -h to any 
+command and it will dump the help for you:
+
+ $ mongrel_rails start -h 
+ Usage: start [options]
+    -e, --environment ENV            Rails environment to run as
+    -d, --daemonize                  Whether to run in the background or not
+    -p, --port PORT                  Which port to bind to
+    -a, --address ADDR               Address to bind to
+    -l, --log FILE                   Where to write log messages
+    -P, --pid FILE                   Where to write the PID
+    -n, --num-procs INT              Number of processor threads to use
+    -t, --timeout SECONDS            Timeout all requests after SECONDS time
+    -m, --mime PATH                  A YAML file that lists additional MIME types
+    -c, --chdir PATH                 Change to dir before starting (will be expanded)
+    -r, --root PATH                  Set the document root (default 'public')
+    -h, --help                       Show this message
+        --version                    Show version
+
+Also every option has reasonable default options, and will complain if you give 
+anything invalid.
+
+
+h1. Running In Development
+
+Mongrel turns out to be really nice for development since it serves files
+much faster than WEBrick.  I'm using it for almost all my development Ruby
+on Rails work these days.  What I do is the following:
+
+ $ mongrel_rails start
+
+And then do my work like normal with WEBrick.  You don't get all the logging
+and stuff you get with WEBrick (planned for a future release) but otherwise
+it's nice and snappy.
+
+
+h1. More Information
+
+There's a "mailing list":http://rubyforge.org/mailman/listinfo/mongrel-users that
+you should subscribe to if you're looking for help or are interested in tracking
+Mongrel.  We post announcements of pre-release gems you can play with to this
+mailing list and also discuss development of Mongrel there.
+
+Before you start asking for features you should read about 
+"bikeshedding":http://www.catb.org/jargon/html/B/bikeshedding.html and 
+understand that we're really nice, but sometimes code speaks better than rhetoric.
+
+Finally there's lots of other "documentation.":index.html

doc/site/src/docs/win32.page

@@ -0,0 +1,93 @@
+---
+title: Win32 HOWTO
+inMenu: true
+directoryName: Documentation
+---
+
+h1. Mongrel Win32 HOWTO
+
+Mongrel now supports Win32 much better than previous releases thanks to 
+some "great people":../attributions.html and their hard work.  You can
+now run Mongrel with Ruby on Rails as a windows service, ang there are
+pre-compiled gems available for people to use.
+
+*Before reading this document you need to read "Getting Started.":started.html and make sure it works.*
+
+h2. Stopping The mongrel_rails Script
+
+When you run the mongrel_rails script from the command line you'll have to use CTRL-Pause/Break
+to get it to exit rather than CTRL-C.
+
+
+h2. Running The Service
+
+After you do the gem install, find a Rails application you want to run
+and do:
+
+ $ mongrel_rails_service install -n myapp \ 
+     -r c:\my\path\to\myapp -p 4000 -e production
+ $ mongrel_rails_service start -n myapp
+
+Now hit the port and poof, works (or should).
+
+*Stopping the service is a little problematic right now.*  We're working on graceful
+shutdown, so be patient.  The application will stop if you use:
+
+ $ mongrel_rails_service stop -n myapp
+
+But will complain about an error during shutdown.  If you try to stop using the
+Services control panel then it will seem to hang.  Just wait a little while then
+hit stop once the service actually stop.
+
+
+h2. Development Work
+
+I recommend that you keep the service runner for doing a production run setup, 
+and then use a regular console with the plain Mongrel runner until we get
+service stop working right.
+
+Also, if you run into an app that's not running right, my suggestion is to run it with
+the regular mongrel_rails runner:
+
+ $ cd c:\my\path\to\myapp
+ $ mongrel_rails start -p 4500
+
+Since that will spit out error messages and stuff to the console.  *Use CTRL-Pause/Break to stop.*
+
+
+h2. Other Service Commands
+
+There is a full set of service control commands in the mongrel_rails_service script.
+This lets you use either the Services control panel or a command line script to 
+manage your Rails applications.  What's also nice is that you can register as many
+applications as you want, and even the same one with different names.
+
+
+h3. install
+
+If you want to run the same app in different modes then use the *-n* option to the *install*
+command:
+
+ $ mongrel_rails_service install -n myapp_dev \ 
+     -r c:\my\path\to\myapp -p 4000 -e development
+ $ mongrel_rails_service start -n myapp
+
+You can also use the *-d* option to give the service a different display name in the
+Services console.
+
+h3. start
+
+Pretty much just takes a service name to start up.  It will run and print a message
+until the service finally starts, which sometimes can take 10-60 seconds.
+
+h3. stop
+
+Sort of works right now and also only takes a -n parameter.  It has a few errors
+when it tries to stop a service so we're working on making it cleaner.
+
+h3. delete
+
+Takes the name (-n) of the service to delete and then removes it from the list.
+*This would be how you'd remove a service so you can change it's start-up options.*
+
+

doc/site/src/index.page

@@ -2,7 +2,6 @@
 title: Home
 inMenu: false
 directoryName: Home
-odering: 1
 ---
 h1. What is Mongrel?
 
@@ -29,12 +28,29 @@ And you're all set.  There's quite a few options you can set for the
 start command.  Use the *mongrel_rails start -h* to see them all.
 
 
-h3. Win32 Folks
+h3. Win32 Support
 
-The only thing you people need to do right now is avoid the -d
+Mongrel now has support for running as a Win32 service right out of the
-option to start.  Win32 doesn't support POSIX fork so it won't
+box.  The support is still rough but works well enough that we decided
-go into the background.  I'll be adding support for making
+to release it.  You can thank Luis Lavena for working on this and making
-Mongrel a service in a few releases.
+it so nice.
+
+After you do the gem install, find a Rails application you want to run
+and do:
+
+ $ mongrel_rails_service install -n myapp \ 
+     -r c:\my\path\to\myapp -p 4000 -e production
+ $ mongrel_rails_service start -n myapp
+
+Now hit the port and poof, works.  *Stopping the service is a little problematic right now.*
+
+If you run into an app that's not running right, my suggestion is to run it with
+the regular mongrel_rails runner:
+
+ $ cd c:\my\path\to\myapp
+ $ mongrel_rails start -p 4500
+
+Since that will spit out error messages and stuff to the console.  *Use CTRL-Pause/Break to stop.*
 
 
 h2. Performance
@@ -59,3 +75,14 @@ API and dig into the source.  Since Mongrel is currently being used by
 other frameworks it's documentation is aimed at developers.  Real manuals
 will be written when there's something for "regular" folks to use.
 
+
+h2. Mailing Lists
+
+There's a "mailing list":http://rubyforge.org/mailman/listinfo/mongrel-users that
+you should subscribe to if you're looking for help or are interested in tracking
+Mongrel.  We post announcements of pre-release gems you can play with to this
+mailing list and also discuss development of Mongrel there.
+
+Before you start asking for features you should read about 
+"bikeshedding":http://www.catb.org/jargon/html/B/bikeshedding.html and 
+understand that we're really nice, but sometimes code speaks better than rhetoric.

doc/site/src/news.page

@@ -7,6 +7,17 @@ ordering: 2
 
 h1. Latest News
 
+h2.  Feb-22:  Mongrel 0.3.6 -- Win32 Services Galore
+
+Thanks to Luis Lavena we have an almost complete win32 service
+runner and management script that lets you setup services in windows for
+all the different rails apps you have.  This means you can control the
+services from the command line or from the Services console.
+"Check the Win32 HOWTO":docs/win32.html for more information on using it.
+It still has some problems with stopping, but otherwise it's great.
+
+"Download 0.3.6":http://rubyforge.org/frs/?group_id=1306
+
 h2.  Feb-18: Mongrel 0.3.5 -- CGI Actually Works
 
 The CGIWrapper code I had written was complete and utter crap, so 
@@ -16,7 +27,7 @@ and read_multipart functions as the next place to put my efforts.  These
 three functions are so full of hand coded parsing that rewriting them with
 a Ragel processor would be a huge gain.
 
-"Download 0.3.3":http://rubyforge.org/frs/?group_id=1306
+"Download 0.3.5":http://rubyforge.org/frs/?group_id=1306
 
 h2.  Feb-16: Mongrel 0.3.4 -- Win32 Pre-built Gems
 
@@ -35,7 +46,7 @@ give mongrel_rails a command.  It now lists the commands.
 There is a small warning message I threw in that I want people to report if they
 see.  You'll know it if you see it in the log/mongrel.log file or on the console.
 
-"Download 0.3.3":http://rubyforge.org/frs/?group_id=1306
+"Download 0.3.4":http://rubyforge.org/frs/?group_id=1306
 
 
 h2.  Feb-14: Mongrel 0.3.3 Released