Update docs

- add some project info for the main readme
- migrate readmes to markdown for improved formatting
- The main binary now requires the Rust toolchain, so make note of it
  in the build instructions.

Signed-off-by: Alexander Fougner <fougner89@gmail.com>

INSTALL

@@ -1,75 +0,0 @@
--- Getting started --
-
-Dependencies:
-
- * libaio
- * libblkid
- * libkeyutils
- * liblz4
- * libsodium
- * liburcu
- * libuuid
- * libzstd
- * pkg-config
- * zlib1g
- * valgrind
-
-Debian (Bullseye or later) and Ubuntu (20.04 or later): you can install these with
-    apt install -y pkg-config libaio-dev libblkid-dev libkeyutils-dev \
-        liblz4-dev libsodium-dev liburcu-dev libzstd-dev \
-        uuid-dev zlib1g-dev valgrind libudev-dev git build-essential \
-        python3 python3-docutils
-
-Fedora: install the "Development tools" group along with:
-    dnf install -y libaio-devel libsodium-devel \
-        libblkid-devel libzstd-devel zlib-devel userspace-rcu-devel \
-        lz4-devel libuuid-devel valgrind-devel keyutils-libs-devel \
-        findutils
-
-Arch: install bcachefs-tools-git from the AUR.
-Or to build from source, install build dependencies with
-    pacman -S base-devel libaio keyutils libsodium liburcu zstd valgrind
-
-Then, just make && make install
-
-
--- Experimental features --
-
-Experimental fuse support is currently disabled by default. Fuse support is at
-an early stage and may corrupt your filesystem, so it should only be used for
-testing. To enable, you'll also need to add:
-
-* libfuse3 >= 3.7
-
-On Debian/Ubuntu (Bullseye/20.04 or later needed for libfuse >= 3.7):
-    apt install -y libfuse3-dev
-
-On Fedora (32 or later needed for lbifuse >= 3.7):
-    dnf install -y fuse3-devel
-
-Arch:
-    pacman -S fuse3
-
-Then, make using the BCACHEFS_FUSE environment variable (make clean first if
-previously built without fuse support):
-
-BCACHEFS_FUSE=1 make && make install
-
-
--- Tests --
-
-Some tests are available to validate the "bcachefs" binary.  The tests depend
-on python3 pytest.
-
-On debian:
-    apt install -u python3-pytest
-
-Then, you can run the tests via:
-
-    make check
-    # or if pytest has a different name
-    make check PYTEST=pytest
-
-Optionally, you may wish to run tests in parallel using python3-pytest-xdist:
-
-    cd tests; pytest-3 -n4

INSTALL.md

@@ -0,0 +1,101 @@
+Getting started
+---------------
+
+Build dependencies:
+
+ * libaio
+ * libblkid
+ * libkeyutils
+ * liblz4
+ * libsodium
+ * liburcu
+ * libuuid
+ * libzstd
+ * pkg-config
+ * valgrind
+ * zlib1g
+
+In addition a recent Rust toolchain is required (rustc, cargo), either by using
+[rustup](https://rustup.rs/) or make sure to use a distribution where rustc (>=1.64)
+is available.
+
+Debian (Bullseye or later) and Ubuntu (20.04 or later): you can install these with
+
+``` shell
+apt install -y pkg-config libaio-dev libblkid-dev libkeyutils-dev \
+    liblz4-dev libsodium-dev liburcu-dev libzstd-dev \
+    uuid-dev zlib1g-dev valgrind libudev-dev git build-essential \
+    python3 python3-docutils
+```
+
+Fedora: install the "Development tools" group along with:
+```shell
+dnf install -y libaio-devel libsodium-devel \
+    libblkid-devel libzstd-devel zlib-devel userspace-rcu-devel \
+    lz4-devel libuuid-devel valgrind-devel keyutils-libs-devel \
+    findutils
+```
+
+Arch: install bcachefs-tools-git from the AUR.
+Or to build from source, install build dependencies with
+```shell
+pacman -S base-devel libaio keyutils libsodium liburcu zstd valgrind
+```
+
+Then, just `make && make install`
+
+
+Experimental features
+---------------------
+
+Experimental fuse support is currently disabled by default. Fuse support is at
+an early stage and may corrupt your filesystem, so it should only be used for
+testing. To enable, you'll also need to add:
+
+* libfuse3 >= 3.7
+
+On Debian/Ubuntu (Bullseye/20.04 or later needed for libfuse >= 3.7):
+```shell
+apt install -y libfuse3-dev
+```
+
+On Fedora (32 or later needed for lbifuse >= 3.7):
+```shell
+dnf install -y fuse3-devel
+```
+
+Arch:
+```shell
+pacman -S fuse3
+```
+
+Then, make using the `BCACHEFS_FUSE` environment variable (make clean first if
+previously built without fuse support):
+
+```shell
+BCACHEFS_FUSE=1 make && make install
+```
+
+Tests
+-----
+Some tests are available to validate the `bcachefs` binary.  The tests depend
+on python3 pytest.
+
+On debian:
+```shell
+apt install -u python3-pytest
+```
+
+Then, you can run the tests via:
+
+```shell
+make check
+# or if pytest has a different name
+make check PYTEST=pytest
+```
+
+Optionally, you may wish to run tests in parallel using python3-pytest-xdist:
+
+```shell
+cd tests; pytest-3 -n4
+```

README

@@ -1,12 +0,0 @@
-Userspace tools for bcachefs
-
-This builds the bcachefs tool, which has a number of subcommands for formatting
-and managing bcachefs filesystems:
-
-bcachefs format
-bcachefs unlock
-bcachefs assemble
-bcachefs incremental
-etc.
-
-Run bcachefs --help for full list of commands.

README.md

@@ -0,0 +1,27 @@
+bcachefs-tools
+==============
+Userspace tools and docs for bcachefs
+
+Bcachefs is an advanced new filesystem for Linux, with an emphasis on reliability and robustness
+and the complete set of features one would expect from a modern filesystem.
+
+This repo primarily consists of the following:
+
+- bcachefs tool, the reason this repo exists.
+- {mkfs,mount,fsck}.bcachefs utils, which is just wrappers calling the corresponding subcommands
+  in the main tool
+- docs in the form of man-pages and a user manual
+
+Please refer to the main site for [getting started](https://bcachefs.org/#Getting_started)
+An in-depth user manual is (also) found on the [official website](https://bcachefs.org/#Documentation)
+
+Build and install
+-----------------
+
+Refer to [INSTALL.md](./INSTALL.md)
+
+Bug reports and contributions
+-----------------------------
+
+- The official mailing list, linux-bcachefs@vger.kernel.org
+- IRC: #bcache on OFTC (irc.oftc.net). Although, note that it can be easily missed.