README.rst: new file with basic usage information

diff --git a/README.rst b/README.rst
new file mode 100644 (file)
index 0000000..11a5f83
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,81 @@
+Personal library of (probably bad) GNU Octave code
+
+Overview
+========
+
+A collection of Octave functions that I wrote a long time ago. There
+is nothing groundbreaking here, only what I needed to make it through
+a MATLAB-based optimization algorithms course without MATLAB.
+
+Almost everything was compatible with MATLAB at the time, but I am
+happy to say that I have not opened MATLAB in over a decade. Most of
+it should *still* be compatible, because I have barely touched it, but
+for example the ``pkg load statistics;`` now used in a few functions
+are not likely to be portable.
+
+
+Requirements
+============
+
+Octave must have been built with ``--with-arpack`` for the ``svds()``
+call in ``rank_k_approximation.m`` to work. On Gentoo this requires
+``USE=sparse``.
+
+Several functions use ``unifrnd()`` from the `statistics package
+<https://gnu-octave.github.io/packages/statistics/>`_, which in turn
+depends on the `datatypes
+<https://gnu-octave.github.io/packages/datatypes/>`_ package (as of
+Octave 11.1.0). If ``pkg install statistics;`` works for you; do
+that. If not, you can download and install them manually, but please
+make sure you get the latest versions. For example:
+
+.. code-block:: shell
+
+  $ wget https://github.com/pr0m1th3as/datatypes/releases/download/release-1.2.0/datatypes-1.2.0.tar.gz
+  $ wget https://github.com/gnu-octave/statistics/releases/download/release-1.8.2/statistics-1.8.2.tar.gz
+  $ octave -q
+  octave:1> pkg install datatypes-1.2.0.tar.gz;
+  octave:2> pkg install statistics-1.8.2.tar.gz;
+
+
+Installation
+============
+
+Add the repository (and a few subdirectories) to your Octave load
+path in ``~/.octaverc``:
+
+.. code-block:: octave
+
+  ## Add the repository to Octave's load path.
+  repository = "/path/to/repository.git";
+  addpath(repository);
+  addpath(fullfile(repository, "iterative"));
+  addpath(fullfile(repository, "misc"));
+  addpath(fullfile(repository, "optimization"));
+
+If you don't already have an ``~/.octaverc``, you can use the included
+one:
+
+.. code-block:: shell
+
+  $ ln -s /path/to/repository.git/.octaverc ~/.octaverc
+
+But beware that this sets a few MATLAB compatibility options.
+
+
+Testing
+=======
+
+A full test suite is included. You can run it with
+
+.. code-block:: shell
+
+  $ ./run-tests.m
+
+from within the repository. This script accepts an integer argument,
+and will repeat the test suite that many times (some of the tests are
+random):
+
+.. code-block:: shell
+
+  $ ./run-tests.m 5