Improve documentation for window types and hints

doc/config_settings.yaml

@@ -405,35 +405,68 @@ values:
       - color
   - name: own_window_hints
     desc: |-
-      If own_window is yes, you may specify comma separated window manager hints
-      to affect the way Conky displays. Notes: Use own_window_type desktop
-      as another way to implement many of these hints implicitly. If you use
-      own_window_type override, window manager hints have no meaning and are
-      ignored.
+      If `own_window` is set, on X11 you may specify comma separated window
+      manager hints to affect the way Conky displays.
+
+      Following hints are some of the standard WM specification ones:
+      - `above` indicates that conky should be on top of most windows.
+      - `below` indicates that conky should be below most windows.
+      - `skip_pager` indicates that conky should not be included on a
+        Pager. **Implied if** `own_window_type` is 'dock' or 'panel'.
+      - `skip_taskbar` indicates that conky should not be included on a
+        taskbar. **Implied if** `own_window_type` is 'dock' or 'panel'.
+      - `sticky` indicates that the Window Manager SHOULD keep conky's
+        position fixed on the screen, even when the virtual desktop scrolls.
+      - `undecorated` indicates that conky shouldn't have any window
+        decorations (e.g. title bar). **Implied if** `own_window_type` is
+        'dock' or 'panel'.
+
+      Notes:
+      - Use `own_window_type='desktop'` setting as another way to implement many of these hints implicitly.
+      - If you use `own_window_type='override'`, window manager hints have no meaning and are ignored.
     args:
       - hint(,hint)*
   - name: own_window_title
     desc: |-
-      Manually set the window name.
+      Allows overriding conky window name.
     default: 'conky (<hostname>)'
   - name: own_window_transparent
     desc: |-
-      Boolean, set transparency? If ARGB visual is enabled, sets
-      background opacity to 0%.
+      Make conky window transparent. If `own_window_argb_visual` is enabled,
+      sets background opacity to 0%.
+    default: false
   - name: own_window_type
     desc: |-
-      If own_window is yes, you may specify type normal, desktop, dock, panel,
-      utility or override. Desktop windows are special windows that have no
-      window decorations; are always visible on your desktop; do not appear in
-      your pager or taskbar; and are sticky across all workspaces. Utility
-      windows are like desktop windows, except they appear above everything
-      else rather than below. Panel windows reserve space along a desktop edge,
-      just like panels and taskbars, preventing maximized windows
-      from overlapping them. The edge is chosen based on the alignment
-      option. Override windows are not under the control of the window
-      manager. Hints are ignored. This type of window can be useful for
-      certain situations.
+      If own_window is set, under X11 you can specify type of window conky
+      displayed as:
+
+      - `normal` mode makes conky show as normal window. This mode can be
+        configured with use of `own_window_hints` setting.
+      - `desktop` windows are special windows that have no window decorations,
+        are always visible on the desktop, do not appear in pager or taskbar,
+        and are sticky across all workspaces. Many DEs include `desktop` windows
+        for background, icons and desktop menu, in those cases it might be
+        better to use `normal` or one of the below options, as those will cover
+        conky when they're clicked on.
+      - `dock` windows reserve space on the desktop, i.e. WMs will try their
+        best to not place windows on top of them. They're the same as `desktop`
+        in other respects, but render on top of `desktop` windows.
+      - `panel` windows are similar to `dock` windows, but they also reserve
+        space _along a desktop edge_ (like taskbars), preventing maximized
+        windows from overlapping them. The edge is chosen based on the
+        `alignment` setting.
+      - `utility` windows are persistent utility windows (e.g. a palette or
+        toolbox). They appear on top of other windows (in the same group), but
+        otherwise behave much like `normal` windows.
+      - `override` windows are drawn directly on root window (desktop
+        background) and are not under the control of the window manager. These
+        will not work with DEs which draw desktop icons via custom
+        panels/windows as those will cover conky.
+        `own_window_hints` are ignored for `override` windows.
+
     default: normal
+    args:
+      - (normal|desktop|dock|panel|utility|override)
   - name: pad_percents
     desc: Pad percentages to this many decimals (0 = no padding).
   - name: pop3