[elpa] master a89d1b2 149/215: Rewrite README

[Rocky Bernstein]

branch: master
commit a89d1b2be56fceb45e3736f15a209b900643a44a
Author: Clément Pit--Claudel <address@hidden>
Commit: Clément Pit--Claudel <address@hidden>

    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** 
(address@hidden(https://github.com/rocky)) with contributions by **Clément 
Pit-Claudel** (address@hidden(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.
+![RealGUD screenshot](etc/realgud.png)
 
-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 <address@hidden>
+[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>&gt;</kbd>                | Up stack (move to older stack 
frame)           |
+| <kbd>d</kbd>, <kbd>&lt;</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)