[elpa] externals/topspace c1e4621a11 067/181: Update description in topspace.el and readme.md

[ELPA Syncer]

branch: externals/topspace
commit c1e4621a11c79ec962bec75c12a6187f6dec3dc3
Author: Trevor Pogue <pogu...@mcmaster.ca>
Commit: Trevor Pogue <pogu...@mcmaster.ca>

    Update description in topspace.el and readme.md
---
 README.md   | 26 +++++++++++++++++++++++++-
 topspace.el | 22 ++++++++++++++++------
 2 files changed, 41 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 88296394c8..86f819c016 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
 <h1 align="center"> TopSpace </h1>
-<p align="center">Scroll down and recenter top lines in Emacs.</p>
+<p align="center">Scroll down and recenter top lines in Emacs / get upper 
margins/padding.</p>
 
 <!-- padding cursor -->
 
@@ -11,6 +11,13 @@
 
 <p align="center"><img 
src="https://user-images.githubusercontent.com/12535207/155176914-87390537-10f0-4ee5-9b37-cd798f07df27.gif";
 /></a></p>
 
+TopSpace is an Emacs minor mode that allows you to scroll down and recenter 
top lines
+by automatically drawing upper margins/padding above the top line
+as you scroll down or recenter top text.
+
+TopSpace is:
+
+
 * **Easier on the eyes**: Recenter or scroll down top text to a more 
comfortable eye level for reading, especially when in full-screen or on a large 
monitor.
 * **Easy to use**: No new keybindings are required, keep using all your 
previous scrolling & recentering commands, except now you can also scroll above 
the top lines. It also integrates seamlessly with  [centered-cursor-mode][1] to 
keep the cursor centered all the way to the top line.
 
@@ -68,4 +75,21 @@ Customize `topspace-center-position` to adjust the centering 
position.
 Customize `topspace-autocenter-buffers` to run this command automatically
 after first opening buffers and after window sizes change.
 
+# How it works under the hood
+
+The "upper margin" is created by drawing an overlay before
+window-start containing newline characters.  As you scroll above the
+top line, more newline characters are added or removed accordingly.
+
+No new keybindings are required as topspace automatically works for
+any commands or subsequent function calls which use `scroll-up`,
+`scroll-down`, or `recenter` as the underlying primitives for
+scrolling.  This includes all scrolling commands/functions available
+in Emacs as far as the author is aware. This is achieved by using
+`advice-add` with the `scroll-up`, `scroll-down`, and `recenter`
+commands so that custom topspace functions are called before or after
+each time any of these commands are called (interactively or
+otherwise).
+
+
 [1]: https://github.com/andre-r/centered-cursor-mode.el
diff --git a/topspace.el b/topspace.el
index 9b72508cba..e38b912a41 100644
--- a/topspace.el
+++ b/topspace.el
@@ -1,4 +1,4 @@
-;;; topspace.el --- Scroll down & recenter top lines, get upper 
margins/padding -*- lexical-binding: t -*-
+;;; topspace.el --- Scroll down & recenter top lines / get upper 
margins/padding -*- lexical-binding: t -*-
 
 ;; Copyright (C) 2021-2022 Trevor Edwin Pogue
 
@@ -23,7 +23,11 @@
 ;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 ;;; Commentary:
-;; Scroll down and recenter top lines.
+;; TopSpace allows you to scroll down and recenter top lines
+;; by automatically drawing upper margins/padding above the top line
+;; as you scroll down or recenter top text.
+
+;; TopSpace is:
 
 ;; - Easier on the eyes: Recenter or scroll down top text to a more
 ;;   comfortable eye level for reading, especially when in full-screen
@@ -35,9 +39,8 @@
 ;;   seamlessly with `centered-cursor-mode' to keep the cursor
 ;;   centered all the way to the top line.
 
-;; How it works:
-;; A top margin is created above the top text line as you scroll down
-;; top text.  The "margin" is created by drawing an overlay before
+;; How it works under the hood:
+;; The "upper margin" is created by drawing an overlay before
 ;; window-start containing newline characters.  As you scroll above the
 ;; top line, more newline characters are added or removed accordingly.
 
@@ -45,7 +48,14 @@
 ;; any commands or subsequent function calls which use `scroll-up',
 ;; `scroll-down', or `recenter' as the underlying primitives for
 ;; scrolling.  This includes all scrolling commands/functions available
-;; in Emacs as far as the author is aware.
+;; in Emacs as far as the author is aware. This is achieved by using
+;; `advice-add' with the `scroll-up', `scroll-down', and `recenter'
+;; commands so that custom topspace functions are called before or after
+;; each time any of these commands are called (interactively or
+;; otherwise).
+
+;; See the readme at https://github.com/trevorpogue/topspace for more
+;; information.
 
 ;;; Code: