[pitivi] docs: Update gdb instructions

[Thibault Saunier <tsaunier src gnome org>]

commit 26d21d248b77b354bb6af0b955fa0eafa1fb9d53
Author: Alexandru Băluț <alexandru balut gmail com>
Date:   Tue Feb 27 01:48:28 2018 +0100

    docs: Update gdb instructions
    
    Fixes #2158

 bin/meson.build       |  3 ++-
 docs/Bug_reporting.md | 73 +++++++++++++++++++++++++++++++--------------------
 docs/HACKING.md       | 43 +++++++++++++++++++++---------
 3 files changed, 77 insertions(+), 42 deletions(-)
---
diff --git a/bin/meson.build b/bin/meson.build
index b7c163f7..48464b88 100644
--- a/bin/meson.build
+++ b/bin/meson.build
@@ -5,5 +5,6 @@ configure_file(input: 'pitivi.in',
 pitivi_bin = '@0@/pitivi'.format(meson.current_build_dir())
 install_data(pitivi_bin, install_dir: get_option('bindir'))
 
-# FIXME Work around to be able to run uninstalled
+# Create `pitivi` in the current dir at build time to be able to
+# run uninstalled in the dev env.
 run_command('cp', pitivi_bin, meson.current_source_dir())
diff --git a/docs/Bug_reporting.md b/docs/Bug_reporting.md
index 37cb6634..48b6cfd3 100644
--- a/docs/Bug_reporting.md
+++ b/docs/Bug_reporting.md
@@ -62,10 +62,38 @@ process:**
     integrate it into our test suite so that it does not happen again in
     the future!
 
-## Stack traces for crashes
 
-When reporting a **crash** or when the application freezed **deadlock**,
-it would be good to provide a **stack trace**.
+## Stack traces for crashes and deadlocks
+
+When reporting a **crash** or a **deadlock** (application is frozen),
+we can't do much without a **stack trace** (also known as back trace).
+
+The back trace can be obtained with `gdb`. Below are instructions on
+how to properly start Pitivi in gdb.
+
+Once Pitivi is started in gdb and you reproduce the crash or deadlock:
+- When Pitivi crashes, run `bt full` to get the backtrace.
+- When Pitivi freezes, press Ctrl+Z and run `thread apply all bt` to
+get the backtraces for all the threads.
+
+> To avoid the need to press Enter to “scroll” in gdb, run `set pagination 0`.
+
+### When running in the development environment
+
+1. Make sure you have the GNOME Sdk and Debug symbols installed,
+see below.
+
+2. Enter the sandbox:
+
+```
+ptvenv
+```
+
+3. Start Pitivi inside gdb:
+
+```
+gdb python3 -ex "run $PITIVI_REPO_DIR/bin/pitivi"
+```
 
 ### When running with Flatpak
 
@@ -81,33 +109,24 @@ for i in $(flatpak list | grep org.pitivi.Pitivi | awk '{ print $1 }'); do
 done
 ```
 
-2. Start a shell in the Pitivi bundle environment.
+2. Start a shell in the Pitivi flatpak sandbox:
 
 ```
 flatpak run -d --command=bash org.pitivi.Pitivi
 ```
-In the development environment, you do this by running `ptvenv` instead.
 
-3. Start Pitivi inside gdb
+3. Start Pitivi inside gdb:
 
 ```
 gdb python3 -ex 'run /app/bin/pitivi'
 ```
 
-When Pitivi crashes, run `bt full` to get the backtrace. When Pitivi
-freezes, press Ctrl+Z and run `thread apply all bt` to get the
-backtraces for all the threads.
-
 ### When running from the packages of your Linux distro
 
-See GNOME's [Getting
-Traces](https://wiki.gnome.org/Community/GettingInTouch/Bugzilla/GettingTraces)
-instructions for some comprehensive documentation and tips on the
-subject.
-
-For those of you who already know how to install the relevant debug
-packages etc, we provide you with some simple reminders below of
-commands that can be particularly useful in Pitivi's context.
+GNOME's [Getting Stack Traces] has excellent documentation and tips
+on the subject, including how to install the relevant debug
+packages. Below is a quick reminder for those already familiar with
+the process.
 
 When you want to “attach” to an existing Python process (useful for
 deadlocks, where the application will be hung instead of crashed):
@@ -119,14 +138,9 @@ gdb python3 THE_PITIVI_PROCESS_NUMBER
 When you want to run Pitivi entirely in gdb from the start:
 
 ```
-gdb python3 $(which pitivi)
-set pagination 0  # avoids the need to press Enter to “scroll”
-run
+gdb python3 -ex "run $(which pitivi)"
 ```
 
-When Pitivi crashes, run `bt full` to get the backtrace. When Pitivi
-freezes, press Ctrl+Z and run `thread apply all bt` to get the
-backtraces for all the threads.
 
 ## Debug logs
 
@@ -182,12 +196,11 @@ info from [GES](GES.md) in addition to Pitivi's:
 PITIVI_DEBUG=5 GST_DEBUG=ges:5 bin/pitivi > debug.log 2>&1;
 ```
 
-Some additional tips:
 
--   When using GST\_DEBUG, the resulting logs will most likely be too
-    big to be attached to a bug report directly. Instead, compress them
-    (in gzip, bzip2 or lzma format) before attaching them to a bug
-    report.
+> When using GST\_DEBUG, the resulting logs will most likely be too
+> big to be attached to a bug report directly. Instead, compress them
+> (in gzip, bzip2 or lzma format) before attaching them to a bug report.
+
 
 # Python performance profiling
 
@@ -205,3 +218,5 @@ The resulting `pitivi_performance.profile` file can then be processed
 to create a visual representation of where the most time was spent and
 which functions were called the most often in the code. See also [Jeff's
 blog posts on profiling](http://jeff.ecchi.ca/blog/tag/profiling/).
+
+[Getting Stack Traces]: https://wiki.gnome.org/Community/GettingInTouch/Bugzilla/GettingTraces
diff --git a/docs/HACKING.md b/docs/HACKING.md
index df498f2e..ca10b634 100644
--- a/docs/HACKING.md
+++ b/docs/HACKING.md
@@ -4,13 +4,17 @@ short-description: Using the Pitivi development environment
 
 # Hacking on Pitivi
 
-*The easy way to setup the development environment is to follow the*
-*[GNOME Newcomers guide](https://wiki.gnome.org/Newcomers/).*
-*Make sure to use the right git repository:*
+## The easy way
+
+The easy way to setup the development environment is to follow the
+[GNOME Newcomers guide](https://wiki.gnome.org/Newcomers/).
+
+Make sure to use the right git repository:
 
>   **https://gitlab.gnome.org/GNOME/pitivi.git**
 
-## Setting up advanced development environment
+
+## Setting up the advanced development environment
 
> NOTE: This way of setting the development environment is sensibly more complex
> but also more flexible than the one for newcomers. If you are a  beginner
@@ -66,7 +70,7 @@ Now that you are in the development environment, try running the
 Running in sandbox: ninja -C mesonbuild/ test
 ```
 
-Hack away, and check the effect of you changes by simply running:
+Hack away, and check the effect of your changes by simply running:
 ```
 (ptv-flatpak) $ pitivi
 ```
@@ -85,14 +89,29 @@ dependencies from their git repos and tarballs as defined in the
 manifest](https://git.gnome.org/browse/pitivi/tree/build/flatpak/pitivi.template.json) (located at 
`build/flatpak/pitivi.template.json`).
 
 
-### Building the Pitivi C parts
+### How we use the sandbox
 
-Select parts of Pitivi are written in C and need to be built when changed,
-such as the audio envelope renderer for the audio clips. Build them with:
-```
-(ptv-flatpak) $ ninja -C mesonbuild/
-Running in sandbox: ninja -C mesonbuild/
-```
+The sandbox we set up has access to the host file system. This allows
+running the Python modules in `pitivi-dev/pitivi/pitivi/...` on top of
+the GNOME + Pitivi dependencies system installed in the sandbox.
+Without this trick, you'd have to build and install every time when you
+change a `.py` file, to be able to test how it works, which would be
+annoying because it takes a non-negligible amount of time.
+
+We don't actually run Pitivi 100% uninstalled. Besides the `.py` files
+there are other parts which need to be built when changed or even
+installed before using them:
+
+- Select parts of Pitivi are written in C, such as the audio envelope
+renderer for the audio clips. Build them with `ninja -C mesonbuild/` or
+with our very own alias `build`, which is the same thing. No need to
+install them.
+
+- Similarly, `bin/pitivi.py.in` and `pitivi/configure.py.in` also need
+to be built with `build`, to regenerate the corresponding `.py` files.
+
+- The translations need to be built and installed, which can be done
+with `binstall`. See "Switching locales" below.
 
 
 ### Hacking on Pitivi dependencies (Meson)