branch: externals/topspace
commit bb73278f40c2537f8385a70857d7429bd5952701
Author: Trevor Pogue <pogu...@mcmaster.ca>
Commit: Trevor Pogue <pogu...@mcmaster.ca>
Update description
---
README.md | 8 +++++---
topspace.el | 36 +++++++++++++++++++++---------------
2 files changed, 26 insertions(+), 18 deletions(-)
diff --git a/README.md b/README.md
index 5b5932c60f..d10cb0a44f 100644
--- a/README.md
+++ b/README.md
@@ -21,8 +21,10 @@
<a href="https://github.com/trevorpogue/topspace#extra-functions";> Extra
functions</a> |
<a href="https://github.com/trevorpogue/topspace#how-it-works";> How it
works </a> ]
-TopSpace is an Emacs minor mode that allows you to scroll down and recenter
top lines by automatically drawing an upper margin/padding above the top line
-as you scroll down or recenter top text.
+TopSpace is an Emacs minor mode that provides the ability to scroll down the
first line of a buffer to be below the very top of the window, as if the buffer
contains additional blank lines above the first line.
+This is done by automatically drawing an upper margin/padding above line 1
+as you recenter and scroll down top text, without modifying the
+underlying file.
### Features
@@ -80,7 +82,7 @@ This is done by automatically calling
`topspace-recenter-buffer'
and the positioning can be customized with `topspace-center-position'.
Top space will not be added if the number of text lines in the buffer is larger
than or close to the selected window's height, or if `window-start' is greater
-than 1. Customize `topspace-center-position' to adjust the centering position.
+than 1.
With the default value, buffers will not be centered if in a child frame
or if the user has already scrolled or used `recenter' with buffer in the
diff --git a/topspace.el b/topspace.el
index 8020e0d09a..a6a9785ce1 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 line 1 to be below the top of the
window using upper margin/padding -*- lexical-binding: t -*-
;; Copyright (C) 2021-2022 Free Software Foundation, Inc.
@@ -26,9 +26,14 @@
;;; Commentary:
-;; TopSpace allows you to scroll down and recenter top lines
-;; by automatically drawing an upper margin/padding above the top line
-;; as you scroll down or recenter top text.
+;; TopSpace provides the ability to scroll down the first line of a buffer
+;; to be below the very top of the window, as if the buffer contains
+;; additional blank lines above the first line.
+;; This is done by automatically drawing an upper margin/padding above line 1
+;; as you recenter and scroll down top text, without modifying the
+;; underlying file.
+
+;; See https://github.com/trevorpogue/topspace for a gif demo & documentation.
;; Features:
@@ -43,6 +48,7 @@
;; centered all the way to the top line.
;; How it works:
+
;; 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.
@@ -57,9 +63,6 @@
;; each time any of these other commands are called (interactively or
;; otherwise).
-;; See the readme at https://github.com/trevorpogue/topspace for more
-;; information.
-
;;; Code:
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@@ -148,7 +151,7 @@ This is done by automatically calling
`topspace-recenter-buffer'
and the positioning can be customized with `topspace-center-position'.
Top space will not be added if the number of text lines in the buffer is larger
than or close to the selected window's height, or if `window-start' is greater
-than 1. Customize `topspace-center-position' to adjust the centering position.
+than 1.
With the default value, buffers will not be centered if in a child frame
or if the user has already scrolled or used `recenter' with buffer in the
@@ -768,11 +771,16 @@ Topspace will not be enabled for:
;;;###autoload
(define-minor-mode topspace-mode
- "Scroll down & recenter top lines / get upper margins/padding.
+ "Scroll down & recenter line 1 to be below the top of the window.
-TopSpace allows you to scroll down and recenter top lines
-by automatically drawing an upper margin/padding above the top line
-as you scroll down or recenter top text.
+TopSpace provides the ability to scroll down the first line of a buffer
+to be below the very top of the window, as if the buffer contains
+additional blank lines above the first line.
+This is done by automatically drawing an upper margin/padding above line 1
+as you recenter and scroll down top text, without modifying the
+underlying file.
+
+See https://github.com/trevorpogue/topspace for a gif demo & documentation.
Features:
@@ -787,6 +795,7 @@ Features:
centered all the way to the top line.
How it works:
+
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.
@@ -801,9 +810,6 @@ commands so that custom topspace functions are called
before or after
each time any of these other commands are called (interactively or
otherwise).
-See the readme at https://github.com/trevorpogue/topspace for more
-information.
-
Enabling/disabling:
When called interactively, toggle `topspace-mode'.
