Update documentation on debugger extensions to mention source step

Also make documentation more consistent across the repo.

Author: undo-bkenward

automatic_symbol_loading/README.md

@@ -1,5 +1,4 @@
-Load Debug Symbols
-==================
+# Load Debug Symbols
 
 A common practice amongst UDB users is to produce binaries compiled with debug symbols and
 then use a tool such as `objcopy` to strip it of symbols, producing a `.debug` symbol file
@@ -15,10 +14,19 @@ This script automates the symbol loading completely.
 The script will traverse the whole directory structure, the user is just asked for the base
 directory.
 
-Usage: `load-all-symbols PATHTOBASEDIR`
+## Usage
+```
+load-all-symbols PATHTOBASEDIR
+```
 
-Examples:
-`load-all-symbols /data/mci/` - For each library loaded in UDB looks for the symbol file
+Before using the script it must be loaded in to the debugger:
+```
+source PATHTOADDONS/automatic_symbol_loading/automatic_symbol_loading.py
+```
+
+## Examples
+
+`load-all-symbols /data/mci/` : for each library loaded in UDB looks for the symbol file
 (by taking into consideration all and only the files ending in `.debug`) and, if the Build-IDs
 match, it loads the symbol-file.
 

load_debug_symbols/README.md

@@ -1,5 +1,4 @@
-Load Debug Symbols
-==================
+# Load Debug Symbols
 
 A common practice amongst customers is to produce binaries compiled with debug symbols and
 then use a tool such as `objcopy` to strip it of symbols, producing a `.debug` symbol file
@@ -12,10 +11,19 @@ retrospectively add the debug symbols to the recording, the user is required to
 `add-symbol-file` command in udb and pass in the `.debug` file and relevant addresses for the
 `.text`, `.data` and `.bss` sections. This script automates this process.
 
-Usage: `load-debug-symbols PATHTOFILE`
+## Usage
+```
+load-debug-symbols PATHTOFILE
+```
 
-Examples:
-`load-debug-symbols /foo/bar/baz.debug` - Loads the debug symbols by parsing relevant sections.
+Before using the script it must be loaded in to the debugger:
+```
+source PATHTOADDONS/load_debug_symbols/load_debug_symbols.py
+```
+
+## Examples
+
+`load-debug-symbols /foo/bar/baz.debug` : loads the debug symbols by parsing relevant sections.
 
 Note that the argument to `load-debug-symbols` needs to be a valid debug symbol file and
 present in the file system.

reconstruct_file/README.md

@@ -1,19 +1,23 @@
-Reconstruct file
-================
+# Reconstruct file
 
 Reconstruct a file read by the target program by examining its execution
 history. Use the `-regex` or `-fd` options to select which file to reconstruct
 or, if omitted, the first file opened is reconstructed.
 
-Usage:
+## Usage
 
 ```
 reconstruct-file [-regex PATH-REGEX | -fd FILE-DESCRIPTOR]
                  [-from-start]
                  [-output OUTPUT-PATH]
 ```
 
-Optional arguments:
+Before using the script it must be loaded in to the debugger:
+```
+source PATHTOADDONS/reconstruct_file/reconstruct_file.py
+```
+
+### Optional arguments
 
 - `-regex PATH-REGEX`:
   A regular expression matching the path of the file to reconstruct. Only the
@@ -28,7 +32,7 @@ Optional arguments:
   Path to a file were to write the reconstructed file. If not specified, the
   content is printed on standard output.
 
-Limitations:
+## Limitations
 
 - Only 64-bit x86 is supported.
 - Only files which are read in their entirety can be fully reconstructed.

regs_every_bb/README.md

@@ -1,7 +1,13 @@
-Regs every bb
-=============
+# Regs every bb
 
 Prints the values of all the registers at every basic block within a range
 
-	Usage:
-	uregs <bbstart> <bbend>
+## Usage
+```
+uregs <bbstart> <bbend>
+```
+
+Before using the script it must be loaded in to the debugger:
+```
+source PATHTOADDONS/regs_every_bb/regs_every_bb.py
+```

sample_functions/README.md

@@ -1,6 +1,6 @@
 # Sample functions
 
-Sampler which counts the number of times we find ourselves in a particular function. 
+Sampler which counts the number of times we find ourselves in a particular function.
 Outputs a list of functions with their counts.
 ```
 Usage:
@@ -15,6 +15,11 @@ Usage:
   means sample every basic block count from 1 to 1000.
 ```
 
+Before using the script it must be loaded in to the debugger:
+```
+source PATHTOADDONS/sample_functions/sample_functions.py
+```
+
 ## Generating flame graphs
 
 The output from this tool can be used directly to generate [flame graphs](https://www.brendangregg.com/flamegraphs.html).

what_map/README.md

@@ -1,18 +1,26 @@
-What map
-========
+# What map
 
 Looks up a variable or address within the maps of the debuggee.
 
-Usage: whatmap EXPRESSION
+## Usage
+```
+whatmap EXPRESSION
+```
 
-Examples:  
-whatmap my_variable        - Looks up the map containing the named variable.
-whatmap *0x1234            - Looks up the map containing the address 0x1234.
+Before using the script it must be loaded in to the debugger:
+```
+source PATHTOADDONS/what_map/what_map.py
+```
 
-Note that the argument to "whatmap" needs to be addressable - in other words, you should use an
-argument that you would pass to "watch".
+## Examples
+
+`whatmap my_variable` : looks up the map containing the named variable.
+
+`whatmap *0x1234` : looks up the map containing the address 0x1234.
+
+Note that the argument to `whatmap` needs to be addressable - in other words, you should use an
+argument that you would pass to `watch`.
 
 This command works with vanilla GDB or within UDB. When run under UDB it will inspect the maps
 of the currently active child process - note that these don't exactly match the maps that were
 present at record time.
-