Overhaul README and convert it to markdown

Signed-off-by: David Oberhollenzer <david.oberhollenzer@sigma-star.at>

3 files changed, 117 insertions, 85 deletions

diff --git a/Makefile.am b/Makefile.am
index 27bb063..155ac08 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -8,7 +8,7 @@ bin_PROGRAMS =
 dist_man1_MANS =
 check_PROGRAMS =
 
-EXTRA_DIST = autogen.sh LICENSE README
+EXTRA_DIST = autogen.sh LICENSE README.md
 TESTS =
 
 include doc/Makemodule.am
diff --git a/README b/README
deleted file mode 100644
index 4c2bff3..0000000
--- a/README
+++ /dev/null
@@ -1,84 +0,0 @@
-
- About
- *****
-
-SquashFS is a highly compressed, read only file system often used as a root fs
-on embedded devices, live systems or simply as a compressed archive format.
-
-Think of it as a .tar.gz that you can mount (or XZ, LZO, LZ4, ZSTD).
-
-As the name suggests, this is not the original user space tooling for
-SquashFS, which are currently maintained in parallel elsewhere. After a
-long period of silence on the SourceForge site and mailing list, I
-attempted to fork the existing code base with the intention to
-restructure/clean it up and add many features I personally perceived to
-be missing, but I ultimately decided that it would be easier to start
-from scratch than to work with the existing code.
-
-Here are some of the features that primarily distinguish this package from
-the (at the time of writing recent) squashfs-tools 4.3:
-
- - Reproducible SquashFS images, i.e. deterministic packing without
-   any local time stamps.
- - Linux `gen_init_cpio` like file listing for micro managing the
-   file system contents, permissions, and ownership without having to replicate
-   the file system (and especially permissions) locally.
- - Support for SELinux contexts file (see selabel_file(5)) to generate
-   SELinux labels.
- - Structured and (hopefully) more readable source code that should be better
-   maintainable in the long run.
-
-
-In addition to that, tools have been added to directly convert a tar archive
-into a SquashFS filesystem image and back. This allows for using existing
-tools can work on tar archives seamlessly on SquashFS images.
-
-
-The tools in this package have different names, so they can be installed
-together with the existing tools:
-
- - `gensquashfs` can be used to produce SquashFS images from `gen_init_cpio`
-   like file listings or simply pack an input directory.
- - `rdsquashfs` can be used to inspect and unpack SquashFS images.
- - `sqfs2tar` can turn a SquashFS image into a tar ball, written to stdout.
- - `tar2sqfs` can turn a tar ball (read from stdin) into a SquashFS image.
-
- Future plans
- ************
-
-In addition to the above, the following things would be really nice to
-have eventually:
-
- - A tool for merging multiple images into one
- - A tool for splitting an image
- - A diff tool
-    - Diff of the directory tree of two images
-    - Diff of the file meta data in two images
-    - File level diffs
-    - Combinations of the above in a still human readable form
- - [IN PROGRESS] A *complete* specification of the on-disk format and all the
-   arbitrary checks enforced by the kernel.
- - Patching kernel and user space to support SquashFS on top of UBI
- - Patching kernel and user space to support ACLs
-
- Copyright & License
- *******************
-
-The source code in this package has been written by me, David Oberhollenzer,
-in 2019 and is released under the terms and conditions of the GNU General
-Public License version 3 or later.
-
-To the best of my knowledge, no code has been copied over from the original
-SquashFS tools. The kernel documentation, the kernel headers and this web site
-have been used as main sources for understanding SquashFS:
-
-  https://dr-emann.github.io/squashfs/
-
-Some additional information (such as xattr implementation) has been gathered
-from various mailing lists and other web sources.
-
-Compressor implementations are primarily based on the documentation of the
-compression libraries.
-
-The existing unsquashfs tool and kernel implementation were used for trial and
-error testing during development.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fc46164
--- /dev/null
+++ b/README.md
@@ -0,0 +1,116 @@
+# About
+
+SquashFS is a highly compressed, read only file system often used as a root fs
+on embedded devices, live systems or simply as a compressed archive format.
+
+Think of it as a .tar.gz that you can mount (or XZ, LZO, LZ4, ZSTD).
+
+As the name suggests, this is not the original user space tooling for
+SquashFS, which are currently maintained in parallel elsewhere. After a
+long period of silence on the SourceForge site and mailing list, I
+attempted to fork the existing code base with the intention to
+restructure/clean it up and add many features I personally perceived to
+be missing, but I ultimately decided that it would be easier to start
+from scratch than to work with the existing code.
+
+Here are some of the features that primarily distinguish this package from
+the (at the time of writing recent) squashfs-tools 4.3:
+
+ - Reproducible SquashFS images, i.e. deterministic packing without
+   any local time stamps.
+ - Linux `gen_init_cpio` like file listing for micro managing the
+   file system contents, permissions, and ownership without having to replicate
+   the file system (and especially permissions) locally.
+ - Support for SELinux contexts file (see selabel_file(5)) to generate
+   SELinux labels.
+ - Structured and (hopefully) more readable source code that should be better
+   maintainable in the long run.
+
+
+In addition to that, tools have been added to directly convert a tar archive
+into a SquashFS filesystem image and back. This allows for using existing
+tools can work on tar archives seamlessly on SquashFS images.
+
+
+The tools in this package have different names, so they can be installed
+together with the existing tools:
+
+ - `gensquashfs` can be used to produce SquashFS images from `gen_init_cpio`
+   like file listings or simply pack an input directory.
+ - `rdsquashfs` can be used to inspect and unpack SquashFS images.
+ - `sqfs2tar` can turn a SquashFS image into a tarball, written to stdout.
+ - `tar2sqfs` can turn a tarball (read from stdin) into a SquashFS image.
+
+# Getting and Building the Source Code
+
+Official release tarballs can be obtained here:
+
+https://infraroot.at/pub/squashfs
+
+The official git tree is currently located here:
+
+https://github.com/AgentD/squashfs-tools-ng
+
+If you are working on an official release tarball, you can build the package
+like every autotools based package:
+
+	./configure
+	make
+	make install
+
+If you work on the git tree, you need to bootstrap the build system first:
+
+	./autogen.sh
+
+## Structure of the Source Code
+
+The main functionality of the package is split up into a number of static
+libraries. The actual tools are mainly wrappers around the libraries that
+combine their functionality in a useful way.
+
+The headers of all the libraries can be found in the `include` directory,
+whereas the source code is in a per-library sub-directory within `lib`.
+
+The following components exist:
+ - `libutil.a` built from files in `lib/util` contains miscellaneous helper
+   functions.
+ - `libcompress.a` built from files in `lib/comp/` contains an abstract
+   interface for block compression and concrete implementations using
+   different compressor libraries. It uses an enum from `squashfs.h` to
+   identify compressors but it only depends on functions from `libutil.a`.
+   A program using `libcompress.a` also has to link against the various
+   compressor libraries.
+ - `libfstree.a` built from files in `lib/fstree` contains functions for
+   manipulating a file system tree. It only depends on `libutil.a`
+ - `libtar.a` built from files in `lib/tar` contains data structures and
+   functions for parsing and creating tar files. It only depends
+   on `libutil.a`.
+ - `libsquashfs.a` built from files in `lib/sqfs` contains all kinds of
+   data structures for reading and writing SquashFS archives. It is built
+   on top of `libutil.a`, `libfstree.a` and `libcompress.a`.
+
+The headers in `include` are stuffed with comments on functions an data
+structures.
+
+The `tests` sub-directory contains unit tests for the libraries.
+
+## Further Information
+
+A documentation of the SquashFS on-disk format can be found here:
+
+https://dr-emann.github.io/squashfs/
+
+# Copyright & License
+
+The software in this package is released under the terms and conditions of the
+GNU General Public License version 3 or later. The file `LICENSE` contains a
+copy of the license.
+
+The original source code in this package has been written by David
+Oberhollenzer in 2019. Additional contributions have been added since the
+initial release which makes some parts of the package subject to the copyright
+of the respective authors.
+
+Although the existing squashfs-tools and the Linux kernel implementation have
+been used for testing, the source code in this package is neither based on,
+nor derived from either of them.