Update docs

Author: ethanhann

docs-src/commands.md

@@ -44,7 +44,8 @@ namespace MyCommandPlugin
 }
 ```
 
-Extending the **InEngine.Core.AbstractCommand** class adds extra functionality, like a logger, a progress bar, and the ability to schedule the command using the scheduler.
+A command that implements ICommand can be run directly or [queued](queuing), but it cannot be [scheduled](scheduling).
+Extending the **InEngine.Core.AbstractCommand** class adds extra functionality, like a progress bar, and the ability to schedule the command using the scheduler.
 Minimally, the Run method should be overridden.
 
 ```c#
@@ -63,12 +64,12 @@ namespace MyCommandPlugin
 }
 ```
 
-
 ## Run a Command
 
 Create a class that implements **InEngine.Core.IOptions** in the same assembly as the command class.
-Add a VerbOptions attribute from the CommandLine namespace that defines the name of the command and optional help text.
-The help text can be auto-generated from the attribute or manually specified in the GetUsage method.  
+Add a VerbOptions attribute, from the CommandLine namespace, that defines the name of the command. 
+Optional help text can also be specified in the VerbOption attribute.
+The help text can be auto-generated from the attribute or manually specified in the GetUsage method if desired.
 
 ```c#
 using CommandLine;
@@ -93,20 +94,20 @@ namespace MyCommandPlugin
 
 Download the InEngine binary distribution, from the [GitHub Releases](https://github.com/InEngine-NET/InEngine.NET/releases) page, that matches the version of the InEngine.Core package you included.
 
-Copy your project's DLLs into the same directory as inengine.exe.
+Copy your project's DLLs into the Plugins subdirectory included in the binary distribution. 
+Add your plugin to the ["Plugins" list in appsettings.config](configuration) at the root of the binary distribution.
 
-Run your command...
+Run your command:
 
 ```bash
 inengine.exe -pMyCommandPlugin my-command
 ```
 
-## Discover Command Plugins
+## View Available Plugins
 
-Run inengine.exe without any arguments to see a list of plugins.
+Run inengine.exe without any arguments to see a list of plugins:
 
 ```text
-
   ___       _____             _              _   _ _____ _____ 
  |_ _|_ __ | ____|_ __   __ _(_)_ __   ___  | \ | | ____|_   _|
   | || '_ \|  _| | '_ \ / _` | | '_ \ / _ \ |  \| |  _|   | |  
@@ -115,116 +116,138 @@ Run inengine.exe without any arguments to see a list of plugins.
                         |___/ 
 
 Usage:
-  -p[<plugin_name>] [<command_name>]
+InEngine 3.x
+Copyright © 2017 Ethan Hann
+
+  p, plugin           Plug-In to activate.
+
+  s, scheduler        Run the scheduler.
+
+  c, configuration    (Default: ./appsettings.json) The path to the 
+                      configuration file.
+
 
 Plugins:
-  InEngine.Commands
   InEngine.Core
-
 ```
 
-## Discover Commands in a Plugin
+## View Commands in a Plugin
 
-Run inengine.exe with only the plugin specified.
+Run inengine.exe with only the plugin specified:
 
 ```bash
 inengine.exe -pInEngine.Core
 ```
 
-The **InEngine.Core** library is itself a plugin that contains queue related commands. 
+The **InEngine.Core** library is itself a plugin that contains queue-related and other commands. 
 As an example, this is the help output for the core plugin.
 
 ```text
-
   ___       _____             _              _   _ _____ _____ 
  |_ _|_ __ | ____|_ __   __ _(_)_ __   ___  | \ | | ____|_   _|
   | || '_ \|  _| | '_ \ / _` | | '_ \ / _ \ |  \| |  _|   | |  
   | || | | | |___| | | | (_| | | | | |  __/_| |\  | |___  | |  
  |___|_| |_|_____|_| |_|\__, |_|_| |_|\___(_|_| \_|_____| |_|  
                         |___/ 
 
-Plugin: InEngine.Core
+Plugin: 
+  Name:    InEngine.Core
+  Version: 3.x
+
 
 Commands:
-  null	A null operation command. Literally does nothing.
-  echo	Echo some text to the console. Useful for end-to-end testing.
-  queue:publish	Publish a command message to a queue.
-  queue:consume	Consume one or more command messages from the queue.
-  queue:length	Get the number of messages in the primary and secondary queues.
-  queue:clear	Clear the primary and secondary queues.
+  queue:publish     Publish a command message to a queue.
+  queue:consume     Consume one or more command messages from the queue.
+  queue:length      Get the number of messages in the primary and secondary queues.
+  queue:flush       Clear the primary or secondary queues.
+  queue:republish   Republish failed messages to the queue.
+  queue:peek        Peek at messages in the primary or secondary queues.
+  echo              Echo some text to the console. Useful for end-to-end testing.
+  proc              Launch an arbitrary process.
 ```
 
 ## Print Help Text for a Plugin's Commands
 
 Run the command with the -h or --help arguments.
 
 ```bash
-inengine.exe -pInEngine.Core queue:clear -h
+inengine.exe -pInEngine.Core queue:publish -h
 ```
 
 The **InEngine.Core** plugin's command to clear the InEngine.NET queues produces this help message. 
 
 ```text
 InEngine 3.x
-Copyright © Ethan Hann 2017
+Copyright © 2017 Ethan Hann
 
-  --processing-queue    Clear the processing queue.
+  --command-plugin    Required. The name of a command plugin file, e.g. 
+                      InEngine.Core.dll
 
-  --secondary           Clear the secondary queue.
-```
+  --command-verb      A plugin command verb, e.g. echo
 
-## Writing Output
+  --command-class     A command class name, e.g. 
+                      InEngine.Core.Commands.AlwaysSucceed. Takes precedence 
+                      over --command-verb if both are specified.
 
-The **InEngine.Core.AbstractCommand** class provides some helper functions to output text to the console: 
+  --args              An optional list of arguments to publish with the 
+                      command.
 
-```c#
-IWrite Newline();
-IWrite Info(string val);
-IWrite Warning(string val);
-IWrite Error(string val);
-IWrite Line(string val);
+  --secondary         (Default: False) Publish the command to the secondary 
+                      queue.
 ```
 
+## Writing Output
+
+The **InEngine.Core.AbstractCommand** class provides some helper functions to output text to the console, for example:
+
 ```c#
 public override void Run()
 {
-    Info("Display some information");
+    Line("Display some information");
 }
 ```
 
-Display an error message, use the Error method.
+All of these commands append a newline to the end of the specified text:
 
 ```c#
-Error("Display some information");
+Line("This is some text");                  // Text color is white
+Info("Something good happened");            // Text color is green
+Warning("Something not so good happened");  // Text color is yellow
+Error("Something bad happened");            // Text color is red
 ```
 
-Display a warning message, use the Warning method.
+These commands are similar, but they do not append a newline:
 
 ```c#
-Error("Display some information");
+Text("This is some text");                      // Text color is white
+InfoText("Something good happened");            // Text color is green
+WarningText("Something not so good happened");  // Text color is yellow
+ErrorText("Something bad happened");            // Text color is red
 ```
 
-Info, Error, and Warning messages are display in green, red, and yellow, respectively.
-If you want to display an uncolored line, use the Line method. 
-Line("This is a plain line.");
-
-## Logging
+You can also display newlines:
+ 
+```c#
+Newline();      // 1 newline
+Newline(5);     // 5 newlines
+Newline(10);    // 10 newlines
+```
 
-The **InEngine.Core.AbstractCommand** class provides a Logger property. It implements the **NLog.ILogger** interface.
+The methods can be chained together:
 
 ```c#
-public override void Run()
-{
-    Logger.Trace("Sample trace message");
-    Logger.Debug("Sample debug message");
-    Logger.Info("Sample informational message");
-    Logger.Warn("Sample warning message");
-    Logger.Error("Sample error message");
-    Logger.Fatal("Sample fatal error message");
-}
+InfoText("You have this many things: ")
+    .Line("23")
+    .NewLine(2)
+    .InfoText("You have this many other things: ")
+    .Line("34")
+    .NewLine(2); 
 ```
 
-Setup an [NLog configuration](https://github.com/NLog/NLog/wiki/Tutorial#configuration) file, something like this...
+## Logging
+
+Any exceptions thrown by a command will be logged with NLog provided NLog is configured. 
+The [NLog configuration](https://github.com/NLog/NLog/wiki/Tutorial#configuration) file needs to be setup with something like this: 
 
 ```xml
 <?xml version="1.0" encoding="utf-8" ?>
@@ -245,7 +268,8 @@ Setup an [NLog configuration](https://github.com/NLog/NLog/wiki/Tutorial#configu
 
 ## Progress Bar
 
-The **InEngine.Core.AbstractCommand** class provides a ProgressBar property. This is how it is used.
+The **InEngine.Core.AbstractCommand** class provides a ProgressBar property to show command progress in a terminal.
+This is how it is used:
 
 ```c#
 public override void Run()

docs-src/configuration.md

@@ -6,7 +6,11 @@ Configuration is accomplished by modifying the appsettings.json file that comes
 ```json
 {
   "InEngine": {
+    "Plugins": [
+      "path/to/MyCommandPlugin"
+    ],
     "Queue": {
+      "UseCompression": false,
       "PrimaryQueueConsumers":  16,
       "SecondaryQueueConsumers": 4,
       "QueueName": "InEngine:Queue",
@@ -20,15 +24,23 @@ Configuration is accomplished by modifying the appsettings.json file that comes
 
 ```
 
-| Setting                   | Description               |
-| ------------------------- | ------------------------- |
-| PrimaryQueueConsumers     | The number of consumers to schedule for the primary queue.        |
-| SecondaryQueueConsumers   | The number of consumers to schedule for the secondary queue.      |
-| QueueName                 | The base name of the queue, used to form the Redis Queue keys.    |
-| RedisHost                 | The Redis hostname to connect to.                                 |
-| RedisPort                 | Redis's port.                                                     |
-| RedisDb                   | The Redis database - 0-15                                         |
-| RedisPassword             | The Redis auth password                                           |
 
+## Top-level Settings
 
+| Setting                   | Type              | Description                                                                       |
+| ------------------------- | ----------------- | --------------------------------------------------------------------------------- |
+| Plugins                   | array of strings  | A list of paths of plugin assemblies, with ".dll" omitted from the assembly name. |
 
+
+## Queue Settings
+
+| Setting                   | Type      | Description                                                           |
+| ------------------------- | --------- | --------------------------------------------------------------------- |
+| UseCompression            | bool      | A situation performance optimization that compresses queued messages. |
+| PrimaryQueueConsumers     | string    | The number of consumers to schedule for the secondary queue.          |
+| SecondaryQueueConsumers   | string    | The number of consumers to schedule for the secondary queue.          |
+| QueueName                 | string    | The base name of the queue, used to form the Redis Queue keys.        |
+| RedisHost                 | string    | The Redis hostname to connect to.                                     |
+| RedisPort                 | integer   | Redis's port.                                                         |
+| RedisDb                   | integer   | The Redis database - 0-15                                             |
+| RedisPassword             | string    | The Redis auth password                                               |

docs-src/queuing.md

@@ -25,7 +25,7 @@ It is highly recommended to <a href="https://redis.io/topics/security#authentica
 
 #### Programmatically
 
-[Commands](commands) can be published programmatically with the **InEngine.Core.Queue.Broker** class:
+[Commands](commands) can be published programmatically with the **InEngine.Core.Queuing.Broker** class:
 
 ```c#
 Broker.Make().Publish(new MyCommand());
@@ -37,13 +37,19 @@ Note that all queue commands reside in the **InEngine.Core** plugin.
 This is an example of how to publish a command from the CLI by specifying the commands assembly, class name, and arguments:
 
 ```bash
-inengine.exe -pInEngine.Core queue:publish --command-assembly=MyCommandPlugin.dll --command-class=MyCommand --args "text=bar"
+inengine.exe -pInEngine.Core queue:publish --command-plugin=MyCommandPlugin.dll --command-class=MyCommand --args "text=bar"
 ```
 
 There is an "Echo" command in the *InEngine.Core* package. It is useful for end-to-end testing with the queue feature.
 
 ```bash
-inengine.exe -pInEngine.Core queue:publish --command-assembly=InEngine.Core.dll --command-class=InEngine.Core.Commands.Echo --args "text=foo"
+inengine.exe -pInEngine.Core queue:publish --command-plugin=InEngine.Core.dll --command-class=InEngine.Core.Commands.Echo --args "text=foo"
+```
+
+The command verb can also be specified instead of the full class name:
+ 
+```bash
+inengine.exe -pInEngine.Core queue:publish --command-plugin=InEngine.Core.dll --command-verb=echo--args "text=foo"
 ```
 
 ### Consuming Commands
@@ -55,11 +61,11 @@ Consuming a command is also accomplished with the Broker class:
 Broker.Make().Consume();
 ```
 
-Both methods take an optional second argument to indicate if the secondary queue should be used instead of the primary queue.
+The make method takes an optional second argument to indicate if the secondary queue should be used instead of the primary queue.
 
 ```c#
 // Uses secondary queue.
-Broker.Make().Consume(true);
+Broker.Make(true).Consume();
 ```
 
 Commands can be consumed from the command line as well with this simple command:
@@ -70,7 +76,7 @@ Commands can be consumed from the command line as well with this simple command:
 inengine.exe -pInEngine.Core queue:consume
 ```
 
-Use the **--secondary** switch to consume the secondary queue instead of the primary queue:
+Use the **--secondary** argument to consume the secondary queue instead of the primary queue:
 
 ```bash
 inengine.exe -pInEngine.Core queue:consume --secondary
@@ -84,21 +90,25 @@ There are a variety of [ways to run the scheduler](scheduling/#running-the-sched
 
 ## Primary and Secondary Queue
 
-Other than the fact that the primary queue is used by default, there is difference between the primary and secondary queues. 
+Other than the fact that the primary queue is used by default, there is no difference between the primary and secondary queues. 
 However, it is often desirable to have more than 1 queue. 
 For example, long running jobs might be sent to the secondary queue, 
 while jobs that are expected to finish after only a few moments are sent to the primary queue.
 
-What about 3, 4, or 900 queues? Numerous queues gets to be a pain to manage and, practically speaking, is probably unnecessary.
+What about 3, 4, or 900 queues? Managing numerous queues gets to be a pain and, practically speaking, is probably unnecessary.
 If it is desirable, different [configuration files](configuration) can be used to run multiple instances of InEngine.NET.
-Simply create a new config file with a new QueueName setting and point inengine.exe at it.
+Simply create a new [config file](configuration) with a new QueueName setting and point inengine.exe at it with the -c argument:
+
+```bash
+inengine.exe -cMyCustomSettingsFile.json -pInEngine.Core queue:consume
+```
 
 ## Message Compression
 
 Messages can be compressed when saved in the queue. 
 It is important to understand the trade-offs of this feature before enabling it.
-Compressing messages takes more CPU resources and might negatively impact queueing throughput if the queued commands do not have a lot of internal state.
-Put simply, if the commands are too small to benefit from being compressed, then compressing them wastes resources.
+If the queued commands are too small to benefit from being compressed, then compressing them wastes resources.
+Compressing messages takes more CPU resources and might negatively impact queue throughput if the queued commands do not have a lot of internal state.
 
 If the commands have a lot of internal state, then this feature will reduce the queue's memory consumption.
 Also, in a high-throughput scenario, where network bandwidth is limited, this feature can greatly reduce the amount of bandwidth used.