branch: elpa/flamegraph
commit 5603e21e6457b94bd2162b5c72a27aa20504caf0
Author: Dmitry Gutov <[email protected]>
Commit: Dmitry Gutov <[email protected]>
Add screenshots
---
README.md | 43 ++++++++++++++++++--------------------
docs/img/describe-dark.png | Bin 0 -> 166628 bytes
docs/img/describe-light.png | Bin 0 -> 166572 bytes
docs/img/flamegraph-dark.png | Bin 0 -> 238704 bytes
docs/img/flamegraph-light.png | Bin 0 -> 238566 bytes
docs/update-screenshots.sh | 47 ++++++++++++++++++++++++++++++++++++++++++
6 files changed, 67 insertions(+), 23 deletions(-)
diff --git a/README.md b/README.md
index 046e4e455f..1d9ef8ab4b 100644
--- a/README.md
+++ b/README.md
@@ -10,12 +10,26 @@ renderer is planned). Top-down "icicle" orientation: the
outermost
frame sits on the top row, and the stack grows downward. Identical
call paths are merged and children are sorted heaviest-first.
-`RET` / `mouse-1` zooms into a frame; `d` describes the frame
-(parent, callees, self-time) with a source snippet highlighting its
-outgoing calls; `f` jumps to that source line. The snippet and `f`
-need the data to include `file:line` — Elisp profiles always do; for
-perf, fold with `-F +srcline` (see
-[Recording](#recording-profile-data) below).
+`RET` / `mouse-1` zooms into a frame; `d` opens a description (parent,
+callees, self-time) with a source code snippet highlighting its
+outgoing calls; `f` opens that source. The snippet and `f` need the
+data to include `file:line` — Elisp profiles always do; for perf,
+fold with `-F +srcline` (see [Recording](#recording-profile-data)
+below).
+
+<p align="center">
+ <img src="docs/img/flamegraph-light.png" width="490">
+ <img src="docs/img/flamegraph-dark.png" width="490">
+</p>
+<p align="center">
+ <img src="docs/img/describe-light.png" width="490">
+ <img src="docs/img/describe-dark.png" width="490">
+</p>
+
+In the snippet, we pull in and highlight the source lines where the
+frame's outgoing calls appear. Parent and callees are cross-references
+(click to describe them); `l` / `r` walk the navigation history,
+help-mode style.
## Installation
@@ -66,23 +80,6 @@ format (one `;`-separated stack per line, followed by the
sample count).
| `g` | Redraw (e.g. after resizing the window) |
| `q` | Quit |
-## The describe buffer (`d`)
-
-For the frame at point, shows:
-
-- A clickable heading — for an Elisp symbol, opens the standard
- `describe-function` help; for a frame with an embedded source
- location, the `file:line` is a second button that visits that line.
-- A source snippet of the enclosing function, with the sampled line
- marked, structurally-enclosing lines kept (so the nesting that leads
- to the sampled line stays visible), and **every direct callee of the
- frame highlighted at its call site**, with skip-through special-form
- layers descended transparently.
-- Sample count and self-time.
-- Buttons to the frame's parent and to each callee. Callees rendered
- through `if`/`let`/`progn`/etc. are expanded inline so the path to
- the real callees stays visible.
-
## Recording profile data
### Emacs's native profiler
diff --git a/docs/img/describe-dark.png b/docs/img/describe-dark.png
new file mode 100644
index 0000000000..e662a44bdf
Binary files /dev/null and b/docs/img/describe-dark.png differ
diff --git a/docs/img/describe-light.png b/docs/img/describe-light.png
new file mode 100644
index 0000000000..7cb1c6bc12
Binary files /dev/null and b/docs/img/describe-light.png differ
diff --git a/docs/img/flamegraph-dark.png b/docs/img/flamegraph-dark.png
new file mode 100644
index 0000000000..b1fc0857fd
Binary files /dev/null and b/docs/img/flamegraph-dark.png differ
diff --git a/docs/img/flamegraph-light.png b/docs/img/flamegraph-light.png
new file mode 100644
index 0000000000..a727a2a559
Binary files /dev/null and b/docs/img/flamegraph-light.png differ
diff --git a/docs/update-screenshots.sh b/docs/update-screenshots.sh
new file mode 100755
index 0000000000..d693955237
--- /dev/null
+++ b/docs/update-screenshots.sh
@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Picks the two most recent PNGs from ~/Pictures/Screenshots/ (newest = dark,
+# second-newest = light) and crops them into ./img/.
+#
+# --- Sizing/positioning Emacs ---------------------------------------------
+# Current frame is at (22, 26) with outer dims 2636x1016. Eval inside Emacs
+# (M-:) to put a frame back in that spot. Use 2621x950 inner pixels to match
+# the default crops below, or 2636x1016 for the gdbus-captured alt crops.
+#
+# (progn (set-frame-position nil 22 26)
+# (set-frame-size nil 2621 950 t)) ; t = pixels, not chars
+#
+# --- Auto-screenshot via GNOME Shell --------------------------------------
+# Captures a screen region without the interactive picker. Uncomment and run
+# once per theme (toggle light/dark in between) — the two newest files in
+# ~/Pictures/Screenshots/ are picked up below.
+#
+# gdbus call --session \
+# --dest org.gnome.Shell.Screenshot \
+# --object-path /org/gnome/Shell/Screenshot \
+# --method org.gnome.Shell.Screenshot.ScreenshotArea \
+# 22 26 2636 1016 false \
+# "$HOME/Pictures/Screenshots/Screenshot from $(date '+%Y-%m-%d
%H-%M-%S').png"
+# --------------------------------------------------------------------------
+
+set -euo pipefail
+cd "$(dirname "$0")"
+
+mapfile -t shots < <(ls -t "$HOME/Pictures/Screenshots/"*.png 2>/dev/null |
head -2)
+LIGHT="${shots[1]:?need at least two screenshots in ~/Pictures/Screenshots/}"
+DARK="${shots[0]}"
+echo "LIGHT: $LIGHT"
+echo "DARK: $DARK"
+
+# Source images are 2621x950 (Emacs window with decorations).
+# Crop syntax: WIDTHxHEIGHT+X_OFFSET+Y_OFFSET
+convert "$LIGHT" -strip -crop 1304x944+8+4 +repage img/describe-light.png
+convert "$DARK" -strip -crop 1304x944+8+4 +repage img/describe-dark.png
+convert "$LIGHT" -strip -crop 1304x944+1315+4 +repage img/flamegraph-light.png
+convert "$DARK" -strip -crop 1304x944+1315+4 +repage img/flamegraph-dark.png
+
+# Alt crops for a 2636x1016 PNG captured via the gdbus command above. The
+# captured region still includes the GTK decorations, so the 8/4 insets stay.
+# convert "$LIGHT" -strip -crop 1311x1010+8+4 +repage img/describe-light.png
+# convert "$DARK" -strip -crop 1311x1010+8+4 +repage img/describe-dark.png
+# convert "$LIGHT" -strip -crop 1311x1010+1322+4 +repage
img/flamegraph-light.png
+# convert "$DARK" -strip -crop 1311x1010+1322+4 +repage
img/flamegraph-dark.png
