Add script plugin development info

docs/en/10-plugins/01-chapter11.md

@@ -106,30 +106,58 @@ RunDeck uses a few built-in providers to provide the default service:
 
 For NodeExecutor, these providers:
 
-`local`: local execution of a command 
-`jsch-ssh`: remote execution of a command via SSH, requiring the "hostname", and "username" attributes on a node.
+`local`
+
+:   local execution of a command 
+
+`jsch-ssh`
+
+:   remote execution of a command via SSH, requiring the "hostname", and "username" attributes on a node.
 
 For FileCopier, these providers:
 
-`local`: creates a local temp file for a script
-`jsch-scp`: remote copy of a command via SCP, requiring the "hostname" and 
-   "username" attributes on a node.
+`local`
+
+:   creates a local temp file for a script
+
+`jsch-scp`
+
+:   remote copy of a command via SCP, requiring the "hostname" and  "username" attributes on a node.
 
 Plugin Development
 =============
 
 This is a work in progress, and the plugin system is likely to change.
 
-Plugins are currently developed as Java code that is distributed within a Jar 
-file and placed in the RunDeck server's classpath before it starts up.
+There are currently two ways to develop plugins:
+
+1. Develop Java code that is distributed within a Jar 
+file.  See [Java plugin development](#java-plugin-development).
+2. Write shell/system scripts that implement your desired behavior and put them
+in a zip file with some metadata.   See [Script Plugin Development](#script-plugin-development).
+
+In both manners, the resultant plugin archive file, either a .jar java archive, 
+or a .zip file archive will be placed in the `$RDECK_BASE/libext` dir.
+
+
+Java Plugin Development
+--------
+
+Java plugins are distributed as .jar files containing the necessary classes to
+provide one or more services.
+
+The `.jar` file you distribute must have this metdata within the Manifest for
+the jar file to be correctly loaded by the system:
+
+* `Rundeck-Plugin-Archive: true`
+* `Rundeck-Plugin-Classnames: classname,..`
 
-A "Plugin Provider Class" is a java class that implements a particular interface and is
-registered as a "Provider" for a particular RunDeck "Service".  
+Each classname listed must be a valid "Provider Class" as defined below.
 
-Available Service Names:
+### Provider Classes
 
-* `NodeExecutor` - interface to implement: `com.dtolabs.rundeck.core.execution.service.NodeExecutor`
-* `FileCopier` - interface to implement: `com.dtolabs.rundeck.core.execution.service.FileCopier`
+A "Provider Class" is a java class that implements a particular interface and declares
+itself as a provider for a particular RunDeck "Service".  
 
 Each plugin also defines a "Name" that identifies it for use in RunDeck.  The Name
 of a plugin is also referred to as a "Provider Name", as the plugin class is a
@@ -156,26 +184,31 @@ You may log messages to the ExecutionListener available via
 You can also send output to `System.err` and `System.out` and it will be 
 captured as output of the execution.
 
-Node Executor Plugins
---------
+### Available Services:
+
+* `NodeExecutor` - executes a command on a node
+* `FileCopier` - copies a file to a node
+
+### Node Executor Providers
 
 A Node Executor provider executes a certain command on a remote or 
 local node.
 
-Your provider class must implement the `NodeExecutor` interface:
+Your provider class must implement the `com.dtolabs.rundeck.core.execution.service.NodeExecutor` interface:
 
     public interface NodeExecutor {
         public NodeExecutorResult executeCommand(ExecutionContext context, 
             String[] command, INodeEntry node) throws ExecutionException;
     }
 
-File Copier Plugins
----------
+More information is available in the Javadoc.
+
+### File Copier Providers
 
 A File Copier provider copies a file or script to a remote
 or local node.
 
-Your provider class must implement the FileCopier interface:
+Your provider class must implement the `com.dtolabs.rundeck.core.execution.service.FileCopier` interface:
 
     public interface FileCopier {
         public String copyFileStream(final ExecutionContext context, InputStream input, INodeEntry node) throws
@@ -187,20 +220,86 @@ Your provider class must implement the FileCopier interface:
             FileCopierException;
     }
 
+More information is available in the Javadoc.
+
+Script Plugin Development
+-----------
+
+Script plugins can provide the same services as Java plugins, but they do so
+with a script that is invoked in an external system processes by the JVM. 
+
+You must create a zip file with the following structure:
+
+
+    [something]-plugin.zip -- container (root)
+    |- plugin.yaml -- plugin metadata file
+    \- contents/  -- plugin contents directory
+       \- script/resource files...
+
+The filename of the plugin zip must end with "-plugin.zip" to be recognized as a
+plugin archive. (NB: to support a common confusion with zip files, if the zip 
+contains a top-level directory with the same base name as the zip file (sans ".zip") 
+then that directory is considered the root.)
+
+The file `plugin.yaml` must have this structure:
+
+    # yaml plugin metadata
+
+    name: plugin name
+    author: author name
+    version: version info
+    date: release data
+    providers:
+        - name: [provider name]
+          service: [service name]
+          plugin-type: script
+          script-file: [script file name]
+          script-args: [script file args]
+
+This provides the necessary metadata about the plugin, including one or more 
+entries in the `providers` list to declare those providers defined in the plugin.
+
+Each provider must have a name unique for the service it provides.
+
+Each provider must declare one of these valid services:
+
+* `NodeExecutor`
+* `FileCopier`
+
+The `script-file` must be the name of a file relative to the `contents` directory.
+
+`script-args` is the arguments to use when invoking the script file. This can
+contain data-context properties such as `${node.name}`.  Additionally, the
+specific Service will provide some additional context properties that can be used:
+
+* `NodeExecutor` will define "${exec.command}" containing the command to be executed
+* `FileCopier` will define "${file-copy.file}" containing the local path to the file
+that needs to be copied.
+
+### Service requirements
+
+The specific service has expectations about
+the way your provider script behaves:
+
+* Exit code of 0 indicates success
+* Any other exit code indiates failure
+
+For `NodeExecutor`
+
+:   All output to `STDOUT`/`STDERR` will be captured for the job's output
+
+For `FileCopier`
+
+:   The first line of output of `STDOUT` MUST be the filepath of the file copied 
+    to the target node.  Other output is ignored. All output to `STDERR` will be
+    captured for the job's output.
 
 Architecture
 ------
 
 Installing Java Plugins
 
-Copy the `plugin.jar` to the RunDeck server's
-webapp lib dir:
+Copy the `plugin.jar` to the RunDeck server's libext dir:
 
     cp plugin.jar \
-        $RDECK_BASE/server/exp/webapp/WEB-INF/lib
-
-2: Modify the framework.properties file, to enable the plugin
-
-Add this line:
-
-    framework.plugins.[ServiceName].classnames=[classname]
+        $RDECK_BASE/libext