Merge lp:~alan-griffiths/miral/add-introducing_the_miral_api into lp:miral

[Alan Griffiths]

A bit more high level documentation

[Alexandros Frantzis (afrantzis)]

71 + MirAL is the answer to this it provides a stable "abstraction layer" written

Something is missing in this sentence.

Looks good otherwise.

review: Approve

[lp:~alan-griffiths/miral/add-introducing_the_miral_api]

254. By Alan Griffiths on 2016-08-03

Reword for clarity

255. By Alan Griffiths on 2016-08-03

merge lp:miral

[Alexandros Frantzis (afrantzis)]

review: Approve

[Gerry Boland (gerboland)]

review: Approve

=== added file 'doc/introducing_the_miral_api.md'
--- doc/introducing_the_miral_api.md	1970-01-01 00:00:00 +0000
+++ doc/introducing_the_miral_api.md	2016-08-03 14:52:25 +0000
@@ -0,0 +1,25 @@
+Introducing the Miral API {#introducing_the_miral_api}
+=========================
+
+The main() program
+------------------
+
+The main() program from miral-shell looks like this:
+
+\include shell_main.cpp
+
+This shell is providing TitlebarWindowManagerPolicy, TilingWindowManagerPolicy
+and SpinnerSplash. The rest is from MirAL.
+
+If you look for the corresponding code in lp:qtmir and lp:mir you’ll find it
+less clear, more verbose and scattered over multiple files.
+
+A shell has to provide a window management policy (miral-shell provides two: 
+TitlebarWindowManagerPolicy and TilingWindowManagerPolicy). A window management
+policy needs to implement the \ref miral::WindowManagementPolicy interface for
+handling a set of window management events.
+
+The way these events are handled determines the behaviour of the shell.
+
+The \ref miral::WindowManagerTools interface provides the principle methods for
+a window management policy to control Mir. 

=== modified file 'doc/mainpage.md'
--- doc/mainpage.md	2016-08-01 15:43:39 +0000
+++ doc/mainpage.md	2016-08-03 14:52:25 +0000
@@ -3,15 +3,52 @@
 
 MirAL is an ABI stable abstraction layer over Mir (and some working examples).
 
-Mir is a next generation display server targeted as a replacement for the X
-window server system to unlock next-generation user experiences for devices
-ranging from Linux desktop to mobile devices powered by Ubuntu. The primary
-purpose of Mir is to enable the development of the next generation
-[Unity](http://unity.ubuntu.com).
-
+Why MirAL?
+----------
+
+Mir is a library for writing Linux display servers and shells that are
+independent of the underlying graphics stack. It fits into a similar role as an
+X server or Weston (a Wayland server) but was initially motivated by Canonical’s
+vision of "convergent" computing.
+
+The Mir project has had some success in meeting Canonical’s immediate needs –
+it is running in the Ubuntu Touch phones and tablets, and as an experimental
+option for running the Unity8 shell on the desktop.  But because of the
+concentration of effort on delivering the features needed for this internal use
+it hasn’t really addressed the needs of potential users outside of Canonical.
+
+Mir provides two APIs for users: the "client" API is for applications that run
+on Mir and that is largely used by toolkits. There is support for Mir in the GTK
+and Qt toolkits, and in SDL. This works pretty well and the Mir client API has
+remained backwards compatible for a couple of years and can do so for the
+foreseeable future.
+
+The problem is that the server-side ABI compatibility is broken by almost every
+release of Mir. This isn’t a big problem for Canonical, as the API is fairly
+stable and both Mir and Unity8 are in rapid development: rebuilding Unity8
+every time Mir is released is a small overhead. But for independent developers
+the lack of a stable ABI is problematic as they cannot easily synchronize their
+releases to updates of Mir.
+
+MirAL is the answer to this: It offers an "abstraction layer" written over the
+top of the current Mir server API that will provide a stable ABI. There are a
+number of other goals that can be addressed at the same time:
+
+  - The API can be considerably narrowed as a lot of things can be customized
+    that are of no interest to shell development;
+  - A more declarative design style can be followed than the implementation
+    focused approach that the Mir server API follows; and,
+  - Common facilities can be provided that don’t belong in the Mir libraries.
+  
+Mir is supported on a range of platforms including phones, tablets and desktops.
+There is also work to provide it as a "snap" in the "internet of things". The
+miral-shell already works in all these environments (for a suitably forgiving
+value of "works") and is an early opportunity to learn about this alternative
+to X11.
 
 Notes for Developers
 --------------------
 
  - \ref building_and_using_miral
+ - \ref introducing_the_miral_api
  - \ref tasks_for_the_interested_reader
\ No newline at end of file