From 2df13933cac3574af2e1a040d2cc495bffb62ea7 Mon Sep 17 00:00:00 2001
From: Johan Malm <jgm323@gmail.com>
Date: Wed, 10 May 2023 21:15:11 +0100
Subject: [PATCH] labwc-config(5): describe element/attribute-agnostic XML
 parsing

---
 docs/labwc-config.5.scd | 57 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 52 insertions(+), 5 deletions(-)

diff --git a/docs/labwc-config.5.scd b/docs/labwc-config.5.scd
index 9539fdd7..730af280 100644
--- a/docs/labwc-config.5.scd
+++ b/docs/labwc-config.5.scd
@@ -4,7 +4,7 @@ labwc-config(5)
 
 labwc - configuration files
 
-# CONFIGURATION
+# DESCRIPTION
 
 Labwc uses openbox-3.6 specification for configuration and theming, but does not
 support all options. The following files form the basis of the labwc
@@ -41,8 +41,15 @@ but the remainder of the theme specification and associated files are described
 in labwc-theme(5).
 
 *rc.xml* is the main configuration file and all its options are described in
-detail below. Configuration must be wrapped in a <labwc_config> root-element,
-like this:
+detail below.
+
+# CONFIGURATION
+
+This section describes *rc.xml* configuration options.
+
+## SYNTAX
+
+Configuration must be wrapped in a <labwc_config> root-element like this:
 
 ```
 <?xml version="1.0"?>
@@ -50,14 +57,54 @@ like this:
 
 <!-- settings -->
 
-
 </labwc_config>
 ```
 
-The rest of this man page describes configuration options.
+*labwc* parses XML in an element/attribute agnostic way. This is a design
+decision to increase config file flexibility and keep code simple. In practical
+terms, this means that `<a><b>c</b></a>` is equivalent to `<a b="c" />`.
+
+The following three are therefore treated the same:
+
+```
+<action>
+  <name>Execute</name>
+  <command>foot</command>
+</action>
+```
+
+```
+<action name="Execute">
+  <command>foot</command>
+</action>
+```
+
+```
+<action name="Execute" command="foot" />
+```
+
+The benefit of the final one is brevity whereas the advantage of the first two
+is that you can add ' and " within the `<command>` block, for example:
+
+```
+<command>sh -c 'grim -g "`slurp`"'</command>
+```
+
+Elements at the same level can have the same name whereas attributes cannot.
+Therefore, where multiple objects of the same kind are required (for example
+*<action>* and *<keybind>*) the top-node of the object has to be an element.
 
 ## CORE
 
+```
+<core>
+  <decoration>server</decoration>
+  <gap>0</gap>
+  <adaptiveSync>no</adaptiveSync>
+  <reuseOutputMode>no</reuseOutputMode>
+</core>
+```
+
 *<core><decoration>* [server|client]
 	Specify server or client side decorations for xdg-shell views. Note
 	that it is not always possible to turn off client side decorations.