Merge lp:~alan-griffiths/mir/update-docs into lp:mir

[Alan Griffiths]

Updating docs (including integrating MirAL documentation)

[Alan Griffiths (alan-griffiths)]

To test the generated docs:

$ make doc-show

[Mir CI Bot (mir-ci-bot)]

PASSED: Continuous integration, rev:4242
https://mir-jenkins.ubuntu.com/job/mir-ci/3640/
Executed test runs:
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-mir/4979
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-0-fetch/5207
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=artful/5195
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=xenial/5195
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=zesty/5195
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=artful/5018
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=artful/5018/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=zesty/5018
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=zesty/5018/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=artful/5018
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=artful/5018/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=xenial/5018
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=xenial/5018/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=zesty/5018
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=zesty/5018/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=cross-armhf,compiler=gcc,platform=mesa,release=artful/5018
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=cross-armhf,compiler=gcc,platform=mesa,release=artful/5018/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=cross-armhf,compiler=gcc,platform=mesa,release=zesty/5018
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=cross-armhf,compiler=gcc,platform=mesa,release=zesty/5018/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=mesa,release=xenial/5018
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=mesa,release=xenial/5018/artifact/output/*zip*/output.zip

Click here to trigger a rebuild:
https://mir-jenkins.ubuntu.com/job/mir-ci/3640/rebuild

review: Approve (continuous-integration)

[Michał Sawicz (saviq)]

All good!

review: Approve

=== modified file 'HACKING.md'
--- HACKING.md	2017-05-08 03:04:26 +0000
+++ HACKING.md	2017-09-07 10:01:02 +0000
@@ -1,38 +1,6 @@
 Mir hacking guide
 =================
 
-Getting Mir
------------
-
-If you're reading this file then you've probably solved this one. ;)
-
-However, for completeness Mir is a project on LaunchPad (https://launchpad.net/mir)
-to grab a copy use the command:
-
-    $ bzr branch lp:mir
-
-
-Getting dependencies
---------------------
-To succesfully build Mir there are a few packages required:
-
-    $ apt-get install devscripts equivs cmake
-    $ mk-build-deps --install --tool "apt-get -y" --build-dep debian/control
-
-
-Building Mir
------------
-
-Mir is built using cmake. There are other options, but here's one way to
-build the system:
-
-    $ mkdir build
-    $ cd build
-    $ cmake ..
-    $ make -j 8
-    $ ctest
-
-
 Coding Mir
 ----------
 
@@ -109,7 +77,7 @@
 you need to know to get it working, and also to prevent your existing X server
 from dying at the same time.
 
- - \ref using_mir_on_pc
+ - \ref getting_and_using_mir
 
 You can configure Mir to provide runtime information helpful for debugging
 by enabling component reports:

=== modified file 'doc/Doxyfile.in'
--- doc/Doxyfile.in	2017-08-25 10:02:30 +0000
+++ doc/Doxyfile.in	2017-09-07 10:01:02 +0000
@@ -876,7 +876,9 @@
 # exclude all test directories for example use the pattern */test/*
 
 EXCLUDE_PATTERNS       = *.capnp.c++ \
-                         */examples/multi_stream.cpp
+                         @CMAKE_CURRENT_SOURCE_DIR@/include/server/* \
+                         @CMAKE_CURRENT_SOURCE_DIR@/include/test/mir/* \
+                         @CMAKE_CURRENT_SOURCE_DIR@/examples/multi_stream.cpp
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the

=== removed file 'doc/building_source_for_pc.md'
--- doc/building_source_for_pc.md	2017-05-08 03:04:26 +0000
+++ doc/building_source_for_pc.md	1970-01-01 00:00:00 +0000
@@ -1,101 +0,0 @@
-Building the source for a PC {#building_source_for_pc}
-============================
-
-Getting Mir
------------
-
-Mir is a project on Launchpad (https://launchpad.net/mir). To grab a copy use
-the command:
-
-    $ bzr branch lp:mir
-
-The command above will download the latest development version of Mir into
-the 'mir' directory (called the 'project directory' from now on).
-
-Getting dependencies
---------------------
-
-To succesfully build Mir there are a few packages required. The easiest way
-to get them is to use the packaging build dependencies:
-
-    $ sudo apt-get install devscripts equivs cmake
-
-Then, in the project directory:
-
-    $ sudo mk-build-deps -i
-
-
-Building Mir
-------------
-
-Mir is built using CMake. You first need to create the build directory and
-configure the build. In the project directory do:
-
-    $ mkdir build
-    $ cd build
-    $ cmake .. (possibly passing configuration options to CMake)
-
-There are many configuration options for the Mir project. The default options
-will work fine, but you may want to customize the build depending on your
-needs. The best way to get an overview and set them is to use the cmake-gui
-tool:
-
-    $ cmake-gui ..
-
-The next step is to build the source and run the tests:
-
-    $ make (-j8)
-    $ ctest
-
-
-Running Mir
------------
-
-The binaries created in the bin subdirectory of the project directory can be
-used directly. For example,
-
-    $ bin/mir_demo_server --launch-client bin/mir_demo_client_multiwin
-
-Other examples described elsewhere in this documentation assume you're using the
-installed version and simply need "bin/" adding to specify the local build.  
-
-
-Install Mir
------------
-
-*It should not be necessary to install Mir for experimental purposes (see 
-"Running Mir" above).* Further, if you are using an Ubuntu derived disto then
-there's likely to be existing Mir binaries elsewhere that may interact badly 
-with a second install.
-
-To install Mir just use the normal make install command:
-
-    $ sudo make install
-
-This will install the Mir libraries, executable, example clients and header
-files to the configured installation location (/usr/local by default).
-
-NB You may need "sudo ldconfig" to refresh the cache before the installed
-programs work.
-
-If you install to a non-standard location, keep in mind that you will probably 
-need to properly set the PKG_CONFIG_PATH environment variable to allow other
-applications to build against Mir, and LD_LIBRARY_PATH to allow applications to
-find the Mir libraries at runtime.
-
-
-Building Mesa
--------------
-
-*The Mesa packages shipped with Ubuntu are already built with the relevant Mir patches
-and should work out of the box with Mir.*
-
-For GL accelerated clients to use Mir they need to use a patched version of Mesa
-that supports Mir.
-
-The patch is hosted on GitHub:
-
-    $ git clone https://github.com/RAOF/mesa.git
-
-Compile as per normal instructions and pass --with-egl-platforms="mir,drm" to
-the configure options. You will need libmirclient installed as shown above.

=== removed file 'doc/demo_server_controls.md'
--- doc/demo_server_controls.md	2017-05-08 03:04:26 +0000
+++ doc/demo_server_controls.md	1970-01-01 00:00:00 +0000
@@ -1,69 +0,0 @@
-Demo Server {#demo_server}
-===========
-
-Mir's demo server (`mir_demo_server`) is an example of using the Mir to
-build a server. It uses only functionality supported by the public Mir API.
-
-Running Demo Server
--------------------
-
-Remember to always run `mir_demo_server` as root on PC (not required on
-Android), as this is required for input device support (open bug
-https://bugs.launchpad.net/mir/+bug/1286252);
-
-    sudo mir_demo_server
-
-And if you're not already on the VT you wish to use, that needs to be
-specified:
-
-    sudo mir_demo_server --vt 1
-
-There are plenty more options available if you run:
-
-    mir_demo_server --help
-
-The following operations are supported:
-
- - Quit (shut down the Mir server): *Ctrl-Alt-Backspace*
- - Switch back to X: *Ctrl-Alt-F7*
- - Switch virtual terminals (VTs): *Ctrl-Alt-(F1-F12)*
- - Switch apps: *Alt-Tab*, tap or click on the corresponding app
- - Close app: *Alt-F4*
- - Switch window within app: *Alt-`*, tap or click on the window
- - Close surface: *Ctrl-F4*
- - Move window: *Alt-leftmousebutton* drag
- - Resize window: *Alt-middle_button* drag
- - Maximize/restore current window: *Alt-F11*
- - Vertically maximize/restore current window: *Shift-F11*
- - Horizontally maximize/restore current window: *Ctrl-F11*
-
-For those writing client code request to set the surface attribute
-`mir_surface_attrib_state` are honoured:
- - `mir_window_state_restored`: restores the window 
- - `mir_window_state_maximized`: maximizes size
- - `mir_window_state_vertmaximized`: maximizes height
- - `mir_window_state_horizmaximized`: maximizes width
-
-For a quick demo try:
-
-    sudo DISPLAY= mir_demo_server --vt 1 --launch bin/mir_demo_client_egltriangle\
-     --test-client bin/mir_demo_client_multiwin --test-timeout 60
-
-(Remember to unwrap the line)
-
-### Tiling Window Manager
-
-One option that needs elaboration is "--window-manager tiling".
-
-This starts a (rather primitive) tiling window manager. It tracks the available
-displays and splits the available workspace into "tiles" (one per client).
-
-For a quick demo try:
-
-    sudo DISPLAY= mir_demo_server --vt 1 --launch bin/mir_demo_client_egltriangle\
-     --test-client bin/mir_demo_client_multiwin --test-timeout 60\
-     --window-manager tiling
-
-(Remember to unwrap the line)
-
-Want more? Log your requests at: https://bugs.launchpad.net/mir/+filebug

=== added file 'doc/getting_and_using_mir.md'
--- doc/getting_and_using_mir.md	1970-01-01 00:00:00 +0000
+++ doc/getting_and_using_mir.md	2017-09-07 10:01:02 +0000
@@ -0,0 +1,106 @@
+Getting and Using Mir  {#getting_and_using_mir}
+=====================
+
+Getting Mir examples
+--------------------
+
+You can install the Mir examples as follows:
+
+    $ sudo apt install mir-demos qterminal
+    $ sudo apt install mir-graphics-drivers-desktop qtubuntu-desktop
+
+Using Mir examples
+------------------
+
+For convenient testing there's a "miral-app" script that wraps the commands used
+to start a server and then launches a terminal (as the current user):
+
+    $ miral-app
+
+To run independently of X11 you need to grant access to the graphics hardware
+(by running as root) and specify a VT to run in. There's a "miral-desktop"
+script that wraps to start the server (as root) and then launch a terminal
+(as the current user):
+
+    $ miral-desktop
+    
+For more options see *Options when running the Mir example shell* below.
+    
+### Running applications on Mir
+
+If you use the command-line launched by miral-app or miral-desktop native Mir
+applications (which include native Mir clients and those that use SDL or the 
+GTK+, Qt toolkits) can be started as usual:
+
+    $ mir_demo_client_egltriangle
+    $ gedit
+    $ sudo apt install kate neverball 
+    $ kate
+    $ neverball
+
+From outside the MirAL session GTK+, Qt and SDL applications can still be run
+using the miral-run script:
+
+    $ miral-run gedit
+    $ miral-run 7kaa
+
+### Running for X11 applications
+
+If you want to run X11 applications that do not have native Mir support in the
+toolkit they use then the answer is Xmir: an X11 server that runs on Mir. First
+you need Xmir installed:
+
+    $ sudo apt install xmir
+
+Then once you have started a miral shell (as above) you can use miral-xrun to
+run applications under Xmir:
+
+    $ miral-xrun firefox
+
+This automatically starts a Xmir X11 server on a new $DISPLAY for the
+application to use. You can use miral-xrun both from a command-line outside the
+miral-shell or, for example, from the terminal running in the shell.
+
+### Options when running the Mir example shell
+
+#### Script Options
+
+Both the "miral-app" and "miral-desktop" scripts provide options for using an
+alternative example shell (miral-kiosk) and an alternative to gnome-terminal.
+
+    -kiosk               use miral-kiosk instead of miral-shell
+    -launcher <launcher> use <launcher> instead of qterminal
+
+In addition miral-desktop has the option to set the VT that is used:
+
+    -vt       <termid>   set the virtual terminal [4]
+
+There are some additional options (listed with "-h") but those are the important
+ones.
+
+#### miral-shell Options
+
+The scripts can also be used to pass options to Mir: they pass everything on
+the command-line following the first thing they don't understand. These can be
+listed by `miral-shell --help`. Most of these options are inherited from Mir,
+but the following MirAL specific are likely to be of interest:
+
+    --window-management-trace           log trace message
+
+Probably the main use for MirAL is to test window-management (either of a
+toolkit or of a server) and this logs all calls to and from the window 
+management policy. This option is supported directly in the MirAL library and
+works for any MirAL based shell - even one you write yourself.
+
+    --keymap arg (=us)                  keymap <layout>[+<variant>[+<options>]]
+                                        , e,g, "gb" or "cz+qwerty" or 
+                                        "de++compose:caps"
+
+For those of us not in the USA this is very useful. Both the -shell and -kiosk
+examples support this option.
+
+    --window-manager arg (=floating)   window management strategy 
+                                       [{floating|tiling|system-compositor}]
+
+Is only supported by miral-shell and its main use is to allow an alternative
+"tiling" window manager to be selected.

=== added file 'doc/getting_involved_in_mir.md'
--- doc/getting_involved_in_mir.md	1970-01-01 00:00:00 +0000
+++ doc/getting_involved_in_mir.md	2017-09-07 10:01:02 +0000
@@ -0,0 +1,106 @@
+Getting Involved in Mir  {#getting_involved_in_mir}
+=======================
+
+Getting involved
+----------------
+
+The best place to ask questions and discuss about the Mir project is
+the \#ubuntu-mir IRC channel on freenode.
+
+The Mir project is hosted on Launchpad: https://launchpad.net/mir
+
+Building Mir
+------------
+
+These instructions assume that you’re using Ubuntu 16.04LTS or later, I’ve not
+earlier Ubuntu versions or other distributions.
+
+You’ll need a few development and utility packages installed, along with the
+Mir graphics drivers:
+
+    $ sudo apt install devscripts equivs bzr
+    $ sudo apt install mir-graphics-drivers-desktop
+
+If you’re working on a phone or tablet use mir-graphics-drivers-android in
+place of mir-graphics-drivers-desktop. (See \ref building_source_for_arm for
+more on this.)
+
+With these installed you can checkout and build Mir:
+
+    $ bzr branch lp:mir
+    $ sudo mk-build-deps -i
+    $ mkdir mir/build
+    $ cd  mir/build
+    $ cmake ..
+    $ make
+
+This creates an example shell (miral-shell) in the bin directory. This can be
+run directly:
+
+    $ bin/miral-shell
+
+With the default options this runs in a window on X (which is convenient for
+development).
+
+The miral-shell example is simple, don’t expect to see a sophisticated launcher
+by default. You can start mir apps from the command-line. For example:
+
+    $ bin/miral-run gnome-terminal
+
+That’s right, a lot of standard GTK+ applications will “just work” (the GDK
+toolkit has a Mir backend). Any that assume the existence of an X11 and bypass
+the toolkit my making X11 protocol calls will have problems though.
+
+To exit from miral-shell press Ctrl-Alt-BkSp.
+
+You can install the Mir examples, headers and libraries you've built with:
+  
+    $ sudo make install
+
+### Preparing a VM to run Mir
+
+Especially if you want to debug the shell without locking your system this might be a helpful setup:
+
+- \ref setup_kvm_for_mir
+- \ref setup_vmware_for_mir
+
+### Contributing to Mir
+
+Currently, the Mir code activity is performed on a development branch:
+lp:~mir-team/mir/development-branch
+
+This development branch is promoted to the branch used for the ubuntu archive
+and touch images. Please submit any merge proposals against the development
+branch.
+
+Please file bug reports at: https://bugs.launchpad.net/mir
+
+The Mir development mailing list can be found at: https://lists.ubuntu.com/mailman/listinfo/Mir-devel
+
+The Mir coding guidelines are [here](cppguide/index.html).
+
+### Working on Mir code
+
+ - \ref md_README  "Mir Read me"
+ - \ref md_HACKING "Mir hacking guide"
+ - \ref component_reports
+ - \ref dso_versioning_guide
+ - \ref abi_compatibility_tools
+ - \ref performance_framework
+ - \ref latency "Measuring visual latency"
+
+Building Mesa
+-------------
+
+*The Mesa packages shipped with Ubuntu are already built with the relevant Mir patches
+and should work out of the box with Mir.*
+
+For GL accelerated clients to use Mir they need to use a patched version of Mesa
+that supports Mir.
+
+The patch is hosted on GitHub:
+
+    $ git clone https://github.com/RAOF/mesa.git
+
+Compile as per normal instructions and pass --with-egl-platforms="mir,drm" to
+the configure options. You will need libmirclient installed as shown above.

=== removed file 'doc/installing_prebuilt_on_pc.md'
--- doc/installing_prebuilt_on_pc.md	2016-01-29 08:18:22 +0000
+++ doc/installing_prebuilt_on_pc.md	1970-01-01 00:00:00 +0000
@@ -1,8 +0,0 @@
-Installing pre-built packages on a PC {#installing_prebuilt_on_pc}
-=====================================
-
-Install Ubuntu 13.10 or later if you haven't done so already.  Uninstall any
-proprietary drivers (-nvidia, -fglrx) and reboot on the FOSS drivers.
-
-       sudo apt-get update
-       sudo apt-get install mir-demos

=== 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	2017-09-07 10:01:02 +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 FloatingWindowManagerPolicy, 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: 
+FloatingWindowManagerPolicy 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	2017-09-06 11:04:56 +0000
+++ doc/mainpage.md	2017-09-07 10:01:02 +0000
@@ -3,103 +3,48 @@
 
 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).
+ranging from Linux desktop to mobile and IoT devices powered by Ubuntu.
+
+ - If you just want to try out the Mir demos, see: \ref getting_and_using_mir
+
+ - If you want to get involved in Mir development, see: \ref getting_involved_in_mir
+
+Using Mir for client development
+--------------------------------
+
+Install the headers and libraries for using libmirclient in development:
+
+    $ sudo apt install libmirclient-dev
+
+A `miral.pc` file is provided for use with `pkg-config` or other tools. For
+example:
+
+    $ pkg-config --cflags mirclient
+
+The client API documentation is here: \ref mir_toolkit
+
+Using Mir for server development
+--------------------------------
+
+Install the headers and libraries for using libmiral in development:
+
+    $ sudo apt install libmirserver-dev
+
+A `miral.pc` file is provided for use with `pkg-config` or other tools. For
+example: 
+
+    $ pkg-config --cflags miral
+
+The server API is introduced here: \ref introducing_the_miral_api
+
+The Mir Documentation
+---------------------
+
+The Mir documentation can be installed and read like this:
+
+    $ sudo apt install mir-doc
+    $ xdg-open /usr/share/doc/mir-doc/html/index.html
 
 More detailed information about the motivation, scope, and high-level design
 of Mir can be found at http://wiki.ubuntu.com/MirSpec .
 
-Getting and installing Mir
---------------------------
-
-### Using pre-built packages
-
-If you just want to try out mir, or write client applications, then the easiest
-way is to use the pre-built packages:
-
- - \ref installing_prebuilt_on_pc
-
-### Building and installing from source
-
-If you are curious about Mir internals or intend to contribute to it, you should
-get the source and build it:
-
- - \ref building_source_for_pc
- - \ref building_source_for_arm
-
-### Preparing a VM to run Mir
-
-Especially if you want to debug the shell without locking your system this might be a helpful setup:
-
-- \ref setup_kvm_for_mir
-- \ref setup_vmware_for_mir
-
-Using Mir
----------
-
- - \ref using_mir_on_pc
- - \ref demo_server
-
-Getting involved
-----------------
-
-The best place to ask questions and discuss about the Mir project is
-the \#ubuntu-mir IRC channel on freenode.
-
-The Mir project is hosted on Launchpad: https://launchpad.net/mir
-
-Currently, the Mir code activity is performed on a development branch:
-lp:~mir-team/mir/development-branch
-
-Approximately fortnightly, this development branch is promoted to the branch
-used for the ubuntu archive and touch images. Please submit any merge proposals 
-against the development branch.
-
-Please file bug reports at: https://bugs.launchpad.net/mir
-
-The Mir development mailing list can be found at: https://lists.ubuntu.com/mailman/listinfo/Mir-devel
-
-The Mir coding guidelines are [here](cppguide/index.html).
-
-Writing client applications
----------------------------
-
- - \ref mir_toolkit "Mir API Documentation"
- - \subpage basic.c "basic.c: A basic Mir client (which does nothing)"
-
-Writing server applications
----------------------------
-
-Mir server is written as a library which allows the server code to be adapted
-for bespoke applications.
-
- - \subpage server_example.cpp 
-   "server_example.cpp: a test executable hosting the following"
- - \subpage server_example_input_event_filter.cpp 
-   "server_example_input_event_filter.cpp: provide a Quit command"
- - \subpage server_example_display_configuration_policy.cpp 
-   "server_example_display_configuration_policy.cpp: configuring display layout"
- - \subpage server_example_input_filter.cpp 
-   "server_example_input_filter.cpp: print input events to stdout"
- - \subpage server_example_log_options.cpp 
-   "server_example_log_options.cpp: replace Mir logger with glog"
- - \subpage server_example_basic_window_manager.h 
-   "server_example_basic_window_manager.h: How to wire up a window manager"
- - \subpage server_example_window_management.cpp 
-   "server_example_window_management.cpp: simple window management examples"
- - \subpage server_example_canonical_window_manager.cpp 
-   "server_example_canonical_window_manager.cpp: canonical window management policy"
- - \subpage server_example_custom_compositor.cpp 
-   "server_example_custom_compositor.cpp: demonstrate writing an alternative GL rendering code"
-
-Working on Mir code
--------------------
-
- - \ref md_README  "Mir Read me"
- - \ref md_HACKING "Mir hacking guide"
- - \ref component_reports
- - \ref dso_versioning_guide
- - \ref abi_compatibility_tools
- - \ref performance_framework
- - \ref latency "Measuring visual latency"

=== removed file 'doc/using_mir_on_pc.md'
--- doc/using_mir_on_pc.md	2016-01-29 08:18:22 +0000
+++ doc/using_mir_on_pc.md	1970-01-01 00:00:00 +0000
@@ -1,91 +0,0 @@
-Using Mir on a PC {#using_mir_on_pc}
-=================
-
-Before you begin
-----------------
-
-Make sure your hardware is supported. That means you're using a Mesa driver,
-of which intel, radeon, and nouveau families are supported. If you're logged
-in to X then run this command to verify an appropriate DRI driver is active:
-
-    sudo pmap `pidof X` | grep dri.so
-
-or
-
-    lsmod | grep drm
-
-Before you can use Mir you need to ensure you have the proper custom Mesa
-build installed. If you are running Ubuntu 13.10 or later
-(see \ref installing_prebuilt_on_pc), you should be good to go.
-
-If you built Mir from source code (see \ref building_source_for_pc), you
-need to ensure you are using the proper Mesa at runtime. You can do that by
-installing the Mesa packages from Ubuntu 13.10 (or later) or by building the
-custom Mesa yourself and ensuring it can be found by Mir, e.g., by using
-`LD_LIBRARY_PATH`.
-
-### Getting some example client applications
-
-You can get some example programs by installing the `mir-demos` package:
-
-    $ sudo apt-get install mir-demos
-
-If you are building from source you can find client applications in the `bin/`
-subdirectory of the build directory.
-
-Running Mir
------------
-
-Mir can run run either natively on mesa-kms or as an X application.
-
-### Running Mir on X
-
-To run Mir as an X client start it from an X terminal:
-
-    $ mir_demo_server --launch-client mir_demo_client_multiwin
-    
-You can start additional Mir clients, for example (in a new terminal):
-
-    $ mir_demo_egltriangle
-    
-To exit from Mir:
- 
-    <Ctrl+Alt+BkSp>
-    
-Note: up to Mir 0.18 it is also necessary to specify `--platform-input-lib` when
-starting the server:
-  - for Mir-0.17 add: `--platform-input-lib server-mesa-x11.so.6`
-  - for Mir-0.18 add: `--platform-input-lib server-mesa-x11.so.7`
-
-### Running Mir natively
-
-To run Mir natively on a PC/desktop/laptop:
-
-    $ sudo DISPLAY= mir_demo_server --vt 1 --arw-file
-    
-This will switch you to a Mir session on VT1. Switch back to your X-based 
-desktop:
-
-    <Ctrl+Alt+F7>
-    
-In a new terminal:
-
-    $ mir_demo_client_multiwin -m /tmp/mir_socket
-    
-Switch back to Mir.
-
-    <Ctrl+Alt+F1>
-    
-Watch your friends be amazed!
-
-To exit from Mir:
-
-    <Ctrl+Alt+BkSp>
-
-In case you accidentally killed your X login and ended up with a failsafe
-screen, you might find on subsequent reboots you can't log in to X at all any
-more (it instantly and silently takes you back to the login screen).  The fix
-for this is to log in to a VT and:
-
-    $ rm .Xauthority
-    $ sudo restart lightdm