README: Move to Markdown, rewrite introduction

Move the README file to Markdown, and update it to attempt to explain
the current status and use of Weston.

The first sections are user-facing, so they can quickly understand what
Weston is, what it does, what it doesn't do, and how to go about using
it. The following sections on libweston and for distribution packagers
are left intact, but should probably be moved to separate documents.

This includes a screenshot of Weston running weston-terminal, Chrome and
simple-egl, which was taken by myself and subject to the same licensing
terms as the rest of the tree.

Signed-off-by: Daniel Stone <daniels@collabora.com>
Reviewed-by: Quentin Glidic <sardemff7+git@sardemff7.net>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>

Makefile.am

@@ -1608,6 +1608,8 @@ SUFFIXES = .1 .5 .7 .man
 
 EXTRA_DIST +=					\
 	CONTRIBUTING.md				\
+	README.md				\
+	doc/wayland-screenshot.jpg		\
 	doc/calibration-helper.bash		\
 	man/weston.man				\
 	man/weston-drm.man			\

README.md

@@ -1,33 +1,81 @@
-			Weston
+Weston
-			======
+======
-
+
-Weston is the reference implementation of a Wayland compositor, and a
+![screenshot of skeletal Weston desktop](doc/wayland-screenshot.jpg)
-useful compositor in its own right.  Weston has various backends that
+
-lets it run on Linux kernel modesetting and evdev input as well as
+Weston is the reference implementation of a Wayland compositor, as well as a
-under X11.  Weston ships with a few example clients, from simple
+useful environment in and of itself.
-clients that demonstrate certain aspects of the protocol to more
+
-complete clients and a simplistic toolkit.  There is also a quite
+Out of the box, Weston provides a very basic desktop, or a full-featured
-capable terminal emulator (weston-terminal) and an toy/example desktop
+environment for non-desktop uses such as automotive, embedded, in-flight,
-shell.  Finally, weston also provides integration with the Xorg server
+industrial, kiosks, set-top boxes and TVs. It also provides a library allowing
-and can pull X clients into the Wayland desktop and act as an X window
+other projects to build their own full-featured environments on top of Weston's
-manager.
+core.
-
+
-Refer to https://wayland.freedesktop.org/building.html for building
+The core focus of Weston is correctness and reliability. Weston aims to be lean
-weston and its dependencies.
+and fast, but more importantly, to be predictable. Whilst Weston does have known
-
+bugs and shortcomings, we avoid unknown or variable behaviour as much as
-The test suite can be invoked via `make check`; see
+possible, including variable performance such as occasional spikes in frame
-https://wayland.freedesktop.org/testing.html for additional details.
+display time.
-
+
-Developer documentation can be built via `make doc`. Output will be in
+A small suite of example or demo clients are also provided: though they can be
-the build root under
+useful in themselves, their main purpose is to be an example or test case for
-
+others building compositors or clients.
-docs/developer/html/index.html
+
-docs/tools/html/index.html
+If you are after a more mainline desktop experience, the
-
+[GNOME](https://www.gnome.org) and [KDE](https://www.kde.org) projects provide
-
+full-featured desktop environments built on the Wayland protocol. Many other
-
+projects also exist providing Wayland clients and desktop environments: you are
-			Libweston
+not limited to just what you can find in Weston.
-			=========
+
+Reporting issues and contributing
+=================================
+
+Weston's development is
+[hosted on freedesktop.org GitLab](https://gitlab.freedesktop.org/wayland/weston/).
+Please also see [the contributing document](CONTRIBUTING.md), which details how
+to make code or non-technical contributions to Weston.
+
+Building Weston
+===============
+
+Weston is built using autotools, with `autogen.sh` and `make`. It often depends
+on the current release versions of
+[Wayland](https://gitlab.freedesktop.org/wayland/wayland) and
+[wayland-protocols](https://cgit.freedesktop.org/wayland/wayland-protocols).
+
+Every push to the Weston master repository and its forks is built using GitLab
+CI. [Reading the configuration](.gitlab-ci.yml) may provide a useful example of
+how to build and install Weston.
+
+More [detailed documentation on building Weston](https://wayland.freedesktop.org/building.html)
+is available on the Wayland site. There are also more details on
+[how to run and write tests](https://wayland.freedesktop.org/testing.html).
+
+Running Weston
+==============
+
+Once Weston is installed, most users can simply run it by typing `weston`. This
+will launch Weston inside whatever environment you launch it from: when launched
+from a text console, it will take over that console. When launched from inside
+an existing Wayland or X11 session, it will start a 'nested' instance of Weston
+inside a window in that session.
+
+Help is available by running `weston --help`, or `man weston`, which will list
+the available configuration options and display backends. It can also be
+configured through a file on disk; more information on this can be found through
+`man weston.ini`.
+
+In some special cases, such as when running remotely or without logind's session
+control, Weston may not be able to run directly from a text console. In these
+situations, you can instead execute the `weston-launch` helper, which will gain
+privileged access to input and output devices by running as root, then granting
+access to the main Weston binary running as your user. Running Weston this way
+is not recommended unless necessary.
+
+
+Libweston
+=========
 
 Libweston is an effort to separate the re-usable parts of Weston into
 a library. Libweston provides most of the boring and tedious bits of