docs: update the tutorial to include less unnecessary cruft for newco…

…mers (#3465)

## What's new?
- Reorganized Mir's main tutorial to divide the line between "installing
the library" and "installing + running demos" to be more readable
- Removed some sections that I consider to be superfluous and just
confuse a first-time reader

doc/sphinx/tutorial.md

@@ -3,86 +3,100 @@ discourse: 4911,5164,5603,6756,8037
 ---
 
 # Tutorial
+This tutorial will instruct you on how to get started building your first
+Wayland compositor with Mir. Additionally, we will provide information on how
+to install some demo compositors that will give you a sense of what you can
+build with Mir.
 
-Mir is a library for building things, not an end-user product, but it does come
-with some demos to illustrate the possibilities.
-
-## Getting Mir demos
-
-The Mir libraries and demos are available on Ubuntu, Fedora and Arch. It has
-also been built and tested on Debian but, at the time or writing, is not in the
-archive.
-
-For Linux distributions that don't currently package Mir you need to build it
-yourself. (See [Getting Involved in Mir](how-to/getting_involved_in_mir)).
-
-## Getting Mir on Ubuntu
-
-You can install the Mir examples along with the Mir graphics drivers as follows:
-
-    sudo apt install mir-demos mir-graphics-drivers-desktop
-
-It is also useful to install Wayland support for Qt and qterminal:
-
-    sudo apt install qterminal qtwayland5
-
-### Getting the latest Mir release on Ubuntu
+## Installing Mir Libraries
+The Mir libraries and demos are available on Ubuntu, Fedora, Debian and Arch.
 
+### Installing Mir on Ubuntu
 As a matter of policy Ubuntu does not routinely update packages after a series
 is released. This means the Mir team cannot reasonably guarantee that all series
 will have the latest Mir release available at all times.
 
 The latest Mir release is available for all supported Ubuntu series from the
 Mir team's "release PPA". To add the PPA to your system:
 
-    sudo add-apt-repository --update ppa:mir-team/release
+```sh
+sudo add-apt-repository --update ppa:mir-team/release
+```
+
+Afterwards, you will be able to install any of the libraries that are published
+by the project. The library that one might be interested in as a compositor author
+is `libmiral`. To install it, you may run:
+
+
+```sh
+sudo apt install libmiral7 libmiral-dev mir-graphics-drivers-desktop
+```
 
 To remove the PPA from your system:
 
-    sudo ppa-purge mir-team/release
+```sh
+sudo ppa-purge mir-team/release
+```
 
-## Getting Mir on Fedora
+### Installing Mir on Fedora
 
-On Fedora Mir is available from the archive:
+On Fedora, Mir is available from the archive:
 
-    sudo dnf install mir-demos
+```sh
+sudo dnf install mir-devel mir-server-libs
+```
 
-It is also useful to install qterminal:
+### Installing Mir on Debian
+On Debian, Mir is available as `mir` (https://tracker.debian.org/pkg/mir):
 
-    sudo dnf install qterminal
+```
+sudo apt install mir
+```
 
-## Getting Mir on Arch
 
-On Arch Linux, you can install the [mir](https://aur.archlinux.org/packages/mir/) package from the AUR.
+### Installing Mir on Arch
 
-## Using Mir demos
+On Arch Linux, you can install the [mir](https://aur.archlinux.org/packages/mir/) package from the AUR.
 
-For convenient testing under X11 there's a "miral-app" script that wraps the
-commands used to start a server and then launches a terminal (as the current
-user):
+## Installing and Running Demo Compositors
+Mir provides a number of few example compositors in the
+[examples folder](https://github.com/canonical/mir/tree/main/examples) of the Mir project.
+Each folder in the "examples" folder is an independent Wayland compositor.
 
-    miral-app
+### Installing demos on Ubuntu
 
-If you're using a desktop that supports X11 then you can run this in a terminal
-window. In that case Mir will automatically select a "Mir-on-X11" backend and
-run in a Window.
+```sh
+sudo apt install mir-demos mir-graphics-drivers-desktop
+```
 
-Alternatively, to run Mir "natively" you can run the same command in a Virtual
-Terminal.
+### Installing Mir demos manually
+For Linux distributions that don't currently package Mir you need to build it
+yourself. (See [Getting Involved in Mir](how-to/getting_involved_in_mir)).
 
-### Running applications on Mir
+### Running Mir demos
+The main mir demo that you might be interested in is `miral-app`, which provides
+access to a number of different window manager demos depending on which arguments
+are provided to it. By default, it runs `miral-shell`, which is a floating window manager
+with  pleasant startup screen. To run the demos, you can  simply run `miral-app`
+from a terminal in your current session (e.g. a gnome-shell session):
 
-If you use the terminal launched by `miral-app` Wayland applications can be
-started as usual:
+```sh
+miral-app
+```
 
-    kate
-    neverputt
-    gedit
+This will open up a new window in your compositor that contains a nested
+"floating window manager" compositor.
+Likewise, you can switch to a different VT (using `Ctrl + Alt + F<NUMBER>`). From
+there, you may log in and run:
 
-### Options when running the Mir example shell
+```sh
+miral-app
+```
 
-#### Script Options
+In both cases, you should see a startup screen with information on how to use the
+compositor. The compositor should behave like a typical floating window manager.
 
+#### Options to `miral-app`
 The `miral-app` script provides options for using an alternative shell
 (e.g. `miral-kiosk` as used by the mir-kiosk snap) and an alternative terminal.
 
@@ -98,32 +112,3 @@ For  example:
 
 There are some additional options (listed with "-h") but those are the important
 ones.
-
-#### `miral-shell` Options
-
-The script will pass everything on the command-line following the first thing it
-doesn't understand to `miral-shell`. The options can be listed by
-`miral-shell --help`. The following are likely to be of interest:
-
-    --window-management-trace           log trace message
-
-Probably the main use for `miral-shell` is to test window-management (either of
-a client 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.
-
-    --window-manager arg (=floating)   window management strategy
-                                       [{floating|tiling|system-compositor}]
-
-This allows an alternative "tiling" window manager to be selected. *Note:
-`--window-manager` is only supported by `miral-shell` (not `miral-kiosk`).*
-
-For  example:
-
-    miral-app --window-manager tiling
-
-These options can also be specified in a configuration file. For example:
-
-    $ cat ~/.config/miral-shell.config
-    keymap=gb
-    window-manager=tiling