userguide: improve the shmlog docs

• the section heading needs === instead of ==
• better title
• explain what shared memory logging does and where to find more
  information
• add syntax section
• improve examples
• clarify that shmlog <size> discards the current log

diff --git a/docs/userguide b/docs/userguide
index 73187fa74fe29090425c68bfc87c9110b8e2c3ae..60345bec286d2427c1679e9c1966a93e197135e3 100644 (file)
--- a/docs/userguide
+++ b/docs/userguide
@@ -1762,20 +1762,29 @@ stack-limit rows 5
 image:stacklimit.png[Container limited to two columns]
 ///////////////////////////////////////////////////////////////////////////////
 
-== Starting/stopping/changing the size of the shm log
+=== Enabling shared memory logging
 
-You may start or stop the shm log with +shmlog+, or change the size of the log.
-If you pass a size to the shmlog command, it will change the running log's
-size, or, if the log is not running, start the log with the provided size. You
-may also toggle the log. This is useful if you want to bind the command to a
-key.
+As described in http://i3wm.org/docs/debugging.html, i3 can log to a shared
+memory buffer, which you can dump using +i3-dump-log+. The +shmlog+ command
+allows you to enable or disable the shared memory logging at runtime.
+
+Note that when using +shmlog <size_in_bytes>+, the current log will be
+discarded and a new one will be started.
+
+*Syntax*:
+------------------------------
+shmlog <size_in_bytes>
+shmlog <on|off|toggle>
+------------------------------
 
 *Examples*:
 ---------------
-shmlog 26214400
-shmlog toggle
-shmlog on
-shmlog off
+# Enable/disable logging
+bindsym $mod+x shmlog toggle
+
+# or, from a terminal:
+# increase the shared memory log buffer to 50 MiB
+i3-msg shmlog $((50*1024*1024))
 ---------------
 
 === Reloading/Restarting/Exiting