Reorder stacktrace.asciidoc

1 files changed, 60 insertions, 33 deletions

diff --git a/doc/stacktrace.asciidoc b/doc/stacktrace.asciidoc
index 9018f7245..920a4c55d 100644
--- a/doc/stacktrace.asciidoc
+++ b/doc/stacktrace.asciidoc
@@ -1,5 +1,6 @@
 Getting stacktraces on crashes
 ==============================
+:toc:
 The Compiler <mail@qutebrowser.org>
 
 When there is a fatal crash in qutebrowser - most of the times a
@@ -14,10 +15,17 @@ https://en.wikipedia.org/wiki/Debug_symbol[debugging symbols] is required.
 The rest of this guide is quite Linux specific, though there is a
 <<windows,section for Windows>> at the end.
 
+Crashes which can be reproduced
+-------------------------------
+
+If a crash can be reproduced, packages with debugging symbols should be
+installed, and the crash should be reproduced under gdb.
+
 Getting debugging symbols
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.Debian/Ubuntu/...
+Debian/Ubuntu/...
+^^^^^^^^^^^^^^^^^
 
 For Debian based systems (Debian, Ubuntu, Linux Mint, ...), debug information
 is available in the repositories:
@@ -26,13 +34,14 @@ is available in the repositories:
 # apt-get install python3-pyqt5-dbg python3-pyqt5.qtwebkit-dbg python3-dbg libqt5webkit5-dbg
 ----
 
-.Archlinux
+Archlinux
+^^^^^^^^^
 
 For Archlinux, no debug informations are provided. You can either compile Qt
 yourself (which will take a few hours even on a modern machine) or use
 debugging symbols compiled/packaged by me (x86_64 only).
 
-To compile by yourself:
+.To compile by yourself
 
 ----
 $ git clone https://github.com/The-Compiler/qt-debug-pkgbuild.git
@@ -46,7 +55,7 @@ $ cd ../pyqt5
 $ makepkg -si --pkg pyqt5-common,python-pyqt5
 ----
 
-To install my pre-built packages:
+.To install my pre-built packages
 
 First download and sign the key:
 
@@ -73,23 +82,52 @@ Then install the packages:
 The `-debug` packages conflict with the non-debug variants - it's safe to
 remove them.
 
-Getting a core dump
--------------------
+Getting the stack trace
+~~~~~~~~~~~~~~~~~~~~~~~
 
-The next step is finding the core dump so we can get a stacktrace from it.
+First install `gdb` on your system if it's not installed already.
 
-First of all, try to reproduce your problem. If you can, run qutebrowser
-directly inside gdb like this:
+Then run qutebrowser directly inside gdb like this:
 
 ----
 $ gdb $(which python3) -ex 'run -m qutebrowser --debug'
 ----
 
+After you reproduce the crash, you should now see something like:
+
+----
+Program received signal SIGSEGV, Segmentation fault.
+...
+(gdb)
+----
+
+Now enter these commands at the gdb prompt:
+
+----
+(gdb) set logging on
+(gdb) bt full
+# you might have to press enter a few times until you get the prompt back
+(gdb) quit
+----
+
+This will create a `gdb.txt` in your current directory.
+
+Copy the last few lines of the debug log (before you got the gdb prompt) and
+the full content of `gdb.txt` into the bug report. Please also add some words
+about what you were doing (or what pages you visited) before the crash
+happened.
+
+Crashes which can NOT be reproduced
+-----------------------------------
+
 If you cannot reproduce the problem, you need to check if a coredump got
-written somewhere.
+written somewhere. You should not install debug symbols as they won't match the
+generated coredump.
+
+First install `gdb` on your system if it's not installed already.
 
-Check the file `/proc/sys/kernel/core_pattern` on your system. If it does not
-start with a `|` character (pipe), check if there is a file named `core` or
+Then check the file `/proc/sys/kernel/core_pattern` on your system. If it does
+not start with a `|` character (pipe), check if there is a file named `core` or
 `core.NNNN` in the directory from that file, or in the current directory.
 
 If so, execute gdb like this:
@@ -99,37 +137,26 @@ $ gdb $(which python3) /path/to/core
 ----
 
 If your `/proc/sys/kernel/core_pattern` contains something like
-`|/usr/lib/systemd/systemd-coredump`, use `coredumpctl` as root to run gdb:
+`|/usr/lib/systemd/systemd-coredump`, use `coredumpctl` to run gdb:
 
 ----
-# coredumpctl gdb $(which python3)
+$ coredumpctl gdb $(which python3)
 ----
 
-Getting a stack trace
----------------------
-
-Regardless of the way you used to open gdb, you should now see something like:
-
-----
-Program received signal SIGSEGV, Segmentation fault.
-...
-(gdb)
-----
+Getting the stack trace
+~~~~~~~~~~~~~~~~~~~~~~~
 
 Now enter these commands at the gdb prompt:
 
 ----
 (gdb) set logging on
-(gdb) set logging redirect on
 (gdb) bt
 # you might have to press enter a few times until you get the prompt back
-(gdb) set logging redirect off
 (gdb) quit
 ----
 
-Now copy the last few lines of the debug log (before you got the gdb prompt)
-and the full content of `gdb.txt` into the bug report. Please also add some
-words about what you were doing (or what pages you visited) before the crash
+Copy the content of `gdb.txt` into the bug report. Please also add some words
+about what you were doing (or what pages you visited) before the crash
 happened.
 
 [[windows]]
@@ -143,9 +170,9 @@ file displayed there.
 
 Now install
 http://www.microsoft.com/en-us/download/details.aspx?id=42933[DebugDiag] from
-Microsoft, then run the "DebugDiag 2 Analysis" tool. There, check
-"CrashHangAnalysis" and add your crash dump via "Add Data files". Then click
-"Start analysis".
+Microsoft, then run the *DebugDiag 2 Analysis* tool. There, check
+*CrashHangAnalysis* and add your crash dump via *Add Data files*. Then click
+*Start analysis*.
 
 Close the Internet Explorer which opens when it's done and use the
 folder-button at the top left to get to the reports. There find the report file