doc/README: convert to reStructuredText

For the sake of Codeberg, and since it is still human-readable,
convert the README to README.rst.

diff --git a/doc/README b/doc/README
deleted file mode 100644 (file)
index 41c38cc..0000000
--- a/doc/README
+++ /dev/null
@@ -1,46 +0,0 @@
-1. What is it?
-
-A utility to apply default POSIX ACLs to files and directories.
-
-The way some common utilities handle POSIX ACLs is busted. For more
-info, see [1].
-
-
-2. Requirements
-
-Right now, this will probably only work on Linux because I'm
-lazy. You'll need the sys/acl.h and acl/libacl.h headers from [2], at
-least until I decide to replace acl_get_perm with something portable
-(or just steal it).
-
-
-3. Installation
-
-It's using GNU Autotools, so run `./configure && make` and maybe `make
-install` if you think it's going to wind up in the right
-place. Otherwise you can just take the binary out of the 'src'
-directory and put it somewhere in your $PATH.
-
-
-4. Usage
-
-Basic usage:
-
-  $ apply-default-acl /path/to/whatever
-
-Work recursively (from the top down):
-
-  $ apply-default-acl --recursive /path/to/whatever
-  $ apply-default-acl -r /path/to/whatever
-
-5. How to report bugs
-
-Email them to me at michael@orlitzky.com, or report them on
-Codeberg at https://codeberg.org/mjo/apply-default-acl/issues
-
-
-
-[1] http://michael.orlitzky.com/articles/problems_with_posix_acls_and_common_utilities.php
-
-[2] http://savannah.nongnu.org/projects/acl
-

diff --git a/doc/README.rst b/doc/README.rst
new file mode 100644 (file)
index 0000000..28649d4
--- /dev/null
+++ b/doc/README.rst
@@ -0,0 +1,51 @@
+What is it?
+===========
+
+A utility to apply default POSIX ACLs to files and directories.
+
+The way common utilities handle POSIX ACLs is busted, and
+*apply-default-acl* is a non-intrusive workaround. For more
+information, see the following articles:
+
+* `Problems with POSIX ACLs and common utilities <https://michael.orlitzky.com/articles/problems_with_posix_acls_and_common_utilities.xhtml>`_
+* `Fixing POSIX ACLs in common utilities <https://michael.orlitzky.com/articles/fixing_posix_acls_in_common_utilities.xhtml>`_
+* `Fix busted ACLs faster with libadacl <https://michael.orlitzky.com/articles/fix_busted_acls_faster_with_libadacl.xhtml>`_
+
+
+Requirements
+============
+
+Right now, this only works on Linux, and you'll need `libacl
+<https://savannah.nongnu.org/projects/acl>`_ installed.
+
+
+Installation
+============
+
+It's using GNU Autotools, so run ``./configure && make`` and maybe ``make
+install`` if you think it's going to wind up in the right
+place. Otherwise you can just take the binary out of the *src*
+directory and put it somewhere in your ``$PATH``.
+
+
+Usage
+=====
+
+Basic usage:
+
+.. code-block:: console
+
+  $ apply-default-acl /path/to/whatever
+
+Work recursively (from the top down):
+
+.. code-block:: console
+
+  $ apply-default-acl --recursive /path/to/whatever
+  $ apply-default-acl -r /path/to/whatever
+
+How to report bugs
+==================
+
+Email them to me at michael@orlitzky.com, or report them on `Codeberg
+<https://codeberg.org/mjo/apply-default-acl/issues>`_.