From: Michael Stapelberg <michael@stapelberg.de>
Date: Sun, 23 Jun 2013 19:52:13 +0000 (+0200)
Subject: userguide: improve the shmlog docs
X-Git-Tag: 4.6~20
X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=71dfcbc674a873038666147e5252375e44fc9100;p=i3%2Fi3

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 73187fa7..60345bec 100644
--- 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