branch: master
commit a89d1b2be56fceb45e3736f15a209b900643a44a
Author: Clément Pit--Claudel <clement.pitclau...@live.com>
Commit: Clément Pit--Claudel <clement.pitclau...@live.com>
Rewrite README
Closes #72.
Screenshot is auto-generated using etc/screenshot.el.
---
README.md | 114 +++++++++++++++++++++++++++++++++++++++++++++++------
etc/realgud.png | Bin 0 -> 99484 bytes
etc/screenshot.el | 82 ++++++++++++++++++++++++++++++++++++++
3 files changed, 183 insertions(+), 13 deletions(-)
diff --git a/README.md b/README.md
index 5155738..15e1544 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,111 @@
[![Build Status][travis-image]][travis-url]
-[![MELPA Stable][melpa-image]][melpa-stable]
+[![MELPA][melpa-image]][melpa]
+[![MELPA Stable][melpa-stable-image]][melpa-stable]
-A modular GNU Emacs front-end for interacting with external debuggers.
+# RealGUD
-See https://github.com/rocky/emacs-dbgr/wiki/Debuggers-Supported for a list of
debuggers supported.
+**A modular GNU Emacs front-end for interacting with external debuggers**,
brought to you by **Rocky Bernstein** ([@rocky](https://github.com/rocky)) with
contributions by **Clément Pit-Claudel**
([@cpitclaudel](https://github.com/cpitclaudel)).
-A debugger can be run out of a *comint* process buffer, or you can use a
-`M-x realgud-track-mode` inside an existing
[shell](http://www.gnu.org/software/emacs/manual/html_node/emacs/Shell.html),
or [eshell](https://www.gnu.org/software/emacs/manual/html_mono/eshell.html)
buffer.
+
-To install, you'll need a couple of other Emacs packages installed. See
-[the installation
instructions](http://wiki.github.com/rocky/emacs-dbgr/how-to-install)
-for details.
+## Setup
-To get started using, see the
-[notes on using realgud](http://wiki.github.com/rocky/emacs-dbgr/how-to-use).
+### MELPA
-*Author:* Rocky Bernstein <ro...@gnu.org>
+[MELPA](http://melpa.org/#/getting-started) is a repository of Emacs packages.
Skip this step if you already use it. Otherwise, add the following to your
`.emacs` and restart Emacs:
-[travis-image]:
https://img.shields.io/travis/rocky/emacs-dbgr.svg?style=flat-square
+```elisp
+(require 'package)
+(add-to-list 'package-archives '("melpa" . "http://melpa.org/packages/";) t)
+(package-initialize)
+```
+
+### RealGUD
+
+Run the following commands to install RealGUD:
+
+```
+M-x package-refresh-contents RET (to refresh your package database)
+M-x package-install RET realgud RET (to install and compile `realgud` and
its dependencies)
+```
+
+## Quick start
+
+Use `M-x load-library RET realgud RET` to load RealGUD.
+
+### Launching the debugger
+
+Open a source file, then use `M-x realgud:<debugger-name>` to start your
favorite debugger (for example, you can use `M-x realgud:pdb` to launch PDB, a
Python debugger). RealGUD opens two windows: the *command window* (showing the
debugger's REPL), and the *source window*, showing your code. An solid arrow
`▶` indicates the current line in the source window. Grayed out arrows
indicate previous positions.
+
+### Using the debugger
+
+All usual debugger commands work in the command window: for example, you can
type `n RET` in the command window to step forward one source line. But
RealGUD's power lies in the source window: in it, most single keys correspond
to a debugger action. For example, you can press `n` in the source window to
step forward.
+
+### Source window commands
+
+Here is a quick rundown of the most useful commands. “🐁” indicates mouse
commands (commands that can be run by clicking on a variable or in the
margins). Many of the commands are accessible from the tool bar
(`tool-bar-mode`) and the menu (`menu-bar-mode`).
+
+* **Motion commands**
+
+ | Command | Action
|
+ | --------------------------------------------- |
--------------------------------------------- |
+ | <kbd>n</kbd>, <kbd>F10</kbd> | Next (aka “step over”,
“step through”) |
+ | <kbd>s</kbd>, <kbd>SPC</kbd>, <kbd>F11</kbd> | Step (aka “step into”;
`C-u`: repeat) |
+ | <kbd>f</kbd>, <kbd>S-F11</kbd> | Finish (aka “step out”,
“return”) |
+ | <kbd>c</kbd>, <kbd>F5</kbd> | Continue (run to next
break point) |
+
+* **Using breakpoints**
+
+ | Command | Action
|
+ | --------------------------------------------- |
--------------------------------------------- |
+ | <kbd>b</kbd>, <kbd>F9</kbd> | Set breakpoint 🐁
|
+ | <kbd>D</kbd> | Clear breakpoint 🐁 (by
number) |
+
+* **Inspecting variables**
+
+ | Command | Action
|
+ | --------------------------------------------- |
--------------------------------------------- |
+ | <kbd>mouse-2</kbd> (middle button) | Inspect variable under
cursor (in tooltip) 🐁 |
+ | <kbd>e</kbd> | Evaluate expression
|
+
+* **Control commands**
+
+ | Command | Action
|
+ | --------------------------------------------- |
--------------------------------------------- |
+ | <kbd>q</kbd>, <kbd>S-F5</kbd> | Quit
|
+ | <kbd>R</kbd>, <kbd>r</kbd> | Run (aka “restart”)
|
+ | <kbd>S</kbd> | Go to command window
|
+
+## Supported debuggers
+
+RealGUD supports [many external
debuggers](https://github.com/rocky/emacs-dbgr/wiki/Debuggers-Supported). Help
us [support even
more](https://github.com/rocky/emacs-dbgr/wiki/How-to-add-a-new-debugger)!
+
+## Advanced topics
+
+### Extra commands
+
+“⚙” indicates a work-in-progress (contributions welcome!)
+
+| Command | Action
|
+| -------------------------------------------- |
---------------------------------------------- |
+| <kbd>U</kbd> | Until (run to a greater
source line) |
+| <kbd>u</kbd>, <kbd>></kbd> | Up stack (move to older stack
frame) |
+| <kbd>d</kbd>, <kbd><</kbd> | Down stack (move to younger
stack frame) |
+| <kbd>X</kbd> | Clear breakpoint (by line)
|
+| <kbd>-</kbd> | Disable breakpoint ⚙
|
+| <kbd>+</kbd> | Enable breakpoint ⚙
|
+
+### Tracking an existing debugger process
+
+Use a `M-x realgud-track-mode` inside an existing
[shell](http://www.gnu.org/software/emacs/manual/html_node/emacs/Shell.html),
or [eshell](https://www.gnu.org/software/emacs/manual/html_mono/eshell.html)
buffer to track an already-running debugger process.
+
+### RealGUD's wiki
+
+Browse the [wiki](http://wiki.github.com/rocky/emacs-dbgr/) for more
information about [setting
up](http://wiki.github.com/rocky/emacs-dbgr/how-to-install), [using
realgud](http://wiki.github.com/rocky/emacs-dbgr/how-to-use), [exploring
features](https://github.com/rocky/emacs-dbgr/wiki/Features), and lots more.
+
+[travis-image]: https://img.shields.io/travis/rocky/emacs-dbgr.svg
[travis-url]: https://travis-ci.org/rocky/emacs-dbgr
-[melpa-image]: http://stable.melpa.org/packages/realgud-badge.svg
+[melpa-stable-image]: http://stable.melpa.org/packages/realgud-badge.svg
[melpa-stable]: http://stable.melpa.org/#/realgud
+[melpa-image]: http://melpa.org/packages/realgud-badge.svg
+[melpa]: http://melpa.org/#/realgud
diff --git a/etc/realgud.png b/etc/realgud.png
new file mode 100644
index 0000000..827e7bb
Binary files /dev/null and b/etc/realgud.png differ
diff --git a/etc/screenshot.el b/etc/screenshot.el
new file mode 100644
index 0000000..41f8e47
--- /dev/null
+++ b/etc/screenshot.el
@@ -0,0 +1,82 @@
+;;; Prepare a RealGUD screenshot
+
+;; Run ‘cask exec emacs -Q -L . -l etc/screenshot.el’ from the project's root
to
+;; build a screenshot.
+
+(defvar my/fringe-width 12)
+
+(defun my/cleanup ()
+ (dolist (buffer (buffer-list))
+ (kill-buffer buffer)))
+
+(defun my/prepare-UI ()
+ "Prepare UI for taking a screenshot."
+ (ido-mode)
+ (tool-bar-mode)
+ (menu-bar-mode -1)
+ (scroll-bar-mode -1)
+ (column-number-mode)
+ (fringe-mode (cons my/fringe-width my/fringe-width))
+ (blink-cursor-mode -1)
+ (setq-default cursor-type 'bar
+ split-width-threshold 80
+ truncate-partial-width-windows t
+ frame-title-format (format "RealGUD:PDB @ Emacs %s"
emacs-version)
+ x-gtk-use-system-tooltips nil)
+ (load-theme 'tango t)
+ ;; (set-face-attribute 'tooltip nil :height 60)
+ (set-face-attribute 'match nil :background "yellow1")
+ (set-face-attribute 'default nil :family "Ubuntu Mono" :height 90)
+ (set-face-attribute 'mode-line nil :foreground "gray60" :background "black")
+ (set-face-attribute 'mode-line-inactive nil :foreground "gray60" :background
"#404045")
+ (set-face-attribute 'mode-line-buffer-id nil :foreground "#eab700")
+ (set-fontset-font t 'unicode "Ubuntu Mono")
+ (set-frame-size nil 140 20)
+ (redisplay t))
+
+(defun my/load-RealGUD ()
+ "Load RealGUD."
+ (package-initialize)
+ (load-library "realgud"))
+
+(defvar my/source-buffer nil)
+(defvar my/command-buffer nil)
+
+(defun my/load-example ()
+ "Prepare an example file and start the debugger."
+ (save-window-excursion
+ (find-file "realgud/common/fringe-utils.py")
+ (setq my/source-buffer (current-buffer))
+ (hl-line-mode 1)
+ (realgud:pdb (format "python3 -m pdb %S" buffer-file-name))
+ (sit-for 3) ;; Give PDB some time to start
+ (setq my/command-buffer (current-buffer))
+ (font-lock-add-keywords ;; Hide default directory
+ nil `((,(regexp-quote default-directory) 0 '(face nil display "<demo>/")
append)) t)
+ (font-lock-mode 1))
+ (switch-to-buffer my/source-buffer)
+ (set-window-buffer (split-window-horizontally) my/command-buffer))
+
+(defun my/prepare-screenshot-1 ()
+ "Prepare for taking a screenshot."
+ (my/prepare-UI)
+ (my/load-RealGUD)
+ (my/load-example)
+ (with-current-buffer my/source-buffer
+ (dolist (line '(4 12 17))
+ (goto-char (point-min))
+ (forward-line (1- line))
+ (realgud:cmd-break nil)
+ (sit-for 1)))
+ (goto-char (point-min))
+ (recenter-top-bottom 0)
+ (realgud:cmd-next)
+ (sit-for 1)
+ (realgud:cmd-continue)
+ (sit-for 1)
+ (hl-line-highlight)
+ (set-window-start (get-buffer-window my/command-buffer) 1)
+ (message nil))
+
+(print default-directory)
+(run-with-idle-timer 0 nil #'my/prepare-screenshot-1)
