Re-structure README

README.md

@@ -1,9 +1,6 @@
-[![build status](https://travis-ci.org/derf/feh.svg?branch=master)](https://travis-ci.org/derf/feh)
+# feh - Image Viewer and Cataloguer
 
-Feh – Image viewer and Cataloguer
----
-
-feh is a light-weight, configurable and versatile image viewer.
+**feh** is a light-weight, configurable and versatile image viewer.
 It is aimed at command line users, but can also be started from graphical file
 managers. Apart from viewing images, it can compile text and thumbnail
 listings, show (un)loadable files, set X11 backgrounds, and more.
@@ -13,75 +10,54 @@ and image captions. feh can be controlled by configurable keyboard and mouse
 shortcuts, terminal input and signals.  When no file arguments or filelists are
 specified, feh displays all files in the current directory.
 
-For more information, please refer to the [feh
-website](https://feh.finalrewind.org/) or read the [feh
-manual](https://man.finalrewind.org/1/feh/).
+This README focuses on installation and contribution instructions.  See the
+[feh homepage](https://feh.finalrewind.org/) and the
+[feh(1) manual](https://man.finalrewind.org/1/feh/) for other details.
 
-Dependencies
----
+## Dependencies
 
  * Imlib2
- * libcurl (disable with make curl=0)
+ * libcurl (disable with `curl=0`)
  * libpng
  * libX11
  * libXt
- * libXinerama (disable with make xinerama=0)
+ * libXinerama (disable with `xinerama=0`)
 
-If built with exif=1:
+Only when building with `exif=1`:
 
  * libexif-dev
  * libexif12
 
-If built with magic=1:
+Only when building with `magic=1`:
 
  * libmagic
 
-Recommended Binaries
----
-
- * convert  (supplied by ImageMagick, can be used to load image formats not supported by Imlib2)
-
-Installation
----
-
-**For end users:**
-```bash
-$ make
-$ sudo make install app=1
-```
-
-**For package maintainers and users who do not want feh to install its
-icons into /usr/share:**
-```bash
-$ make
-$ sudo make install
-```
-
-**Explanation:** feh ships some icons and an X11 desktop entry, which allow it to
-be used from file managers, desktop menus and similar. However, installing
-icons to /usr/local/share/... does not seem to work reliably.
-Because of this, when using "make install app=1", feh will install its icons
-to /usr/share/..., even though they technically belong into /usr/local.
+## Build Process
 
-[ZSH completion for
-feh](https://git.finalrewind.org/zsh/plain/etc/completions/_feh) is also
-available.
+feh has been packaged for a variety of distributions, including
+[Arch Linux](https://archlinux.org/packages/extra/x86_64/feh/),
+[Debian](https://packages.debian.org/search?keywords=feh&exact=1),
+[FreeBSD](https://www.freshports.org/graphics/feh), and
+[Ubuntu](https://packages.ubuntu.com/search?keywords=feh&exact=1).
+You can configure, compile and install a custom version as follows.
 
-Make flags
-----------
+### Configuration
 
 feh's build process uses make flags to enable/disable optional features and
-fine-tune the build and installation process. They can be passed as **make**
-arguments or set as environment variables, like so:
+fine-tune the build and installation process. It uses (hopefully) reasonable
+defaults, so you can skip this section if you like.
+
+Make flags can be passed as **make** arguments or set as environment variables,
+like so:
 
 ```bash
-make flag=bool
-make install flag=bool
+$ make flag=bool
+$ make install flag=bool
 ```
 or
 ```bash
-export flag=bool
-make && make install
+$ export flag=bool
+$ make && make install
 ```
 
 The following flags are respected by the makefile. A default value of **1**
@@ -104,7 +80,8 @@ indicates that the corresponding feature is enabled by default.
 For example, `make xinerama=0 debug=1` will disable Xinerama support and
 produce a debug build; libcurl and natural sorting support will remain enabled.
 
-Additionally, the standard variables `PREFIX` and `DESTDIR` are supported.
+Additionally, it supports the standard variables `CFLAGS`, `LDLIBS`, `PREFIX`,
+and `DESTDIR`.
 
 **PREFIX _(default: /usr/local)_** controls where the application and its data files
 will be installed. It must be set both during `make` and `make install`.
@@ -116,18 +93,43 @@ is mostly useful for package maintainers.
 cases, you can set environment variables instead of editing it. E.g.:
 
 ```bash
-CFLAGS='-g -Os' make
+$ CFLAGS='-g -Os' make
 ```
 ```bash
-export DESTDIR=/tmp/feh PREFIX=/usr
-make && make install
+$ export DESTDIR=/tmp/feh PREFIX=/usr
+$ make && make install
 ```
 
 Builtin EXIF support is maintained by Dennis Real, [here](https://github.com/reald/feh).
 
+### Installation
 
-Testing (non-X)
----------------
+Add your own make flags to the following examples as needed.
+
+**For end users:**
+```bash
+$ make
+$ sudo make install app=1
+```
+
+**For package maintainers and users who do not want feh to install its
+icons into /usr/share:**
+```bash
+$ make
+$ sudo make install
+```
+
+**Explanation:** feh ships some icons and an X11 desktop entry, which allow it to
+be used from file managers, desktop menus and similar. However, installing
+icons to /usr/local/share/... does not seem to work reliably.
+Because of this, when using "make install app=1", feh will install its icons
+to /usr/share/..., even though they technically belong into /usr/local.
+
+[ZSH completion for
+feh](https://git.finalrewind.org/zsh/plain/etc/completions/_feh) is also
+available.
+
+## Testing (non-X11)
 
 The non-X11 parts of feh can be automatically tested by running
 
@@ -138,9 +140,7 @@ This requires **perl >= 5.10** and the perl module `Test::Command`. Tests are
 non-interactive and do not require a running X11, so they can safely be run on
 a headless buildserver.
 
-
-Contributing
----
+## Contributing
 
 Bugfixes are always welcome, just open a pull request :)