Tutorial review

doc/sphinx/tutorial/getting-started-with-mir.md

@@ -0,0 +1,129 @@
+# Getting started with Mir
+
+This tutorial will guide you through Mir's basic functionality. 
+
+By the end of the tutorial, you will install and run a demo application, learn how to use Mir in different environments, and learn about features that Mir provides for Mir-based compositors. 
+
+If you are unfamiliar with Mir, start with this tutorial, and then proceed to a [developer tutorial](write-your-first-wayland-compositor) which will guide you through the process of writing a compositor.
+
+
+## Installing demo applications
+Mir demos are available on Debian derivatives, Fedora, and Alpine. For distros
+that don't have pre-built binaries, examples can be built from source.
+
+### On Debian and its derivatives
+
+```sh
+sudo apt install mir-demos mir-graphics-drivers-desktop
+```
+
+### On Fedora
+```sh
+sudo dnf install mir-demos
+```
+
+### On Alpine
+```sh
+sudo apk add mir-demos mir
+```
+
+## Running applications on X11 or Wayland
+
+We'll work with `miral-app`, a script that handles running a Mir shell with a basic GUI.
+
+Mir allows you to run a graphical shell in *desktop mode* or in *kiosk mode*.
+
+Desktop mode means that application windows that are opened are floating, you can move them around the screen, maximize, or minimize them.
+Kiosk mode means that the application is opened in fullscreen mode. You are unable to move or resize it.
+
+To run the script in desktop mode:
+```sh
+miral-app
+```
+
+To run the script in kiosk mode:
+```sh
+miral-app -kiosk
+```
+
+## Running shells natively
+
+Mir compositors support running "natively" by launching them from a virtual terminal or a login screen.
+
+### Launching from a virtual terminal
+
+1. Switch to a virtual terminal by pressing CTRL+ALT+F\<Number\> and log in.
+
+2. Run the script:
+```sh
+miral-app
+```
+
+### Launching from a login screen
+
+Open the window manager list, choose **Mir Shell**, log in, and `miral-shell` will be running fullscreen.
+
+## Using on-screen keyboards
+Mir-based compositors support on-screen keyboards. 
+
+**Note**: Due to security reasons, some Wayland extensions needed by on-screen keyboards are disabled by default. In this tutorial, we override this setting by passing `--add-wayland-extensions all` when launching `miral-app`.
+passing a `--add-wayland-extensions all` flag when launching an example application.
+
+You can use any Wayland compatible on-screen keyboard but as an example, we'll use `ubuntu-frame-osk`. 
+
+1. Install `ubuntu-frame-osk`:
+```sh
+sudo snap install ubuntu-frame-osk
+sudo snap connect ubuntu-frame-osk:wayland
+```
+
+2. Start `miral-app`:
+```sh
+miral-app --add-wayland-extensions all
+```
+
+3. Once the shell loads, start the terminal (with `Ctrl-Alt-Shift-T`) and start your on-screen keyboard:
+```sh
+ubuntu-frame-osk&
+```
+An on-screen keyboard will pop up.
+
+
+## Mixing Wayland and X11 clients
+
+You can run X11 applications inside Mir-based compositors. As an example, let's run `xclock` - an X11 application that displays the time.
+
+1. Enable X11 support in `miral-shell`:
+```sh
+miral-app --enable-x11 true
+```
+
+2. Once the shell loads, run `xclock`:
+```sh
+xclock
+``` 
+A window with a clock will pop up.
+
+## Remote desktop
+Mir supports remote desktops via the VNC protocol. To demo this, you'll use `wayvnc` - a VNC server. 
+
+1. Install `wayvnc`:
+
+```sh
+sudo apt install wayvnc
+```
+
+2. Install your preferred [VNC client](https://help.ubuntu.com/community/VNC/Clients). 
+
+3. Start the shell with all extensions enabled:
+```sh
+miral-app --add-wayland-extensions all
+```
+
+4. In the shell, open the terminal and run `wayvnc`:
+```sh
+wayvnc
+```
+A `wayvnc` server will start and will listen to `localhost`. 
+
+5. Run your VNC client and connect to `localhost`. You will see the exact same view in both the Mir compositor and the VNC viewer. 

doc/sphinx/tutorial/index.md

@@ -1,12 +1,12 @@
 # Tutorials
 These pages provide first-time introductions to key Mir aspects
 
-- [Learn What Mir Can Do](/tutorial/learn-what-mir-can-do): A showcase of Mir's capabilities
+- [Getting started with Mir](/tutorial/getting-started-with-mir): A showcase of Mir's capabilities
 - [Write Your First Wayland Compositor](/tutorial/write-your-first-wayland-compositor): A guide through writing a simple compositor
 
 ```{toctree}
 :hidden:
 
-/tutorial/learn-what-mir-can-do
+/tutorial/getting-started-with-mir
 /tutorial/write-your-first-wayland-compositor
 ```