1 files changed, 86 insertions, 0 deletions
diff --git a/tools/browse_trace.readme.md b/tools/browse_trace.readme.md
new file mode 100644
index 00000000..d607095e
--- /dev/null
+++ b/tools/browse_trace.readme.md
@@ -0,0 +1,86 @@
+### A debugging helper that lets you zoom in/out on a trace.
+
+To try it out, first create an example trace (from the top-level `mu/`
+directory):
+
+  ```shell
+  ./subx --trace run apps/factorial
+  ```
+
+This command will save a trace of its execution in a file called `last_run`.
+The trace consists of a series of lines, each starting with an integer depth
+and a single-word 'label', followed by a colon and whitespace.
+
+Now browse this trace:
+
+  ```shell
+  tools/browse_trace last_run
+  ```
+
+You should now find yourself in a UI showing a subsequence of lines from the
+trace, each line starting with a numeric depth, and ending with a parenthetical
+count of trace lines hidden after it with greater depths.
+
+For example, this line:
+
+  ```
+  2 app: line1 (30)
+  ```
+
+indicates that it was logged with depth 2, and that 30 following lines have
+been hidden at a depth greater than 2.
+
+(As an experiment, hidden counts of 1000 or more are highlighted in red.)
+
+The UI provides the following hotkeys:
+
+* `q` or `ctrl-c`: Quit.
+
+* `Enter`: 'Zoom into' this line. Expand lines hidden after it that were at
+  the next higher level.
+
+* `Backspace`: 'Zoom out' on a line after zooming in, collapsing lines below
+  expanded by some series of `Enter` commands.
+
+* `j` or `down-arrow`: Move cursor down one line.
+* `k` or `up-arrow`: Move cursor up one line.
+* `J` or `ctrl-f` or `page-down`: Scroll cursor down one page.
+* `K` or `ctrl-b` or `page-up`: Scroll cursor up one page.
+* `h` or `left-arrow`: Scroll cursor left one character.
+* `l` or `right-arrow`: Scroll cursor right one character.
+* `H`: Scroll cursor left one screen-width.
+* `L`: Scroll cursor right one screen-width.
+
+* `g` or `home`: Move cursor to start of trace.
+* `G` or `end`: Move cursor to end of trace.
+
+* `t`: Move cursor to top line on screen.
+* `c`: Move cursor to center line on screen.
+* `b`: Move cursor to bottom line on screen.
+* `T`: Scroll line at cursor to top of screen.
+
+* `/`: Search forward for a pattern.
+* `?`: Search backward for a pattern.
+* `n`: Repeat the previous `/` or `?`.
+* `N`: Repeat the previous `/` or `?` in the opposite direction.
+
+After hitting `/`, the mini-editor on the bottom-most line supports the
+following hotkeys:
+* ascii characters: add the key to the pattern.
+* `Enter`: search for the pattern.
+* `Esc` or `ctrl-c`: cancel the current search, setting the screen back
+  to its state before the search.
+* `left-arrow`: move cursor left.
+* `right-arrow`: move cursor right.
+* `ctrl-a` or `home`: move cursor to start of search pattern.
+* `ctrl-e` or `end`: move cursor to end of search pattern.
+* `ctrl-u`: clear search pattern before cursor
+* `ctrl-k`: clear search pattern at and after cursor
+
+## wish list
+
+* Simple regular expression search: `.` and `*`.
+* Expand into lower depths as necessary when searching.
+* Zoom out everything.
+* Zoom out lines around the cursor to the highest (or specified) depth.
+  Maybe a number followed by `]`?