Add usage and install documentation.

docs/README.md

@@ -8,7 +8,7 @@ issue, and, even better, a pull request to fix the issue.
 
 - [System Requirements](user/requirements.md)
 - [Install](user/install.md)
-- [Command Line Options](user/cmd.md)
+- [Usage & Running](user/usage.md)
 - [Set Up](user/setup.md)
 - [Configuration Options](user/config.md)
 - [Administrator API](user/admin.md)
@@ -20,6 +20,7 @@ issue, and, even better, a pull request to fix the issue.
 
 ## Miscellaneous
 
+- [Matrix Specification](https://spec.matrix.org) ([Mirror](https://telodendria.io/spec.matrix.org))
 - [Change Log](CHANGELOG.md)
 - [Project Road Map](ROADMAP.md)
 

docs/user/install.md

@@ -0,0 +1,51 @@
+# Installation
+
+There are multiple methods of installing Telodendria. Choose the one
+best suited to your use case.
+
+## Package Manager Or System Ports
+
+This is the recommended way to install Telodendria. If your operating
+system has an official package or port of Telodendria, you should
+prefer to use that instead of the other methods documented here,
+because your operating system or software distribution will have
+already figured out how to best integrate Telodendria with your system.
+
+Consult your operating system or software distribution's system
+manual for instructions on how to install packages. Also consult the
+official repository of your distribution to see if a package is
+available. If a package exists but it is too out of date for your
+tastes, please contact the package's maintainer to notify them, or
+offer to update the package yourself using the
+[porting instructions](../dev/ports.md).
+
+If you are maintaining a port or package for an operating system or
+software distribution, open a pull request to include your
+platform-specific instructions as a subheader of this section.
+Eventually, this section should contain basic instructions for the
+operating systems that have packages or ports.
+See [Ports](../dev/ports.md) for the project's distribution
+philosophy.
+
+## Container
+
+At this time, Telodendria does not have any officially recommended
+procedure for running in a container such as Docker or Vagrant. You
+may find helpful files in the [`contrib/`](../../contrib) directory,
+however.
+
+If you are publishing container images, please open a pull request to
+add your source files to `contrib/`, as well as to add documentation
+under this section explaining how to get set started.
+
+## Release Binary
+
+At this time, Telodendria does not publish any official binaries that
+can be downloaded. The tentative plan is to eventually provide binaries
+with each release for a number of supported platforms. When that
+happens, instructions will be provided here for dealing with the
+binaries.
+
+## From Source
+
+**TODO:** Update this section before #19 is closed.

docs/user/usage.md

@@ -0,0 +1,64 @@
+# Usage
+
+This document provides general documentation on how to use the
+`telodendria` server binary, as well as details on how it behaves.
+The details here will be useful for setting up init systems, running
+Telodendria in a container, or manually executing the binary for
+testing or debugging purposes.
+
+## Command Line Options
+
+Typically, Telodendria is controlled via the
+[Administrator API](admin.md), but the Telodendria binary does include
+a few command line options, which can be used in init scripts or for
+debugging purposes.
+
+The command line arguments are as follows:
+
+- **`-d <dir>`** Specify the data directory to use. All persistent
+storage that Telodendria requires is saved to and loaded from here.
+- **`-V`** Only print the version information header and then quit
+with a success exit code.
+- **`-v`** Verbose mode. This overrides the configuration and sets the
+log level to `debug`. It also enables additional logging of memory
+operations, which can be useful for debugging.
+
+Before proposing additional command line arguments, consider whether or
+not the functionality requested can be provided via a (potentially new
+and as of yet uncreated) administrator API endpoint.
+
+## Environment
+
+Telodendria does not read any environment variables. All configuration
+should be done via the [Configuration API](config.md).
+
+## Signals
+
+Telodendria recognizes and responds to a number of signals:
+
+- **`PIPE`:** This signal is ignored, because all I/O errors should
+already be handled properly.
+- **`USR1`:** Perform a soft restart by shutting down the HTTP servers
+and resetting the program state. Note that the daemon process does
+not exit.
+- **`TERM`:** Perform a clean shutdown after all existing connections
+are closed.
+- **`INT`:** Same as `TERM`.
+
+Any other signals are not explicitly handled, so they have the
+default behavior as defind by the operating system.
+
+## Exit Status
+
+Telodendria exits with a non-0 exit code if the configuration file is
+invalid, or one or more of required paths or files is inaccessible.
+Telodendria will print an error to the log and then terminate
+abnormally.
+
+Telodendria exits with a code of 0 if the configuration file is valid,
+all paths and files required are accessible, and the HTTP listener
+starts as intended. If Telodendria is sent a signal that it catches
+after it begins servicing requests, it will still exit normally after
+it safely shuts down, because the bootstrap process completed
+successfully, and by all accounts, it ran normally and exitted
+normally.