README

3 files changed, 99 insertions, 108 deletions

diff --git a/Makefile b/Makefile
index 7e1a74c..b203340 100644
--- a/Makefile
+++ b/Makefile
@@ -25,4 +25,7 @@ install:
         $(ROOT_INSTALL)        -t "$(SSH_LIB_DIR)" AuthorizedKeysCommand || true
         [ -e "$(SSH_LIB_DIR)"/AuthorizedKeysCommand ] || $(SUDO) ln -s -t /etc/ssh "$(SSH_LIB_DIR)"/AuthorizedKeysCommand
 
+README.html: README.md
+        pandoc -t html $< > $@
+
 include tests.makefile
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d4b8127
--- /dev/null
+++ b/README.md
@@ -0,0 +1,96 @@
+AnonymousSSH
+------------
+
+
+
+
+
+
+WHAT IT DOES
+------------
+
+This repository contains the code to share itself (the repository)
+through Git-over-SSH.
+
+It also contains the code to listen for changes sent to itself through
+Git-over-SSH.
+
+
+
+
+
+
+HOW IT WORKS
+------------
+
+Git contains a program `git-receive-pack` which implements a git
+protocol server. The `git-receive-pack` expects to be launched as an SSH
+server "ForcedCommand" in a configuration that protects the server from
+untrustworthy users.
+
+Normally, the SSH server only permits users who have already uploaded
+their public keys to the server. It assumes that access should be closed
+to new users.
+
+Installing this code reverses that assumption, granting open access to
+unrecognized users. This is made safe by limiting write access to a
+GIT_NAMESPACE over which the user proves global mathematical ownership
+with their SSH client key.
+
+
+
+
+
+
+HOW TO INSTALL
+--------------
+
+Run:
+```
+  make
+```
+
+This installs the `AnonymousAccessCommand` in the current user's home
+directory.
+
+Then, if sudo access is available, it enables anonymous access by
+editing the system `OpenSSH` configuration.
+
+
+
+
+
+
+NON-ROOT INSTALLATION
+---------------------
+
+If sudo access is not available, you can install to a different
+location:
+
+```
+  make SSH_CONFIG_DIR=.config/ssh \
+       SSHD_CONFIG_DIR=.config/ssh/config.d \
+       SSH_LIB_DIR=.local/lib/ssh
+```
+
+Then you will need to run `OpenSSH` on a non-default port (the default
+port requires root access).
+
+
+
+
+
+
+ALTERNATIVE LOCATION OF `AnonymousAccessCommand`
+------------------------------------------------
+
+It is also possible to choose the location of the
+`AnonymousAccessCommand` itself:
+
+```
+  make USER_SSH_CONFIG_DIR=$HOME/.config/ssh
+```
+
+First you would have to make the contents of the installed file
+`AuthorizedKeysCommand` vary according to that `Makefile` paremeter, by
+editing `Makefile`.
diff --git a/README.txt b/README.txt
deleted file mode 100644
index e65cdbe..0000000
--- a/README.txt
+++ /dev/null
@@ -1,108 +0,0 @@
-WHAT IT DOES
-------------
-
-This repository contains the code to share itself through Git-over-SSH.
-
-It also contains the code to listen for changes sent to itself through
-Git-over-SSH.
-
-
-
-
-.
-.
-.
-.
-.
-.
-
-
-
-HOW IT WORKS
-------------
-
-Git contains a program `git-receive-pack` which implements a git protocol
-server. The `git-receive-pack` expects to be launched as an SSH server
-"ForcedCommand" in a configuration that protects the server from untrustworthy
-users.
-
-
-
-.
-.
-.
-.
-.
-.
-HOW TO INSTALL
---------------
-
-
-Run:
-
-
-    make
-
-
-
-This installs the `AnonymousAccessCommand` in the current user's home directory.
-
-Then, if sudo access is available, it enables anonymous access by editing the
-system `OpenSSH` configuration.
-
-
-
-.
-.
-.
-.
-.
-.
-
-
-
-NON-ROOT INSTALLATION
----------------------
-
-If sudo access is not available, you can install to a different location:
-
-```
-  make SSH_CONFIG_DIR=.config/ssh \
-       SSHD_CONFIG_DIR=.config/ssh/config.d \
-       SSH_LIB_DIR=.local/lib/ssh
-```
-
-Then you will need to run `OpenSSH` on a non-default port (the default port
-requires root access).
-
-
-
-.
-.
-.
-.
-.
-.
-
-
-
-ALTERNATIVE LOCATION OF `AnonymousAccessCommand`
-------------------------------------------------
-
-It is also possible to choose the location of the `AnonymousAccessCommand` itself:
-
-```
-  make USER_SSH_CONFIG_DIR=/.config/ssh
-```
-
-First you will have to make `AuthorizedKeysCommand` vary according to that
-paremeter.
-
-
-
-
-
-
-
-
-