README: Reformat with details blocks to make it more easily skimmable

And add some extra information about bfs-specific features, and
installing dependencies.

1 files changed, 111 insertions, 30 deletions

diff --git a/README.md b/README.md
index d613834..6db8a31 100644
--- a/README.md
+++ b/README.md
@@ -22,10 +22,12 @@ It is otherwise compatible with many versions of `find`, including
 If you're not familiar with `find`, the [GNU find manual](https://www.gnu.org/software/findutils/manual/html_mono/find.html) provides a good introduction.
 
 
-Breadth vs. depth
------------------
+Features
+--------
+
+<details>
+<summary><code>bfs</code> operates breadth-first, which typically finds the file(s) you're looking for faster.</summary>
 
-The advantage of breadth-first over depth first search is that it usually finds the file(s) you're looking for faster.
 Imagine the following directory tree:
 
 <pre>
@@ -69,46 +71,78 @@ haystack/deep/1/2/3
 haystack/deep/1/2/3/4
 ...
 </pre>
+</details>
 
+<details>
+<summary><code>bfs</code> tries to be easier to use than <code>find</code>, while remaining compatible.</summary>
 
-Easy
-----
-
-`bfs` tries to be easier to use than `find`, while remaining compatible.
 For example, `bfs` is less picky about where you put its arguments:
 
 <pre>
-$ <strong>find</strong> -L -name 'needle' <em>haystack</em>
-find: paths must precede expression: haystack
-$ <strong>bfs</strong> -L -name 'needle' <em>haystack</em>
-<strong>haystack/needle</strong>
-
-$ <strong>find</strong> <em>haystack</em> -L -name 'needle'
-find: unknown predicate `-L'
-$ <strong>bfs</strong> <em>haystack</em> -L -name 'needle'
-<strong>haystack/needle</strong>
-
-$ <strong>find</strong> -L <em>haystack</em> -name 'needle'
-<strong>haystack/needle</strong>
-$ <strong>bfs</strong> -L <em>haystack</em> -name 'needle'
-<strong>haystack/needle</strong>
+$ <strong>bfs</strong> -L -name 'needle' <em>haystack</em>    │ $ <strong>find</strong> -L -name 'needle' <em>haystack</em>
+<strong>haystack/needle</strong>                     │ find: paths must precede expression: haystack
+                                    │
+$ <strong>bfs</strong> <em>haystack</em> -L -name 'needle'    │ $ <strong>find</strong> <em>haystack</em> -L -name 'needle'
+<strong>haystack/needle</strong>                     │ find: unknown predicate `-L'
+                                    │
+$ <strong>bfs</strong> -L <em>haystack</em> -name 'needle'    │ $ <strong>find</strong> -L <em>haystack</em> -name 'needle'
+<strong>haystack/needle</strong>                     │ <strong>haystack/needle</strong>
 </pre>
+</details>
+
+<details>
+<summary><code>bfs</code> adds some options that make common tasks easier.</summary>
 
-`bfs` also adds some extra options that make some common tasks easier.
-Compare
+### `-exclude`
+
+The `-exclude` operator skips an entire subtree whenever an expression matches.
+For example, `-exclude -name .git` will exclude any files or directories named `.git` from the search results.
+`-exclude` is easier to use than the standard `-prune` action; compare
 
     bfs -name config -exclude -name .git
 
-vs.
+to the equivalent
 
     find ! \( -name .git -prune \) -name config
 
+Unlike `-prune`, `-exclude` even works in combination with `-depth`/`-delete`.
+
+---
+
+### `-hidden`/`-nohidden`
+
+`-hidden` matches "hidden" files (dotfiles).
+`bfs -hidden` is effectively shorthand for
+
+    find \( -name '.*' -not -name . -not -name ..` \)
+
+`-nohidden` is equivalent to `-exclude -hidden`.
+
+---
 
-Try it!
--------
+### `-unique`
 
-`bfs` may already be packaged for your distribution of choice.
-For example:
+This option ensures that `bfs` only visits each file once, even if it's reachable through multiple hard or symbolic links.
+It's particularly useful when following symbolic links (`-L`).
+
+---
+
+### `-color`/`-nocolor`
+
+When printing to a terminal, `bfs` automatically colors paths like GNU `ls`, according to the `LS_COLORS` environment variable.
+The `-color` and `-nocolor` options override the automatic behavior, which may be handy when you want to preserve colors through a pipe:
+
+    bfs -color | less -R
+
+If the [`NO_COLOR`](https://no-color.org/) environment variable is set, colors will be disabled by default.
+</details>
+
+
+Installation
+------------
+
+<details>
+<summary><code>bfs</code> may already be packaged for your operating system.</summary>
 
 <pre>
 <strong>Alpine Linux</strong>
@@ -132,8 +166,55 @@ For example:
 <strong>Homebrew</strong>
 $ brew install tavianator/tap/bfs
 </pre>
+</details>
+
+<details>
+<summary>To build <code>bfs</code> from source, you may need to install some dependencies.</summary>
+
+The only absolute requirements for building `bfs` are a C compiler and GNU make.
+These are installed by default on many systems, and easy to install on most others.
+Refer to your operating system's documentation on building software.
+
+`bfs` also depends on some system libraries for some of its features.
+These dependencies are optional, and can be turned off at build time if necessary by setting the appropriate variable to the empty string (e.g. `make WITH_ONIGURUMA=`).
+
+| Dependency                                            | Platforms  | `make` flag      |
+|-------------------------------------------------------|------------|------------------|
+| [acl](https://savannah.nongnu.org/projects/acl)       | Linux only | `WITH_ACL`       |
+| [attr](https://savannah.nongnu.org/projects/attr)     | Linux only | `WITH_ATTR`      |
+| [libcap](https://sites.google.com/site/fullycapable/) | Linux only | `WITH_LIBCAP`    |
+| [Oniguruma](https://github.com/kkos/oniguruma)        | All        | `WITH_ONIGURUMA` |
+
+Here's how to install them on some common platforms:
+
+<pre>
+<strong>Alpine Linux</strong>
+# apk add acl-dev attr-dev libcap-dev oniguruma-dev
+
+<strong>Arch Linux</strong>
+# pacman -S acl attr libcap oniguruma
+
+<strong>Debian/Ubuntu</strong>
+# apt install acl libacl1-dev attr libattr1-dev libcap2-bin libcap-dev libonig-dev
+
+<strong>NixOS</strong>
+# nix-env -i acl attr libcap oniguruma
+
+<strong>Void Linux</strong>
+# xbps-install -S acl-devel attr-devel libcap-devel oniguruma-devel
+
+<strong>FreeBSD</strong>
+# pkg install oniguruma
+
+<strong>MacPorts</strong>
+# port install oniguruma6
+
+<strong>Homebrew</strong>
+$ brew install oniguruma
+</pre>
+</details>
 
-To install `bfs` from source, download one of the [releases](https://github.com/tavianator/bfs/releases) or clone the [git repo](https://github.com/tavianator/bfs).
+Once the dependencies are installed, download one of the [releases](https://github.com/tavianator/bfs/releases) or clone the [git repo](https://github.com/tavianator/bfs).
 Then run
 
     $ make
@@ -149,4 +230,4 @@ If you're interested in speed, you may want to build the release version instead
 
 Finally, if you want to install it globally, run
 
-    $ sudo make install
+    # make install