getting-started.md: re-write most of the document

Author: johanmalm

src/getting-started.md

@@ -1,152 +1,126 @@
 # Getting Started
 
-Labwc is designed to be easy to get started with.
+## Introduction
 
-To use the compositor for the first time, there is no need for configuration
-files, theme files or even a session file.  It should be enough to simply run
-the labwc binary from a TTY or Wayland/X11 session. 
+If you are coming to labwc for the first time, this is the page to read. Should
+you get stuck, do reach out on the [IRC Channel] or [Github Discussions].
 
-If labwc is not packaged by your OS/distribution of choice, it is quite easy
-to build (which should take no more than a few seconds) and run from the build
-directory.[^1]
-
-[^1]: The compositor works fine without doing a system-wide installation, but
-      just be aware that you will not get localized (translated to local
-      language) window context menus, nor will you get a system-wide .desktop
-      file where most display managers look for them (if you use one of them).
+[IRC Channel]: https://web.libera.chat/gamja/?channels=#labwc
+[Github Discussions]: https://github.com/labwc/labwc/discussions
 
-The first time you run labwc, you'll be greeted by a blank screen. If you click
-on the desktop you will see your root-menu containing 'Reconfigure' and 'Exit'.
-Although this initial appearance is minimalist and sparse, it is easy to get
-started.
+## Context
 
-Before doing any configuration, you can start labwc with the following command
-to start an application (alacritty is used in the example, but it could of
-course be any application):
+Labwc is a system level software component for which the entry barrier is
+higher compared with that of many user applications. It can be perceived as
+difficult to set up due to the need for manual configuration and because it is
+a base component upon which Desktop Environments can be built which means that
+there are many ways in which it can be used and that work is required to get
+the best out of it. But fret not, with a small amount of work some very
+creative experiences will be opened up that will most likely be worth the
+effort.
 
-```
-labwc -s alacritty
-```
+Pre-configured Desktop Environments exist using `labwc` as the compositor (see
+examples in list below), but in this document you will be guided to start the
+compositor without any such setup.
 
-Alternatively, if you have bemenu installed, you can use the default keybind
-Alt-F3 to launch applications.
+- [Opensuse with Xfce](https://news.opensuse.org/2025/08/04/leap-16-rc/)
+- [Raspberry Pi](https://www.raspberrypi.com/news/a-new-release-of-raspberry-pi-os/)
+- [LXQt](https://lxqt-project.org/screenshots/labwc/)
+- [LXQt on Arch Linux](https://archlinux.org/packages/?name=lxqt-wayland-session)
+- [Mabox](https://forum.maboxlinux.org/t/labwc-in-mabox-status/2138)
+- [Puppy Linux](https://vanilla-dpup.github.io/)
 
-<img src="img/scrot-first-start.png" />
+## Installation
 
-# Configuration
+Install `labwc` with your package manager and come back here when done.
 
-User config files are located at `${XDG_CONFIG_HOME:-$HOME/.config/labwc/}`
-(usually `~/.config/labwc/`) with the following five files being used:
-[rc.xml], [menu.xml], [autostart], [environment] and [themerc-override].
+Also install `alacritty` (a terminal emulator which is available in most
+distros' repositories). There is of course nothing forcing you to use
+`alacritty` but it is likely to be useful the first time the start the
+compositor.
 
-The example [rc.xml] has been kept simple. For all options and default values,
-see [rc.xml.all]
+## Launching
 
-For full details on configuration options, see the man pages: 
-[labwc(1)], [labwc-config(5)], [labwc-theme(5)], [labwc-actions(5)] and
-[labwc-menu(5)].
+Launch labwc by typing `labwc` in your terminal. Some Display Managers (like
+`SDDM` or `GDM`) will show labwc, so you can also start from there.
 
-Run `labwc --reconfigure` to reload configuration and theme files.
+> TECHNICAL NOTE: labwc can be started from a TTY or nested in a Wayland/X11
+> session.
 
-Your OS/Distribution of choice may include these example configuration files in
-`/usr/share/doc/labwc/` or similar. If not, you could download them with:
+If you start `labwc` with no prior configuration you will be greeted by a blank
+screen. If you click on the desktop you will see your root-menu containing only
+'Reconfigure' and 'Exit' (and 'Terminal' from version 0.9.0 onwards). Do not be
+put off by this sparse appearance. There is a lot more to this compositor than
+first meets the eye.
 
-```bash
-mkdir -p ~/.config/labwc
-wget https://raw.githubusercontent.com/labwc/labwc/master/docs/environment -O ~/.config/labwc/environment
-wget https://raw.githubusercontent.com/labwc/labwc/master/docs/autostart -O ~/.config/labwc/autostart
-wget https://raw.githubusercontent.com/labwc/labwc/master/docs/menu.xml -O ~/.config/labwc/menu.xml
-wget https://raw.githubusercontent.com/labwc/labwc/master/docs/rc.xml -O ~/.config/labwc/rc.xml
-```
+You can start a terminal by pressing `Super + Return`.
 
-> **_NOTE:_** Before using these configuration files, please read them through
-> and modify the content to suit your specific needs.
+<img src="img/scrot-first-start.png" />
 
-For more information about each configuration file and to help create a setup
-that work for you, please read through the sections below.
+# Configuration
 
-If you get stuck, do reach out on the [IRC Channel] or [Github Discussions].
+Configuration files are located in `$HOME/.config/labwc/`
 
-[rc.xml]: https://github.com/labwc/labwc/blob/master/docs/rc.xml
-[rc.xml.all]: https://github.com/labwc/labwc/blob/master/docs/rc.xml.all
-[menu.xml]: https://github.com/labwc/labwc/blob/master/docs/menu.xml
-[autostart]: https://github.com/labwc/labwc/blob/master/docs/autostart
-[environment]: https://github.com/labwc/labwc/blob/master/docs/environment
-[themerc-override]: https://github.com/labwc/labwc/blob/master/docs/themerc
-[labwc(1)]: https://labwc.github.io/labwc.1.html
-[labwc-config(5)]: https://labwc.github.io/labwc-config.5.html
-[labwc-menu(5)]: https://labwc.github.io/labwc-menu.5.html
-[labwc-environment(5)]: https://labwc.github.io/labwc-environment.5.html
-[labwc-theme(5)]: https://labwc.github.io/labwc-theme.5.html
-[labwc-actions(5)]: https://labwc.github.io/labwc-actions.5.html
-[IRC Channel]: https://web.libera.chat/gamja/?channels=#labwc
-[Github Discussions]: https://github.com/labwc/labwc/discussions
+In this guide we are going to cover some common setup steps which will give you
+a good feel for the four most important configuration files which are:
+[environment], [rc.xml], [autostart] and [menu.xml].
 
-## Step 1 - Set your keyboard layout
+Whenever a configuration or theme file has been changed, the command `labwc
+--reconfigure` has be run for the settings to take affect. With additions to
+`autostart` you will need to re-start the compositor.
 
-Set the environment variable `XKB_DEFAULT_LAYOUT` with your country code.
+It is generally recommended not to copy the example configuration files, but to
+build them from scratch.
 
-For example to start with Swedish keyboard layout, run
+## Step 1 - Set your keyboard layout
 
-```
-XKB_DEFAULT_LAYOUT=se labwc
-```
+Set the environment variable `XKB_DEFAULT_LAYOUT` with your country code in
+`~/.config/labwc/environment`.
 
-Or simply add this line to `~/.config/labwc/environment`
+For example to use a Swedish keyboard layout, add this line:
 
 ```
 XKB_DEFAULT_LAYOUT=se
 ```
 
-If you are unsure what your country code is, refer to the 'layout' section of
-`/usr/share/X11/xkb/rules/evdev.lst`
+If you are unsure what your country code is, use the website
+[xkeyboard-config.freedesktop.org] or search the 'layout' section of your
+local copy of `evdev.lst` which is typically located at
+`/usr/share/X11/xkb/rules/evdev.lst`.
 
-See further details, see [docs/environment] and [xkeyboard-config(7)].
+See further details, see [environment] and [xkeyboard-config(7)].
 
+[xkeyboard-config.freedesktop.org]: https://xkeyboard-config.freedesktop.org/layouts/gallery
 [xkeyboard-config(7)]: https://manpages.debian.org/testing/xkb-data/xkeyboard-config.7.en.html
 
-## Step 2 - Add some items to the root-menu
-
-Create a `~/.config/labwc/menu.xml` to hand-craft a menu. See [docs/menu.xml]
-for inspiration, or use the simple example below
-
-```
-<?xml version="1.0" ?>
-
-<openbox_menu>
-<menu id="root-menu" label="">
-  <item label="Web browser"><action name="Execute" command="firefox" /></item>
-  <item label="Terminal"><action name="Execute" command="alacritty" /></item>
-  <item label="Reconfigure"><action name="Reconfigure" /></item>
-  <item label="Exit"><action name="Exit" /></item>
-</menu>
-</openbox_menu>
-```
-
-See [integration#menu-generators] for ideas on how to automatically create
-menu.xml files.
+## Step 2 - Set some keybinds
 
-## Step 3 - Set a shortcut to a launcher
-
-If you want to bind a key-combination to a launcher such as rofi or wofi, or
-simply a terminal, create a configuration file `~/.config/labwc/rc.xml` and add
-a `<keybind>` entry as shown below. In this example `Super-d` is bound to the
-terminal sakura:
+If you want to bind a key-combination to an application like a launcher or
+terminal, create a configuration file `~/.config/labwc/rc.xml` and add a
+`<keyboard>` section as shown below.
 
 ```
 <?xml version="1.0" ?>
 <labwc_config>
-
   <keyboard>
     <default />
-    <keybind key="W-d"><action name="Execute" command="sakura" /></keybind>
-    <keybind key="W-z"><action name="Execute" command="wofi --show drun" /></keybind>
+    <!-- The W- prefix refers to the Super key -->
+    <keybind key="W-d">
+      <action name="Execute" command="sakura" />
+    </keybind>
+    <keybind key="W-z">
+      <action name="Execute" command="wofi --show drun" />
+    </keybind>
   </keyboard>
-
 </labwc_config>
 ```
 
-See [docs/rc.xml.all] for all available configuration options.
+> TECHNICAL NOTE: The `<default/>` element includes all the built-in keybinds
+> as described [here].
+
+[here]: https://labwc.github.io/labwc-config.5.html#entry_keyboard_default
+
+See [rc.xml] for all available configuration options.
 
 To figure out the name of a key, you can use either xev (widely available,
 runs via xwayland) or [wev]. Alternatively, search for keysym names directly in
@@ -155,46 +129,75 @@ runs via xwayland) or [wev]. Alternatively, search for keysym names directly in
 [wev]: https://git.sr.ht/~sircmpwn/wev
 [xkbcommon-keysyms.h]: https://github.com/xkbcommon/libxkbcommon/blob/master/include/xkbcommon/xkbcommon-keysyms.h
 
-## Step 4 - Start a background-image client and a panel
+## Step 3 - Use a wallpaper and a panel
+
+We recommend using `swaybg` for setting a background image or color. You can of
+course run `swaybg` directly from a launcher or panel, but for persistence add
+the example line below to `~/.config/labwc/autostart`
+
+```
+swaybg -c '#334455' &
+```
 
-To use a background-color/image client or a panel, simply add the command
-to `~/.config/labwc/autostart`. See example below for using swaybg and waybar:
+...or for an image try something like this:
 
 ```
-swaybg -i foo.png >/dev/null 2>&1 &
-waybar >/dev/null 2>&1 &
+swaybg -i ~/Pictures/wallpaper.png &
 ```
 
-The `>/dev/null 2>&1` is simply there to hide the logging.
-Don't forget the `&` at the end otherwise the compositor will get stuck on that
-line.
+> IMPORTANT: The `&` at the end is needed to prevent the compositor getting
+> stuck on that line.
+
+There are many widely packaged bars and panels that can be used with `labwc`,
+for example `xfce4-panel`, `lxqt-panel`, `waybar` and `sfwbar`. Just take a
+pick and add one to your `~/.config/labwc/autostart` like this:
+
+```
+xfce4-panel &
+```
 
-See further examples in [docs/autostart]
+See further examples in [autostart]
 
-## Step 5 - install some themes for server-side-decorations
+## Step 4 - Build a root-menu
 
-Some commonly packaged themes support openbox (and therefore labwc) out of the
-box, for example `Numix` and `Adapta`.
+Whether or not you take this step really comes down to how you want to use the
+compositor. For example, if you prefer to use a desktop client like `xfdesktop`
+or `pcmanfm-qt --desktop` which provide their own root menus.
 
-Install a theme and set it in rc.xml:
+To handcraft a menu, create a `~/.config/labwc/menu.xml` and populate with
+your favourite applications as in the example below:
 
 ```
-  <theme>
-    <name>Numix</name>
-  </theme>
+<?xml version="1.0" ?>
+<openbox_menu>
+<menu id="root-menu" label="">
+  <item label="Web browser"><action name="Execute" command="firefox"/></item>
+  <item label="Terminal"><action name="Execute" command="alacritty"/></item>
+  <item label="Reconfigure"><action name="Reconfigure"/></item>
+  <item label="Exit"><action name="Exit"/></item>
+</menu>
+</openbox_menu>
 ```
 
-To just use the current GTK theme, you can use [labwc-gtktheme]
+A lot can be done with the compositor menu. See [integration#menu-generators]
+and [menu.xml] for ideas on how to automatically create menu.xml files as well
+as creating pipemenus.
 
 Refer to the [man pages] for full documentation.
 
 Enjoy!
 
+[labwc(1)]: https://labwc.github.io/labwc.1.html
+[labwc-config(5)]: https://labwc.github.io/labwc-config.5.html
+[labwc-menu(5)]: https://labwc.github.io/labwc-menu.5.html
+[labwc-environment(5)]: https://labwc.github.io/labwc-environment.5.html
+[labwc-theme(5)]: https://labwc.github.io/labwc-theme.5.html
+[labwc-actions(5)]: https://labwc.github.io/labwc-actions.5.html
+
+[environment]: https://github.com/labwc/labwc/blob/master/docs/environment
+[rc.xml]: https://github.com/labwc/labwc/blob/master/docs/rc.xml.all
+[autostart]: https://github.com/labwc/labwc/blob/master/docs/autostart
+[menu.xml]: https://github.com/labwc/labwc/blob/master/docs/menu.xml
 
-[docs/environment]: https://github.com/labwc/labwc/blob/master/docs/environment
-[docs/menu.xml]: https://github.com/labwc/labwc/blob/master/docs/menu.xml
 [integration#menu-generators]: https://labwc.github.io/integration.html#menu-generators
-[docs/rc.xml.all]: https://github.com/labwc/labwc/blob/master/docs/rc.xml.all
-[docs/autostart]: https://github.com/labwc/labwc/blob/master/docs/autostart
-[labwc-gtktheme]: https://github.com/johanmalm/labwc-gtktheme
 [man pages]: manual.html