labwc-config(5): clarify applicability of element/attribute (#1655)

Co-authored-by: Andrew J. Hesford <ajh@sideband.org>

diff --git a/docs/labwc-config.5.scd b/docs/labwc-config.5.scd
index 614821a6ef4e1054b6229b4b737c416476b7ddf3..c163bafbb2fc7980f548056901311caa3397cd62 100644 (file)
--- a/docs/labwc-config.5.scd
+++ b/docs/labwc-config.5.scd
@@ -98,7 +98,26 @@ Configuration must be wrapped in a <labwc_config> root-element like this:
 
 *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" />`.
+terms, this means that `<a><b>c</b></a>` is usually equivalent to `<a b="c" />`.
+However, there are some caveats:
+
+       1. In menu.xml, the attributes *id*, *label* and *execute* must be
+       expressed as attributes rather than as separate child elements.
+
+       2. Ordering of attributes can sometimes be singificant. For example,
+       when setting fonts via attributes rather than children,
+
+               *<font place="ActiveWindow" name="..." size="..." />*
+
+       will set a font for active window titles, while
+
+               *<font name="..." size="..." place="ActiveWindow" />*
+
+       will set a font as if *place* were unspecified, because *name* and
+       *size* will be processed before *place*.
+
+In general, it is recommended that attributes not be used to collapse more than
+one level of the configuration hierarchy.
 
 The following three are therefore treated the same: