README.rst: add one to describe what this is

diff --git a/README.rst b/README.rst
new file mode 100644 (file)
index 0000000..6bae6bb
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,44 @@
+Personal Firefox user preferences (user.js)
+
+Overview
+========
+
+This is what I use to synchronize my preferences across Firefox
+installations. Basically a collection of ECMAScript variable
+assignments that are concatenated into a `user.js
+<https://kb.mozillazine.org/User.js_file>`_ file, which can then be
+symlinked into your user's Firefox profile.
+
+In the past I was reluctant to include settings that can easily be
+adjusted via the Firefox UI, but the number of bad ideas that are
+enabled by default these days has made that less attractive. Now you
+can expect to find every minor tweak that I make to a new Firefox
+installation included here. This makes it less useful to you, but more
+useful to me; sorry :)
+
+I have tried to separate the source files into logical groups, like
+``search`` for things that affect searching, and ``ai`` for the new AI
+controls. But not everything fits nicely into a single box, so my
+choices may not always make sense. I've included references for the
+settings when they are available. A decent (but relatively new)
+resource is the `Firefox administrator reference manual
+<https://firefox-admin-docs.mozilla.org/>`_.
+
+.. warning:
+
+   I only use Firefox on `Gentoo linux <https://www.gentoo.org/>`_, so
+   any changes that are made by default on Gentoo **will not** be
+   repeated here. For example, these files do not disable
+   DNS-over-HTTPS, because the Gentoo package already does that.
+
+
+Installation
+============
+
+First run ``make`` to build ``user.js``. This literally just runs
+``cat ai certificates ... > user.js`` on the source files. Feel free
+to do that yourself instead.
+
+If you are feeling lucky and are on a POSIX system, ``make install``
+will attempt to symlink the new ``user.js`` into every user profile
+under ``~/.config/mozilla/firefox``.