doc/README.rst: add reStructuredText README

This is like, half of the man page. But it will be nice to have
something human-readable for Codeberg.

diff --git a/doc/README.rst b/doc/README.rst
new file mode 100644 (file)
index 0000000..d4d5df0
--- /dev/null
+++ b/doc/README.rst
@@ -0,0 +1,83 @@
+Introduction
+============
+
+*This is only a brief introduction, see the man page for a detailed
+overview.*
+
+Haeredes alerts you when NS/MX records are changed.
+
+This is primarily useful for hosting providers. Customers will
+occasionally switch hosts without alerting the current one, leading to
+two problems:
+
+* NS records: the previous host keeps hosting a DNS zone that does
+  nothing. If that host uses their authoritative nameserver as a
+  caching lookup server as well, it may return incorrect results to
+  queries about the domain in question.
+
+* MX records: most mail servers will immediately accept mail for which
+  the server thinks it is the destination. If a mail server is
+  configured as the destination for a domain, but it is not the MX for
+  that domain, mail submitted to that server can be "lost." It is
+  therefore important to remove domains from the old mail host as soon
+  as the MX record is changed.
+
+Haeredes can alert you when these NS/MX records are changed.
+
+
+Usage
+=====
+
+.. code-block:: console
+
+  $ haeredes [OPTIONS] [DELEGATES] <input>
+
+
+Examples
+========
+
+Make sure example.com has the expected name servers, [ab].iana-servers.net:
+
+.. code-block:: console
+
+  $ echo "example.com" | haeredes a.iana-servers.net b.iana-servers.net
+
+Check orlitzky.com using a root nameserver (this checks the registrar
+configuration):
+
+.. code-block:: console
+
+  $ echo "orlitzky.com" | haeredes --server d.gtld-servers.net dns1.viabit.com
+  Domain "orlitzky.com." delegates somewhere else: "dns2.viabit.com."
+
+In this case, we are correctly warned about the second nameserver that
+we forgot to mention.
+
+
+Requirements
+============
+
+All of the software dependencies are listed in the ``haeredes.cabal``
+file. Just use cabal to build it.
+
+
+Installation
+============
+
+Cabal handles the build, so do whatever you normally do to install
+cabal packages. If you just want to install it for your user,
+
+.. code-block:: console
+
+  $ runghc Setup.hs configure --user
+  $ runghc Setup.hs build
+  $ runghc Setup.hs install
+
+should do it.
+
+
+Bugs
+====
+
+Email them to me at michael@orlitzky.com, or report them on `Codeberg
+<https://codeberg.org/mjo/haeredes/issues>`_.