updating

README.markdown

@@ -29,6 +29,8 @@ You'll rename `winsw.exe` into something like `jenkins.exe`, then you put this X
 
 ... and you can use the exit code from these processes to determine whether the operation was successful. There are other commands to perform other operations, like `uninstall`, `start`, `stop`, and so on.
 
+Once the service is installed, you can start it from Windows service manager. Windows will start `jenkins.exe`, then `jenkins.exe` will launch the executable specified in the configuration file (Java in this case.) If this process dies, winsw will exit itself, and the service will be considered stopped.
+
 Available commands
 ------------------
 Your renamed `winsw.exe` accepts the following commands:
@@ -49,10 +51,88 @@ When winsw is running as a service, more detailed error information is reported
 
 Deferred file operations
 ------------------------
-To support self updating services, winsw offers a mechanism to perform file operations before a service starts up. This is often necessary because Windows prevents files from overwritten while it's in use.
+To support self updating services, winsw offers a mechanism to perform file operations before the process you specified in the configuration file gets launched. This is often necessary because Windows prevents files from overwritten while it's in use.
 
 To perform file operations, write a text file (in the UTF-8 encoding) at `myapp.copies` (that is, it's in the same directory as `myapp.xml` and `myapp.exe` but with a different file extension), and for each operation add one line:
 
-* To move a file, write "src>dst". If the 'dst' file already exists it will be overwritten.
+* To move a file, write a line `src>dst`. If the `dst` file already exists it will be overwritten.
 
 The success or failure of these operations will be recorded in the event log.
+
+The `<download>` element in the configuration file also provides an useful building block for a self updating services.
+
+
+Configuration file syntax
+-------------------------
+The behaviour of the service is controlled by the XML configuration file. The root element of this XML file must be `<service>`, and it supports the following child element.
+
+### id
+Specifies the ID that Windows uses internally to identify the service. This has to be unique among all the services installed in a system, and (while I haven't verified this) this must consist entirely out of alpha-numeric characters.
+
+### name
+Short display name of the service, which can contain spaces and other characters. This shouldn't be too long, like `<id>`, and this also needs to be unique among all the services in a given system.
+
+### description
+Long human-readable description of the service. This gets displayed in Windows service manager when the service is selected.
+
+### executable
+This element specifies the executable to be launched. It can be either absolute path, or you can just specify the executable name and let it be searched from `PATH` (although note that the services often run in a different user account and therefore it might have different `PATH` than your shell does.)
+
+### depend
+Specify IDs of other services that this service depends on. When service X depends on service Y, X can only run if Y is running.
+
+Multiple elements can be used to specify multiple dependencies.
+
+    <depend>Eventlog</depend>
+    <depend>W32Time</depend>
+
+### logging
+
+Optionally set a different logging directory with <logpath> and startup <logmode>: reset (clear log), roll (move to \*.old) or append (default).
+
+### argument
+This element specifies the arguments to be passed to the executable. Winsw will quote each argument if necessary, so do not put quotes in `<argument>` to avoid double quotation.
+
+    <argument>arg1</argument>
+    <argument>arg2</argument>
+    <argument>arg3</argument>
+
+For backward compatibility, `<arguments>` element can be used instead to specify the whole command line in a single element.
+
+## stopargument/stopexecutable
+When the service is requested to stop, winsw simply calls <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/ms686714(v=vs.85).aspx">TerminateProcess</a> API to kill the service instantly. However, if `<stopargument>` elements are present, winsw will instead launch another process of `<executable>` (or `<stopexecutable>` if that's specified) with the `<stopargument>` arguments, and expects that to initiate the graceful shutdown of the service process.
+
+Winsw will then wait for the two processes to exit on its own, before reporting back to Windows that the service has terminated.
+
+When you use the `<stopargument>`, you must use `<startargument>` instead of `<argument>`. See the complete example below:
+
+    <executable>catalina.sh</executable>
+    <startargument>run</startargument>
+    
+    <stopexecutable>catalina.sh</stopexecutable>
+    <stopargument>stop</stopargument>
+
+### env
+This optional element can be specified multiple times if necessary to specify environment variables to be set for the child process. The syntax is:
+
+    <env name="HOME" value="c:\abc" />
+
+### interactive
+If this optional element is specified, the service will be allowed to interact with the desktop, such as by showing a new window and dialog boxes. If your program requires GUI, set this like the following:
+
+    <interactive />
+
+Note that since the introduction UAC (Windows Vista and onward), services are no longer really allowed to interact with the desktop. In those OSes, all that this does is to allow the user to switch to a separate window station to interact with the service.
+
+### beeponshutdown
+This optional element is to emit [simple tone](http://msdn.microsoft.com/en-us/library/ms679277%28VS.85%29.aspx) when the service shuts down. This feature should be used only for debugging, as some operating systems and hardware do not support this functionality.
+
+### download
+This optional element can be specified multiple times to have the service wrapper retrieve resources from URL and place it locally as a file. This operation runs when the service is started, before the application specified by `<executable>` is launched.
+
+    <download from="http://example.com/some.dat" to="%BASE%\some.dat"/>
+
+This is another useful building block for developing a self-updating service.
+
+
+

ServiceDescriptor.cs

@@ -328,6 +328,7 @@ namespace winsw
 
         /// <summary>
         /// True if the service should when finished on shutdown.
+        /// This doesn't work on some OSes. See http://msdn.microsoft.com/en-us/library/ms679277%28VS.85%29.aspx
         /// </summary>
         public bool BeepOnShutdown
         {