[PATCH weston 3/4] README: Move to Markdown, rewrite introduction
Pekka Paalanen
ppaalanen at gmail.com
Fri Aug 3 10:28:30 UTC 2018
On Sat, 14 Jul 2018 14:09:06 +0100
Daniel Stone <daniels at collabora.com> wrote:
> 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.
>
> Signed-off-by: Daniel Stone <daniels at collabora.com>
> ---
> README => README.md | 108 ++++++++++++++++++++++++++-----------
> doc/wayland-screenshot.jpg | Bin 0 -> 143832 bytes
> 2 files changed, 78 insertions(+), 30 deletions(-)
> rename README => README.md (69%)
> create mode 100644 doc/wayland-screenshot.jpg
>
> diff --git a/README b/README.md
> similarity index 69%
> rename from README
> rename to README.md
> index a0a078c46..404859548 100644
> --- a/README
> +++ b/README.md
> @@ -1,33 +1,81 @@
> - 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.
> -
> -The test suite can be invoked via `make check`; see
> -https://wayland.freedesktop.org/testing.html for additional details.
> -
> -Developer documentation can be built via `make doc`. Output will be in
> -the build root under
> -
> -docs/developer/html/index.html
> -docs/tools/html/index.html
> -
> -
> -
> - Libweston
> - =========
> +Weston
> +======
> +
> +
I don't think you need to spell out the whole URL, a local path should
suffice according to the gitlab markdown manual:
Btw. the file you add in this patch is called wayland-screenshot.jpg instead.
> +
> +Weston is the reference implementation of a Wayland compositor, as well as a
> +useful environment in and of itself.
> +
> +Out of the box, Weston provides a partly-featured desktop, or a full-featured
Can we call it full-featured even there? More like "a basic
environment". Or "simple"? "Lean"?
> +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 and provide their own full-featured environments.
A bit of repetition of "full-featured environments".
> +
> +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. The core compositor's performance should always be predictable and
> +measurable.
Could you explain what you mean by predictable and measurable for me? I
can't think of tangible examples of what would or would not be like
that. Not necessarily to add to the README but as background information.
> +
> +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 commit of Weston 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.
I've seen people struggle with the remote launch before, so I filed
https://gitlab.freedesktop.org/wayland/weston/issues/132
> +
> +
> +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
This patch is at least
Acked-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
and could easily be upgraded to R-b.
Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20180803/7e8d39fe/attachment-0001.sig>
More information about the wayland-devel
mailing list