Prepared documentation for publication

- Merges #14, which converts HTML tables to GFM, closes #10
- Reviews (and removes or modifies!) all headers; fixes #7
- Reviews and fixes all blockquotes; fixes #11
- Reviews and fixes all code blocks (TONS of improperly formatted or improperly
  tagged languages!); fixes #8
- Thorough review of documentation structure and narrative; re-orders the
  documentation to split into zend-console vs integration with zend-mvc, and
  adds language around the `DefaultRouteMatcher` implementation to focus on
  standalone usage; fixes #9

Additionally, converts from bookdown to mkdocs.

.gitignore

@@ -6,7 +6,9 @@
 .*.sw*
 .*.un~
 nbproject
+doc/html/
 tmp/
+zf-mkdoc-theme/
 
 clover.xml
 composer.lock

doc/book/adapter.md

@@ -0,0 +1,160 @@
+# Console adapters
+
+zend-console's console abstraction layer works around various bugs and limitations
+in operating systems, including:
+
+- display of colorized text.
+- discovery and calculation of console window size.
+- discovery of console charset.
+- basic line drawing capabilities.
+
+Console adapters implement `Zend\Console\Adapter\AdapterInterface`, and you
+should typehint against that interface for purposes of working with console
+capabilities. Adapters are included for:
+
+- Posix (\*nix-based systems)
+- Windows (and Windows ANSI; for use with `command.bat`)
+- Virtual (which provides Windows PowerShell compatibility)
+
+## Retrieving the console adapter
+
+While you may know your current environment, you will want to write your code in
+such a way that the console adapter is specific to whatever environment it is
+run within. As such, you likely should never instantiate an adapter directly.
+zend-console, and the zend-mvc integration, provide tools for retrieving an
+appropriate adapter for the current environment in a generic way.
+
+### Standalone
+
+zend-console provides a factory for creating and returning the console adapter
+specific to your environment:
+
+```php
+use Zend\Console\Console;
+use Zend\Console\Exception\ExceptionInterface as ConsoleException;
+
+try {
+    $console = Console::getInstance();
+} catch (ConsoleException $e) {
+    // Could not get console adapter; most likely we are not running inside a
+    // console window.
+}
+```
+
+This returns a `Zend\Console\Adapter\AdapterInterface` implementation suitable
+for your current environment.
+
+> #### Exceptions
+>
+> For practical and security reasons, `Console::getInstance()` will always throw
+> an exception if you attempt to get console instance in a non-console
+> environment (i.e. when running on a HTTP server). You can override this
+> behavior by manually instantiating one of the `Zend\Console\Adapter\*`
+> classes; you should do this only as a last resort, however!
+
+### zend-mvc
+
+If you are using MVC controllers you can obtain Console adapter instance using
+the `ServiceManager`.
+
+```php
+namespace Application;
+
+use Zend\Mvc\Controller\AbstractActionController;
+use Zend\Console\Adapter\AdapterInterface as Console;
+use Zend\Console\Exception\RuntimeException;
+
+class ConsoleController extends AbstractActionController
+{
+    public function testAction()
+    {
+        $console = $this->getServiceLocator()->get('console');
+        if (! $console instanceof Console) {
+            throw new RuntimeException('Cannot obtain console adapter. Are we running in a
+console?');
+        }
+    }
+}
+```
+
+If you extend `AbstractConsoleController`, you can use the `getConsole()` method
+instead:
+
+```php
+namespace Application;
+
+use Zend\Mvc\Controller\AbstractConsoleController;
+use Zend\Console\Exception\RuntimeException;
+
+class ConsoleController extends AbstractConsoleController
+{
+    public function testAction()
+    {
+        $console = $this->getConsole();
+    }
+}
+```
+
+> #### Use dependency injection
+>
+> We recommend using dependency injection. Instead of pulling the console
+> adapter from the service manager, inject it from within your controller's
+> factory. This is essentially what happens when extending
+> `AbstractConsoleController` already.
+
+## Using the console adapter
+
+`Zend\Console\Adapter\AdapterInterface` describes a rich set of capabilities.
+Below is a sampling.
+
+### Window size and title
+
+Method | Description
+------ | -----------
+`$console->getWidth()` | (int) Get real console window width in characters.
+`$console->getHeight()` | (int) Get real console window height in characters.
+`$console->getSize()` | (array) Returns `[$width, $height]` with current console window dimensions.
+`$console->getTitle()` | (string) Get console window title.
+
+> #### Multibyte sequences
+>
+> For UTF-8 enabled consoles, dimensions represent the number of multibyte
+> characters (real characters).
+
+> #### Virtual buffer sizes
+>
+> On consoles with virtual buffers (e.g. MS Windows Command Prompt), width and
+> height represent visible (real) size, without scrolling the window. For
+> example, if the window scrolling width is 120 chars, but its real, visible
+> width is 80 chars, `getWidth()` will return `80`.
+
+### Character set
+
+Method | Description
+------ | -----------
+`$console->isUtf8()` | (boolean) Is the console UTF-8 compatible (can it display unicode strings)?
+`$console->getCharset()` | (`Zend\Console\Charset\CharsetInterface`) This method will return an instance of one of the `Zend\Console\Charset\*` classes representing the readable charset present for line-drawing. It is automatically detected by the adapter.
+
+### Writing to the console
+
+Method | Description
+------ | -----------
+`$console->write(string $text, $color = null, $bgColor = null)` | Write `$text` to the console, optionally using foreground `$color` and background `$bgColor`.  Color values must be one of the `Zend\Console\ColorInterface` constants.
+`$console->writeLine(string $text, $color = null, $bgColor = null)` | Write a single line of `$text` to the console. This method will output an environment-specific newline character at the end of the text, moving the console cursor to next line.
+`$console->writeAt(string $text, int $x, int $y, $color = null, $bgColor = null)` | Write `$text` at the specified `$x` and `$y` coordinates of console window. The top left corner of the screen has coordinates of `$x = 1; $y = 1`. To retrieve the far-right and bottom coordinates, use the `getWidth()` and `getHeight()` methods.
+
+### Reading from the console
+
+Method | Description
+------ | -----------
+`$console->readChar(string $mask = null)` | (string) Read a single character from the console. Optional `(string) $mask` can be provided to force entering only a selected set of characters. For example, to read a single digit, we can use the following syntax: `$digit = $console->readChar('0123456789');`.
+`$console->readLine(int $maxLength = 2048)` | (string) Read a single line of input from console. Optional `(int) $maxLength` can be used to limit the length of data that will be read. The line will be returned **without trailing newline characters**.
+
+### Miscellaneous
+
+Method | Description
+------ | -----------
+`$console->hideCursor()` | Hide blinking cursor from the console.
+`$console->showCursor()` | Show blinking cursor in the console.
+`$console->clear()` | Clear the screen.
+`$console->clearLine()` | Clear the line that the cursor currently sits at.

doc/book/getopt/configuration.md

@@ -0,0 +1,165 @@
+# Configuring Zend\\Console\\Getopt
+
+## Adding Option Rules
+
+You can add more option rules in addition to those you specified in the
+`Zend\Console\Getopt` constructor via the `addRules()` method. The argument to
+`addRules()` is the same as the first argument to the class constructor: it is
+either a string in the format of the short syntax options specification, or else
+an associative array in the format of a long syntax options specification.  See
+[Declaring Getopt Rules](rules.md) for details on the syntax for specifying
+options.
+
+### Using addRules()
+
+```php
+$opts = new Zend\Console\Getopt('abp:');
+$opts->addRules([
+    'verbose|v' => 'Print verbose output',
+]);
+```
+
+The example above shows adding the `--verbose` option with an alias of `-v` to a set of options
+defined in the call to the constructor. Notice that you can mix short format options and long format
+options in the same instance of `Zend\Console\Getopt`.
+
+## Adding Help Messages
+
+In addition to specifying the help strings when declaring option rules in the
+long format, you can associate help strings with option rules using the
+`setHelp()` method. The argument to the `setHelp()` method is an associative
+array, in which the key is a flag, and the value is a corresponding help string.
+
+### Using setHelp()
+
+```php
+$opts = new Zend\Console\Getopt('abp:');
+$opts->setHelp([
+    'a' => 'apple option, with no parameter',
+    'b' => 'banana option, with required integer parameter',
+    'p' => 'pear option, with optional string parameter',
+]);
+```
+
+If you declared options with aliases, you can use any of the aliases as the key
+of the associative array.
+
+The `setHelp()` method is the only way to define help strings if you declared
+the options using the short syntax.
+
+## Adding Option Aliases
+
+You can declare aliases for options using the `setAliases()` method. The
+argument is an associative array, where keys are flag strings declared
+previously, and values are new aliases for the flags.  These aliases are
+merged with any existing aliases. In other words, aliases you declared earlier
+are still in effect.
+
+An alias may be declared only once. If you try to redefine an alias, a
+`Zend\Console\Getopt\Exception` is thrown.
+
+### Using setAliases()
+
+```php
+$opts = new Zend\Console\Getopt('abp:');
+$opts->setAliases([
+    'a' => 'apple',
+    'a' => 'apfel',
+    'p' => 'pear',
+]);
+```
+
+In the example above, after declaring these aliases, `-a`, `--apple` and
+`--apfel` are aliases for each other. Also `-p` and `--pear` are aliases for
+each other.
+
+The `setAliases()` method is the only way to define aliases if you declared the
+options using the short syntax.
+
+## Adding Argument Lists
+
+By default, `Zend\Console\Getopt` uses `$_SERVER['argv']` for the array of
+command-line arguments to parse. You can alternatively specify the array of
+arguments as the second constructor argument.  Finally, you can append more
+arguments to those already used using the `addArguments()` method, or you can
+replace the current array of arguments using the `setArguments()` method. In
+both cases, the parameter to these methods is a simple array of strings. The
+former method appends the array to the current arguments, and the latter method
+substitutes the array for the current arguments.
+
+### Using addArguments() and setArguments()
+
+```php
+// By default, the constructor uses $_SERVER['argv']
+$opts = new Zend\Console\Getopt('abp:');
+
+// Append an array to the existing arguments
+$opts->addArguments(['-a', '-p', 'p_parameter', 'non_option_arg']);
+
+// Substitute a new array for the existing arguments
+$opts->setArguments(['-a', '-p', 'p_parameter', 'non_option_arg']);
+```
+
+## Adding Configuration
+
+The third parameter to the `Zend\Console\Getopt` constructor is an array of
+configuration options that affect the behavior of the object instance returned.
+You can also specify configuration options using the `setOptions()` method, or
+you can set an individual option using the `setOption()` method.
+
+> ### Clarifying the Term "option"
+>
+> The term "option" is used for configuration of the `Zend\Console\Getopt` class
+> to match terminology used elsewhere in Zend Framework. These are not the same
+> things as the command-line options that are parsed by the
+> `Zend\Console\Getopt` class.
+
+The currently supported options have constant definitions in the class. The
+options, along with their constant identifiers and literal values (in
+parentheses) are listed below:
+
+- `Zend\Console\Getopt::CONFIG_DASHDASH` ("dashDash"), if `TRUE`, enables the
+  special flag `--` to signify the end of flags. Command-line arguments
+  following the double-dash signifier are not interpreted as options, even if
+  the arguments start with a dash. This configuration option is `TRUE` by
+  default.
+- `Zend\Console\Getopt::CONFIG_IGNORECASE` ("ignoreCase"), if `TRUE`, makes
+  flags aliases of each other if they differ only in their case. That is, `-a`
+  and `-A` will be considered to be synonymous flags. This configuration option
+  is `FALSE` by default.
+- `Zend\Console\Getopt::CONFIG_RULEMODE` ("ruleMode") may have values
+  `Zend\Console\Getopt::MODE_ZEND` ("zend") and `Zend\Console\Getopt::MODE_GNU`
+  ("gnu"). It should not be necessary to use this option unless you extend the
+  class with additional syntax forms. The two modes supported in the base
+  `Zend\Console\Getopt` class are unambiguous. If the specifier is a string, the
+  class assumes `MODE_GNU`, otherwise it assumes `MODE_ZEND`. But if you extend
+  the class and add more syntax forms, you may need to specify the mode using
+  this option.
+
+More configuration options may be added as future enhancements of this class.
+
+### Using setOption()
+
+The two arguments to the `setOption()` method are a configuration option name
+and an option value.
+
+```php
+$opts = new Zend\Console\Getopt('abp:');
+$opts->setOption('ignoreCase', true);
+```
+
+### Using setOptions()
+
+The argument to the `setOptions()` method is an associative array. The keys of
+this array are the configuration option names, and the values are configuration
+values. This is also the array format used in the class constructor. The
+configuration values you specify are merged with the current configuration; you
+don't have to list all options.
+
+```php
+$opts = new Zend\Console\Getopt('abp:');
+$opts->setOptions([
+    'ignoreCase' => true,
+    'dashDash'   => false,
+]);
+```