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

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.
+As described in http://i3wm.org/docs/debugging.html, i3 can log to a shared
-If you pass a size to the shmlog command, it will change the running log's
+memory buffer, which you can dump using +i3-dump-log+. The +shmlog+ command
-size, or, if the log is not running, start the log with the provided size. You
+allows you to enable or disable the shared memory logging at runtime.
-may also toggle the log. This is useful if you want to bind the command to a
+
-key.
+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
+# Enable/disable logging
-shmlog toggle
+bindsym $mod+x shmlog toggle
-shmlog on
+
-shmlog off
+# or, from a terminal:
+# increase the shared memory log buffer to 50 MiB
+i3-msg shmlog $((50*1024*1024))
 ---------------
 
 === Reloading/Restarting/Exiting