doc/README.rst: new reStructuredText README.rst

Basically a duplicate of the man page, but will look nicer
on Codeberg.

diff --git a/doc/README.rst b/doc/README.rst
new file mode 100644 (file)
index 0000000..3c4b90c
--- /dev/null
+++ b/doc/README.rst
@@ -0,0 +1,98 @@
+Overview
+========
+
+A command-line utility to validate email addresses. It takes a list of
+addresses, and tries to remove the bad ones. It does this without
+sending any mail.
+
+Addresses are validated using three techniques:
+
+#. Ensuring that the length of local and domain parts is within the
+   RFC-specified limits.
+
+#. A syntax check using a regular expression, or the full
+   `RFC 5322 <https://www.rfc-editor.org/rfc/rfc5322>`_
+   grammar (see the ``--rfc5322`` option).
+
+#. Confirmation of the existence of an MX record for the domain part
+   of the address.
+   `NULLMX (RFC7505) <https://www.rfc-editor.org/rfc/rfc7505>`_
+   records are not accepted. This is not required; in fact many
+   domains accept mail via an A record for (say) example.com which is
+   used in lieu of an MX record. This behavior can be controlled via
+   the ``--accept-a`` flag, but note that ``--accept-a`` is ignored
+   for domains that have NULLMX records.
+
+These checks are performed in parallel using the number of available
+threads. To increase the number of threads, you can pass the
+appropriate flag to the GHC runtime.
+
+This will set the number of threads to 25:
+
+.. code-block:: console
+
+  user $ email-validator -i addresses.csv +RTS -N25
+
+
+Usage
+=====
+
+.. code-block:: console
+
+  user $ email-validator [-har] [-i FILE] [-o FILE] <input>
+
+Input
+-----
+
+The input file (default: stdin) should be a list of email addresses,
+one per line. Empty lines are ignored.
+
+Output
+------
+
+Valid email addresses will be written to the output file (default:
+stdout), one per line.
+
+Options
+-------
+
+--accept-a, -a
+  Accept an A record for the domain instead of requiring
+  an MX record (the default).
+--input, -i
+  Specify the input file containing a list of email addresses,
+  rather than using stdin (the default).
+--output, -o
+    Specify the output file to which the good addresses will
+    be written, rather than using stdout (the default).
+--rfc5322, -r
+    Verify addresses against RFC 5322 rather than a naive regular
+    expression. This is much more lenient than the default.
+
+
+Requirements
+============
+
+All dependencies are listed in the ``email-validator.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
+
+  user $ runghc Setup.hs configure --user
+  user $ runghc Setup.hs build
+  user $ 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/email-validator/issues>`_