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>
diff --git a/Makefile.am b/Makefile.am
index 67670d3..83bb253 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1608,6 +1608,8 @@
EXTRA_DIST += \
CONTRIBUTING.md \
+ README.md \
+ doc/wayland-screenshot.jpg \
doc/calibration-helper.bash \
man/weston.man \
man/weston-drm.man \
diff --git a/README b/README.md
similarity index 69%
rename from README
rename to README.md
index a0a078c..d61b932 100644
--- a/README
+++ b/README.md
@@ -1,33 +1,81 @@
- Weston
- ======
+Weston
+======
-Weston is the reference implementation of a Wayland compositor, and a
-useful compositor in its own right. Weston has various backends that
-lets it run on Linux kernel modesetting and evdev input as well as
-under X11. Weston ships with a few example clients, from simple
-clients that demonstrate certain aspects of the protocol to more
-complete clients and a simplistic toolkit. There is also a quite
-capable terminal emulator (weston-terminal) and an toy/example desktop
-shell. Finally, weston also provides integration with the Xorg server
-and can pull X clients into the Wayland desktop and act as an X window
-manager.
+
-Refer to https://wayland.freedesktop.org/building.html for building
-weston and its dependencies.
+Weston is the reference implementation of a Wayland compositor, as well as a
+useful environment in and of itself.
-The test suite can be invoked via `make check`; see
-https://wayland.freedesktop.org/testing.html for additional details.
+Out of the box, Weston provides a very basic desktop, or a full-featured
+environment for non-desktop uses such as automotive, embedded, in-flight,
+industrial, kiosks, set-top boxes and TVs. It also provides a library allowing
+other projects to build their own full-featured environments on top of Weston's
+core.
-Developer documentation can be built via `make doc`. Output will be in
-the build root under
+The core focus of Weston is correctness and reliability. Weston aims to be lean
+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
+possible, including variable performance such as occasional spikes in frame
+display time.
-docs/developer/html/index.html
-docs/tools/html/index.html
+A small suite of example or demo clients are also provided: though they can be
+useful in themselves, their main purpose is to be an example or test case for
+others building compositors or clients.
+
+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
+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
+=========
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
diff --git a/doc/wayland-screenshot.jpg b/doc/wayland-screenshot.jpg
new file mode 100644
index 0000000..4d8f35c
--- /dev/null
+++ b/doc/wayland-screenshot.jpg
Binary files differ
