Improve README for publishing

* NEWS.txt: New file. * README.txt: Improve documentation. * vundo.el: Improve Commentary section (which copies README). Fix typoes in Developer section.
casouri · Apr 6, 2022 · acdc706 · acdc706
1 parent 0e3af84
commit acdc706
Show file tree

Hide file tree

Showing 3 changed files with 100 additions and 27 deletions.
diff --git a/NEWS.txt b/NEWS.txt
@@ -0,0 +1,15 @@
+<2022-04-04 Mon>: Version 1.0.0
+
+<2022-03-29 Tue>: vundo--mode and vundo--mode-map are now vundo-mode
+and vundo-mode-map. A new custom option vundo-compact-display is added.
+
+<2022-03-23 Wed>: UI now defaults to ASCII mode. ASCII mode also draws
+differently now, it now draws
+
+    o--o--o     instead of      o--o--o
+    |  `--x                     |  +--*
+    |--o                        |--o
+    `--o                        +--o
+
+<2021-11-26 Fri>: Variable vundo-translate-alist changed to
+vundo-glyph-alist and has different value now.
diff --git a/README.txt b/README.txt
@@ -1,25 +1,34 @@
-To use vundo, type M-x vundo RET in the buffer you want to undo.
-A undo tree buffer should pop up. To move around, type:
+To use vundo, type M-x vundo RET in the buffer you want to undo. An
+undo tree buffer should pop up. To move around, type:
 
   f   to go forward
   b   to go backward
+
   n   to go to the node below when you at a branching point
   p   to go to the node above
+
+  a   to go back to the last branching point
+  e   to go forward to the end/tip of the branch
+
   q   to quit, you can also type C-g
 
-By default, you need to press RET to “commit” your change and if
-you quit with q or C-g, the change made by vundo are rolled back.
-You can set ‘vundo-roll-back-on-quit’ to nil to disable rolling
-back.
+n/p may need some more explanation. In the following tree, n/p can
+move between A and B because they share a parent (thus at a branching
+point), but not C and D.
+
+         A  C
+    ──○──○──○──○──○
+      │  ↕
+      └──○──○──○
+         B  D
 
-If you bring up the vundo buffer and make some modification in the
-original buffer, the tree in the vundo buffer doesn’t automatically
-update. Vundo catches up the next time you invoke any command:
-instead of performing that command, it updates the tree.
+By default, you need to press RET to “commit” your change and if you
+quit with q or C-g, the changes made by vundo are rolled back. You can
+set ‘vundo-roll-back-on-quit’ to nil to disable rolling back.
 
 Note: vundo.el requires Emacs 28.
 
-Faces:
+Customizable faces:
 
 - vundo-default
 - vundo-node
@@ -65,11 +74,11 @@ probably will not add those features in the future.
 
 
 
-Changelog:
+Changelog (full changelog in NEWS.txt):
 
-<2022-04-04 Mon> Version 1.0.0
+<2022-04-04 Mon>: Version 1.0.0
 
-<2022-03-29 Tue> vundo--mode and vundo--mode-map are now vundo-mode
+<2022-03-29 Tue>: vundo--mode and vundo--mode-map are now vundo-mode
 and vundo-mode-map. A new custom option vundo-compact-display is added.
 
 <2022-03-23 Wed>: UI now defaults to ASCII mode. ASCII mode also draws

diff --git a/vundo.el b/vundo.el
@@ -26,26 +26,37 @@
 
 ;;; Commentary:
 ;;
-;; To use vundo, type M-x vundo RET in the buffer you want to undo.
-;; A undo tree buffer should pop up. To move around, type:
+;; To use vundo, type M-x vundo RET in the buffer you want to undo. An
+;; undo tree buffer should pop up. To move around, type:
 ;;
 ;;   f   to go forward
 ;;   b   to go backward
+;;
 ;;   n   to go to the node below when you at a branching point
 ;;   p   to go to the node above
+;;
+;;   a   to go back to the last branching point
+;;   e   to go forward to the end/tip of the branch
+;;
 ;;   q   to quit, you can also type C-g
 ;;
-;; By default, you need to press RET to “commit” your change and if
-;; you quit with q or C-g, the change made by vundo are rolled back.
-;; You can set ‘vundo-roll-back-on-quit’ to nil to disable rolling
-;; back.
+;; n/p may need some more explanation. In the following tree, n/p can
+;; move between A and B because they share a parent (thus at a branching
+;; point), but not C and D.
+;;
+;;          A  C
+;;     ──○──○──○──○──○
+;;       │  ↕
+;;       └──○──○──○
+;;          B  D
+;;
+;; By default, you need to press RET to “commit” your change and if you
+;; quit with q or C-g, the changes made by vundo are rolled back. You can
+;; set ‘vundo-roll-back-on-quit’ to nil to disable rolling back.
 ;;
-;; If you bring up the vundo buffer and make some modification in the
-;; original buffer, the tree in the vundo buffer doesn’t automatically
-;; update. Vundo catches up the next time you invoke any command:
-;; instead of performing that command, it updates the tree.
+;; Note: vundo.el requires Emacs 28.
 ;;
-;; Faces:
+;; Customizable faces:
 ;;
 ;; - vundo-default
 ;; - vundo-node
@@ -70,6 +81,44 @@
 ;; to use that font:
 ;;
 ;;     (set-face-attribute 'vundo-default nil :family "Symbola")
+;;
+;; Tests:
+;;
+;; You can run tests by loading test/vundo-test.el and M-x ert RET t RET
+;; to run those tests interactively, or use the following batch command:
+;;
+;;      emacs --batch \
+;;            -l vundo.el \
+;;            -l test/vundo-test.el \
+;;            -f ert-run-tests-batch-and-exit
+;;
+;; Comparing to undo-tree:
+;;
+;; Vundo doesn’t need to be turned on all the time nor replace the undo
+;; commands like undo-tree does. Vundo displays the tree horizontally,
+;; whereas undo-tree displays a tree vertically. Vundo doesn’t have many
+;; advanced features that undo-tree does (like showing diff), and most
+;; probably will not add those features in the future.
+;;
+;;
+;;
+;; Changelog (full changelog in NEWS.txt):
+;;
+;; <2022-04-04 Mon>: Version 1.0.0
+;;
+;; <2022-03-29 Tue>: vundo--mode and vundo--mode-map are now vundo-mode
+;; and vundo-mode-map. A new custom option vundo-compact-display is added.
+;;
+;; <2022-03-23 Wed>: UI now defaults to ASCII mode. ASCII mode also draws
+;; differently now, it now draws
+;;
+;;     o--o--o     instead of      o--o--o
+;;     |  `--x                     |  +--*
+;;     |--o                        |--o
+;;     `--o                        +--o
+;;
+;; <2021-11-26 Fri>: Variable vundo-translate-alist changed to
+;; vundo-glyph-alist and has different value now.
 
 ;;; Developer:
 ;;
@@ -114,14 +163,14 @@
 ;; Position-only records
 ;;
 ;; We know how undo works: when undoing, ‘primitive-undo’ looks at
-;; each record in ‘pending-undo-list’ and modify the buffer
+;; each record in ‘pending-undo-list’ and modifies the buffer
 ;; accordingly, and that modification itself pushes new undo records
 ;; into ‘buffer-undo-list’. However, not all undo records introduce
 ;; modification, if the record is an integer, ‘primitive-undo’ simply
 ;; ‘goto’ that position, which introduces no modification to the
 ;; buffer and pushes no undo record to ‘buffer-undo-list’. Normally
 ;; position records accompany other buffer-modifying records, but if a
-;; particular record consist of only position records, we have
+;; particular record consists of only position records, we have
 ;; trouble: after an undo step, ‘buffer-undo-list’ didn’t grow, as far
 ;; as vundo tree-folding algorithm is concerned, we didn’t move.
 ;; Assertions expecting to see new undo records in ‘buffer-undo-list’