update docs

5 files changed, 149 insertions, 36 deletions

diff --git a/Makefile b/Makefile
index fff0e0b..9fd1521 100644
--- a/Makefile
+++ b/Makefile
@@ -2,16 +2,17 @@
 RONN =	ronn
 MANPAGE =	einhyrningsins.1
 
-doc/$(MANPAGE): doc/$(MANPAGE).ronn
-	$(RONN) -r $<
+docs: doc/*.ronn
+	$(RONN) -r doc/*.ronn
+	$(RONN) --style toc -5 doc/*.ronn
 
-doc/$(MANPAGE).html: doc/$(MANPAGE).ronn
-	$(RONN) --style toc -5 $<
-
-gh-pages: doc/$(MANPAGE).html
-	cp doc/$(MANPAGE).html /tmp/index.html
+gh-pages: docs
+	mkdir -p /tmp/einhyrningsins-ronn
+	cp doc/*.1.html /tmp/einhyrningsins-ronn
 	git checkout gh-pages
-	cp /tmp/index.html index.html
-	git add -u index.html
+	cp /tmp/einhyrningsins-ronn/*.html .
+	cp einhyrningsins.1.html index.html
+	git add -u *.html
 	git commit -m "updating rendered manpage for github docs"
 	git checkout master
+	rm -r /tmp/einhyrningsins-ronn
diff --git a/README.txt b/README.txt
index 304522e..01500ae 100644
--- a/README.txt
+++ b/README.txt
@@ -8,7 +8,49 @@
 
                                                 ... is einhorn in Rust!
 
-See doc/refs.txt for further reading.
+`einhyrningsins` is a socket multiplexer featuring graceful restarts. It runs
+multiple copies of a child program, each of which are passed a shared socket
+(or multiple shared sockets) to bind(2) to and accept(2) connections from.
+Graceful, rolling restarts enable updates of the child program with zero
+downtime and no dropped connections.
+
+`einhyrningsins` is a partially-comparible re-implementation of Einhorn (a Ruby
+program) in Rust. Einhorn itself derived from Unicorn.  The word
+"einhyrningsins" is Icelandic for unicorn.
+
+Read the manual page at:
+https://bnewbold.github.io/einhyrningsins/einhyrningsins.1.html
+
+NOTE: `einhyrningsins` is a for-fun hobby project. It is not feature complete,
+fully documented, or tested. See also ./TODO and unstructured notes in ./doc/.
+
+Building and Installation
+---------------------------
+
+For now both building and installation are done with rust's cargo tool, usually
+bundled with the toolchain. If you haven't used rust before, "rustup" is highly
+recommended. einhyrningsins builds with the 'stable' compiler, and was
+developed against version 1.12 of the toolchain (September 2016). To build and
+install:
+
+    cargo build --release
+    cargo install
+
+Manpages (in both roff and HTML format) are built using the `ronn` tool, which
+is available in many package managers. To build those pages, run:
+
+    make docs
+
+There (currently) isn't an automated way to install the manpages.
+
+Differences from Einhorn
+--------------------------
+
+ * Ruby pre-loading is not possible
+ * einhyrningsins does not reload *itself* on upgrades (aka restarts)
+ * control socket message line format is JSON, not YAML-in-URL-encoding
+ * passing control socket file descriptor is unimplemented
+ * children start all-at-once, not with a delay between spawns
 
 License
 ---------
diff --git a/doc/einhyrningsins.1.ronn b/doc/einhyrningsins.1.ronn
index 90ea89f..3a1d1c0 100644
--- a/doc/einhyrningsins.1.ronn
+++ b/doc/einhyrningsins.1.ronn
@@ -3,40 +3,98 @@ einhyrningsins(1) -- graceful restarts for socket-based daemons
 
 ## SYNOPSIS
 
-`einhyrningsins` [OPTIONS] -- PROGRAM [PROGRAM_ARGS]
+`einhyrningsins` [<OPTIONS>] [--] <PROGRAM> [<PROGRAM_ARGS>]
 
 ## DESCRIPTION
 
-This is a socket multiplexer featuring graceful restarts. It runs multiple
-copies of the child program that are passed a shared socket (or more than one)
-to bind to and accept connections from. Graceful rolling restarts enable
-updates of the child program with zero downtime and no dropped connections.
+`Einhyrningsins` is a socket multiplexer featuring graceful restarts. It runs
+multiple copies of a child program, each of which are passed a shared socket
+(or multiple shared sockets) to bind(2) to and accept(2) connections from.
+Graceful, rolling restarts enable updates of the child program with zero
+downtime and no dropped connections.
 
 This program requires special support in the child program to achive the
-graceful restarts and bind to inherited file descriptors indicated by
-environment variables.
+graceful restarts (aka, exiting only after all connection close) and to be able
+to bind to inherited file descriptors (as indicated by environment variables).
+Child programs must also be able to run in parallel: for example, each copy
+must not try to write to the same output file without some form of locking.
 
-einhyrningsins(1) is a partially-comparible re-implementation of einhorn(1) (a
-Ruby program) in Rust.  Einhorn itself derived from Unicorn.
-
- * `-n`, `--number`=COUNT
+ * `-n`, `--number` <COUNT>:
    How many child processes to spawn.
- * `-b`, `--bind` ADDR
-   Socket(s) to bind to. This argument can be repeated.
+
+ * `-b`, `--bind` <ADDR>:<PORT>[,<OPT>...]:
+   Socket(s) to bind to. <OPT> specifies flags to be set on the socket. Options
+   are `n` for non-blocking (`O_NONBLOCK`) and `r` for re-using addresses
+   (`SO_REUSEADDR`). Eg, for both options, could pass `-b 127.0.0.1:1234,r,n`.
+   This argument can be repeated.
+
  * `-4`, `--ipv4-only`:
    Only accept IPv4 connections
- * `-6`, `--ipv6-only`
+
+ * `-6`, `--ipv6-only`:
    Only accept IPv6 connections
- * `-h`, `--help`
+
+ * `-h`, `--help`:
    Print a help menu
- * `--version`
+
+ * `--version`:
    Print program version
- * `-v`, `--verbose`
+
+ * `-v`, `--verbose`:
    More verbose logging and output
 
+ * `--syslog`:
+   Enables logging via syslog(2) (for WARN and above).
+
+ * `-m`, `--manual`:
+   Enable manual (explicit) acknowledge mode, in which each child program must
+   connect to the master's control socket and "ACK" within a graceperiod, or it
+   will be considered unhealthy and get restarted.
+
+ * `--drop-env-var` <VAR>:
+   Clears the given variable from the child's environment. All other variables
+   are passed through by default. This argument can be repeated.
+
+ * `-d`, `--socket-path` <PATH>:
+   Where to create the control socket (default: `/tmp/einhorn.sock`).
+
+ * `-r`, `--retries` <COUNT>
+   How many times to attempt re-spawning before giving up.
+
+
+## CHILD API
+
+`Einhyrningsins` creates children by fork(1)-ing a new process and
+execve(1)-ing to run the proces itself. For every socket specified by a `-b`
+flag, a socket is bound in the main `einhyrningsins` process and then
+explicitly flagged to be passed on to the child processes. This means the child
+process will already have a valid file descriptor bound to each of the shared
+sockets. The file descriptor numbers are passed via the following environment
+variables:
+
+ * `EINHORN_FD_COUNT`:
+   How many sockets have been passed.
+ * `EINHORN_FD_<NUM>`:
+   One evironment for each socket with <NUM> from 0 to `EINHORN_FD_COUNT-1`.
+
+When `einhyrningsins` is run in manual mode, each child process should connect
+to the control socket (at the UNIX path given by the `EINHORN_SOCK_PATH`
+variable) and write(2) a newline-terminated string like the following,
+containing the child's PID number:
+
+  `{"command":"worker:ack", "pid":<PID>}`
+
+## HISTORY
+
+`Einhyrningsins` is a partially-comparible re-implementation of einhorn(1) (a
+Ruby program) in Rust. Einhorn itself derived from Unicorn.
+
+The word "Einhyrningsins" is Icelandic for unicorn.
+
 ## STATUS
 
-This is a fun fun hobby project. Still in progress, and notably untested.
+`Einhyrningsins` is a for-fun hobby project. It is not feature complete, fully
+documented, or tested.
 
 ## COPYRIGHT
 Copyright 2016  Bryan Newbold
@@ -45,4 +103,4 @@ This is free software: you are free to change and redistribute it. There is NO
 WARRANTY, to the extent permitted by law.
 
 ## SEE ALSO
-`einhorn (1)`, `einhyrningsinsctl(1)`
+einhorn(1), einhyrningsinsctl(1), socket(7)
diff --git a/doc/einhyrningsinsctl.1.ronn b/doc/einhyrningsinsctl.1.ronn
index 1c9056f..37e8d70 100644
--- a/doc/einhyrningsinsctl.1.ronn
+++ b/doc/einhyrningsinsctl.1.ronn
@@ -3,21 +3,26 @@ einhyrningsinsctl(1) -- control of einhyrningsins
 
 ## SYNOPSIS
 
-`einhyrningsinsctl` [OPTIONS] [-e CMD]
+`einhyrningsinsctl` [<OPTIONS>] [-e <CMD>]
 
 ## DESCRIPTION
 
-Tiny shell client for einhyrningsins(1), which connects to a control socket
-(UNIX domain socket) and either sends a single command or acts as an
-interactive shell.
+`Einhyrningsinsctl` is a shell client for einhyrningsins(1), which connects to
+a control socket (UNIX domain socket) and either sends a single command (via
+`-e`) or acts as an interactive shell.
 
- * `-e`, `--execute`=CMD:
+For a list of valid commands, start in shell mode and run `help`.
+
+ * `-e`, `--execute` <CMD>:
    Instead of starting a shell, just execute the CMD.
- * `-d`, `--socket-path`=PATH:
+
+ * `-d`, `--socket-path` <PATH>:
    Where to look for the control socket (a UNIX domain socket).
    Defaults to `/tmp/einhorn.sock`.
+
  * `-h`, `--help`:
    Summary of options (of course)
+
  * `--version`:
    Prints version number
 
@@ -28,4 +33,4 @@ This is free software: you are free to change and redistribute it. There is NO
 WARRANTY, to the extent permitted by law.
 
 ## SEE ALSO
-`einhorn (1)`, `einhyrningsins(1)`
+einhorn(1), einhyrningsins(1)
diff --git a/doc/index.txt b/doc/index.txt
new file mode 100644
index 0000000..d2a3714
--- /dev/null
+++ b/doc/index.txt
@@ -0,0 +1,7 @@
+
+# These are cross-links for ronn (manpage+html documentation creator)
+einhyrningsins(1)       einhyrningsins.1
+einhyrningsinsctl(1)    einhyrningsinsctl.1
+
+# External links
+einhorn(1)              https://github.com/stripe/einhorn