update docs/debugging from git

diff --git a/_docs/debugging b/_docs/debugging
index b258789d1a14d00954e9c71eb6a731615123d4f4..9dec3056ec0643b7b8b0c0eb32a0d0bd35037ded 100644 (file)
--- a/_docs/debugging
+++ b/_docs/debugging
@@ -1,7 +1,7 @@
 Debugging i3: How To
 ====================
 Michael Stapelberg <michael@i3wm.org>
 Debugging i3: How To
 ====================
 Michael Stapelberg <michael@i3wm.org>

-December 2012
+January 2014

 
 This document describes how to debug i3 to send us useful bug
 reports, even if you have no knowledge of C programming.
 
 This document describes how to debug i3 to send us useful bug
 reports, even if you have no knowledge of C programming.


@@ -10,26 +10,29 @@ Thank you for being interested in debugging i3. It really means
 something to us to get your bug fixed. If you have any questions about the
 process and/or need further help, do not hesitate to contact us!
 
 something to us to get your bug fixed. If you have any questions about the
 process and/or need further help, do not hesitate to contact us!
 

-== Verify you are using the latest (development) version
+== Verify you are using i3 ≥ 4.7

 
 

-Please verify that you are using the latest version of i3:
+Only the latest major version of i3 is supported, i.e. version 4.7 currently.
+To verify which version you are running, use:

 
 ---------------
 
 ---------------

-$ i3 --version
-i3 version 4.1.2-248-g51728ba (2012-02-12, branch "next")
+$ i3 --moreversion 2>&- || i3 --version
+Binary i3 version:  4.7 (2013-12-22, branch "tags/4.7")
+Running i3 version: 4.7-84-gac74a63 (2014-01-01, branch "next") (pid 1995)

 ---------------
 
 Your version can look like this:
 
 ---------------
 
 Your version can look like this:
 

-4.1.2 (release version)::
+4.7 (release version)::

 You are using a release version. In many cases, bugs are already
 You are using a release version. In many cases, bugs are already

-fixed in the development version of i3. If they aren’t, we will still ask you
-to reproduce your error with the most recent development version of i3.
-Therefore, please upgrade to a development version if you can.
-
-4.1.2-248-g51728ba (development version)::
-Your version is 248 commits newer than 4.1.2, and the git revision of your
-version is +51728ba+. Go to http://code.i3wm.org/i3/commit/?h=next and see if
+fixed in the development version of i3. Even if the bug is not a known fixed
+one, we will still ask you to reproduce your error with the most recent
+development version of i3. Therefore, please upgrade to a development version
+if you can.
+
+4.7-85-g9c15b95 (development version)::
+Your version is 85 commits newer than 4.7, and the git revision of your
+version is +9c15b95+. Go to http://code.i3wm.org/i3/commit/?h=next and see if

 the line "commit" starts with the same revision. If so, you are using the
 latest version.
 
 the line "commit" starts with the same revision. If so, you are using the
 latest version.
 


@@ -57,6 +60,13 @@ list of sessions in your desktop manager (gdm, lxdm, …), edit
 Exec=i3 --shmlog-size=26214400
 ------------------------------
 
 Exec=i3 --shmlog-size=26214400
 ------------------------------
 

+If you cannot restart i3 for some reason, you can enable debug logging on the
+fly:
+
+---------------------------------------
+i3-msg 'debuglog on; shmlog on; reload'
+---------------------------------------
+

 == Obtaining the debug logfile
 
 No matter whether i3 misbehaved in some way without crashing or whether it just
 == Obtaining the debug logfile
 
 No matter whether i3 misbehaved in some way without crashing or whether it just


@@ -65,13 +75,16 @@ crashed, the logfile provides all information necessary to debug the problem.
 To save a compressed version of the logfile (suitable for attaching it to a
 bugreport), use:
 --------------------------------------------------------------------
 To save a compressed version of the logfile (suitable for attaching it to a
 bugreport), use:
 --------------------------------------------------------------------

-DISPLAY=:0 i3-dump-log | gzip -9c > /tmp/i3.log.gz
+DISPLAY=:0 i3-dump-log | bzip2 -c > /tmp/i3.log.bz2

 --------------------------------------------------------------------
 
 This command does not depend on i3 (it also works while i3 displays
 the crash dialog), but it requires a working X11 connection.
 
 --------------------------------------------------------------------
 
 This command does not depend on i3 (it also works while i3 displays
 the crash dialog), but it requires a working X11 connection.
 

-== Compiling with debug symbols
+== On crashes: Obtaining a backtrace
+
+When i3 crashes, it will display a dialog stating “i3 just crashed”, offering
+you to save a backtrace to a text file.

 
 To actually get useful backtraces, you should make sure that your version of i3
 is compiled with debug symbols:
 
 To actually get useful backtraces, you should make sure that your version of i3
 is compiled with debug symbols:


@@ -87,8 +100,6 @@ which is stripped, please check whether your distribution provides debug
 symbols (package +i3-wm-dbg+ on Debian for example) or if you can turn off
 stripping. If nothing helps, please build i3 from source.
 
 symbols (package +i3-wm-dbg+ on Debian for example) or if you can turn off
 stripping. If nothing helps, please build i3 from source.
 

-== Obtaining a backtrace
-

 Once you have made sure that your i3 is compiled with debug symbols and the C
 debugger +gdb+ is installed on your machine, you can let i3 generate a
 backtrace in the crash dialog.
 Once you have made sure that your i3 is compiled with debug symbols and the C
 debugger +gdb+ is installed on your machine, you can let i3 generate a
 backtrace in the crash dialog.

diff --git a/docs/debugging.html b/docs/debugging.html
index c60b0faf3bb7a67015e585b98787e2f3279f15a0..e314f0967cab67f6111cbb90dbb88316ed7a6f36 100644 (file)
--- a/docs/debugging.html
+++ b/docs/debugging.html
@@ -31,7 +31,7 @@ window.onload = function(){asciidoc.footnotes();}
 <h1>Debugging i3: How To</h1>\r
 <span id="author">Michael Stapelberg</span><br />\r
 <span id="email"><tt>&lt;<a href="mailto:michael@i3wm.org">michael@i3wm.org</a>&gt;</tt></span><br />\r
 <h1>Debugging i3: How To</h1>\r
 <span id="author">Michael Stapelberg</span><br />\r
 <span id="email"><tt>&lt;<a href="mailto:michael@i3wm.org">michael@i3wm.org</a>&gt;</tt></span><br />\r

-<span id="revdate">December 2012</span>\r
+<span id="revdate">January 2014</span>\r

 </div>\r
 <div id="preamble">\r
 <div class="sectionbody">\r
 </div>\r
 <div id="preamble">\r
 <div class="sectionbody">\r


@@ -43,34 +43,37 @@ process and/or need further help, do not hesitate to contact us!</p></div>
 </div>\r
 </div>\r
 <div class="sect1">\r
 </div>\r
 </div>\r
 <div class="sect1">\r

-<h2 id="_verify_you_are_using_the_latest_development_version">1. Verify you are using the latest (development) version</h2>\r
+<h2 id="_verify_you_are_using_i3_4_7">1. Verify you are using i3 ≥ 4.7</h2>\r

 <div class="sectionbody">\r
 <div class="sectionbody">\r

-<div class="paragraph"><p>Please verify that you are using the latest version of i3:</p></div>\r
+<div class="paragraph"><p>Only the latest major version of i3 is supported, i.e. version 4.7 currently.\r
+To verify which version you are running, use:</p></div>\r

 <div class="listingblock">\r
 <div class="content">\r
 <div class="listingblock">\r
 <div class="content">\r

-<pre><tt>$ i3 --version\r
-i3 version 4.1.2-248-g51728ba (2012-02-12, branch "next")</tt></pre>\r
+<pre><tt>$ i3 --moreversion 2&gt;&amp;- || i3 --version\r
+Binary i3 version:  4.7 (2013-12-22, branch "tags/4.7")\r
+Running i3 version: 4.7-84-gac74a63 (2014-01-01, branch "next") (pid 1995)</tt></pre>\r

 </div></div>\r
 <div class="paragraph"><p>Your version can look like this:</p></div>\r
 <div class="dlist"><dl>\r
 <dt class="hdlist1">\r
 </div></div>\r
 <div class="paragraph"><p>Your version can look like this:</p></div>\r
 <div class="dlist"><dl>\r
 <dt class="hdlist1">\r

-4.1.2 (release version)\r
+4.7 (release version)\r

 </dt>\r
 <dd>\r
 <p>\r
 You are using a release version. In many cases, bugs are already\r
 </dt>\r
 <dd>\r
 <p>\r
 You are using a release version. In many cases, bugs are already\r

-fixed in the development version of i3. If they aren’t, we will still ask you\r
-to reproduce your error with the most recent development version of i3.\r
-Therefore, please upgrade to a development version if you can.\r
+fixed in the development version of i3. Even if the bug is not a known fixed\r
+one, we will still ask you to reproduce your error with the most recent\r
+development version of i3. Therefore, please upgrade to a development version\r
+if you can.\r

 </p>\r
 </dd>\r
 <dt class="hdlist1">\r
 </p>\r
 </dd>\r
 <dt class="hdlist1">\r

-4.1.2-248-g51728ba (development version)\r
+4.7-85-g9c15b95 (development version)\r

 </dt>\r
 <dd>\r
 <p>\r
 </dt>\r
 <dd>\r
 <p>\r

-Your version is 248 commits newer than 4.1.2, and the git revision of your\r
-version is <tt>51728ba</tt>. Go to <a href="http://code.i3wm.org/i3/commit/?h=next">http://code.i3wm.org/i3/commit/?h=next</a> and see if\r
+Your version is 85 commits newer than 4.7, and the git revision of your\r
+version is <tt>9c15b95</tt>. Go to <a href="http://code.i3wm.org/i3/commit/?h=next">http://code.i3wm.org/i3/commit/?h=next</a> and see if\r

 the line "commit" starts with the same revision. If so, you are using the\r
 latest version.\r
 </p>\r
 the line "commit" starts with the same revision. If so, you are using the\r
 latest version.\r
 </p>\r


@@ -99,6 +102,12 @@ list of sessions in your desktop manager (gdm, lxdm, …), edit
 <div class="content">\r
 <pre><tt>Exec=i3 --shmlog-size=26214400</tt></pre>\r
 </div></div>\r
 <div class="content">\r
 <pre><tt>Exec=i3 --shmlog-size=26214400</tt></pre>\r
 </div></div>\r

+<div class="paragraph"><p>If you cannot restart i3 for some reason, you can enable debug logging on the\r
+fly:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>i3-msg 'debuglog on; shmlog on; reload'</tt></pre>\r
+</div></div>\r

 </div>\r
 </div>\r
 <div class="sect1">\r
 </div>\r
 </div>\r
 <div class="sect1">\r


@@ -110,15 +119,17 @@ crashed, the logfile provides all information necessary to debug the problem.</p
 bugreport), use:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
 bugreport), use:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r

-<pre><tt>DISPLAY=:0 i3-dump-log | gzip -9c &gt; /tmp/i3.log.gz</tt></pre>\r
+<pre><tt>DISPLAY=:0 i3-dump-log | bzip2 -c &gt; /tmp/i3.log.bz2</tt></pre>\r

 </div></div>\r
 <div class="paragraph"><p>This command does not depend on i3 (it also works while i3 displays\r
 the crash dialog), but it requires a working X11 connection.</p></div>\r
 </div>\r
 </div>\r
 <div class="sect1">\r
 </div></div>\r
 <div class="paragraph"><p>This command does not depend on i3 (it also works while i3 displays\r
 the crash dialog), but it requires a working X11 connection.</p></div>\r
 </div>\r
 </div>\r
 <div class="sect1">\r

-<h2 id="_compiling_with_debug_symbols">4. Compiling with debug symbols</h2>\r
+<h2 id="_on_crashes_obtaining_a_backtrace">4. On crashes: Obtaining a backtrace</h2>\r

 <div class="sectionbody">\r
 <div class="sectionbody">\r

+<div class="paragraph"><p>When i3 crashes, it will display a dialog stating “i3 just crashed”, offering\r
+you to save a backtrace to a text file.</p></div>\r

 <div class="paragraph"><p>To actually get useful backtraces, you should make sure that your version of i3\r
 is compiled with debug symbols:</p></div>\r
 <div class="listingblock">\r
 <div class="paragraph"><p>To actually get useful backtraces, you should make sure that your version of i3\r
 is compiled with debug symbols:</p></div>\r
 <div class="listingblock">\r


@@ -131,11 +142,6 @@ linked (uses shared libs), for GNU/Linux 2.6.18, not stripped</tt></pre>
 which is stripped, please check whether your distribution provides debug\r
 symbols (package <tt>i3-wm-dbg</tt> on Debian for example) or if you can turn off\r
 stripping. If nothing helps, please build i3 from source.</p></div>\r
 which is stripped, please check whether your distribution provides debug\r
 symbols (package <tt>i3-wm-dbg</tt> on Debian for example) or if you can turn off\r
 stripping. If nothing helps, please build i3 from source.</p></div>\r

-</div>\r
-</div>\r
-<div class="sect1">\r
-<h2 id="_obtaining_a_backtrace">5. Obtaining a backtrace</h2>\r
-<div class="sectionbody">\r

 <div class="paragraph"><p>Once you have made sure that your i3 is compiled with debug symbols and the C\r
 debugger <tt>gdb</tt> is installed on your machine, you can let i3 generate a\r
 backtrace in the crash dialog.</p></div>\r
 <div class="paragraph"><p>Once you have made sure that your i3 is compiled with debug symbols and the C\r
 debugger <tt>gdb</tt> is installed on your machine, you can let i3 generate a\r
 backtrace in the crash dialog.</p></div>\r


@@ -146,7 +152,7 @@ starting at 0.</p></div>
 </div>\r
 </div>\r
 <div class="sect1">\r
 </div>\r
 </div>\r
 <div class="sect1">\r

-<h2 id="_sending_bug_reports_debugging_on_irc">6. Sending bug reports/debugging on IRC</h2>\r
+<h2 id="_sending_bug_reports_debugging_on_irc">5. Sending bug reports/debugging on IRC</h2>\r

 <div class="sectionbody">\r
 <div class="paragraph"><p>When sending bug reports, please attach the <strong>whole</strong> log file. Even if you think\r
 you found the section which clearly highlights the problem, additional\r
 <div class="sectionbody">\r
 <div class="paragraph"><p>When sending bug reports, please attach the <strong>whole</strong> log file. Even if you think\r
 you found the section which clearly highlights the problem, additional\r