.elpaignore

@@ -1,7 +1,6 @@
 .github
 .gitignore
 test
-company-tests.el
 Cask
 CONTRIBUTING.md
-HISTORY.md
+HISTORY.md

.github/workflows/news.yml

@@ -22,7 +22,7 @@ jobs:
           output: NEWS.md
           base: HISTORY.md
           issues: no
-          futureRelease: v0.3.0
+          futureRelease: v0.3.1
 
       - name: Commit changes
         uses: stefanzweifel/git-auto-commit-action@v4

CONTRIBUTING.md

@@ -41,11 +41,11 @@ cask exec buttercup -L .
 ```
 
 ## Copyright Assignment
-This package is subject to the same [[https://www.gnu.org/prep/maintain/html_node/Copyright-Papers.html][Copyright Assignment]] policy as
-GNU Emacs and all other packages in [[https://elpa.gnu.org/packages/][GNU ELPA]].
+This package is subject to the same [Copyright Assignment](https://www.gnu.org/prep/maintain/html_node/Copyright-Papers.html) policy as
+GNU Emacs and all other packages in [GNU ELPA](https://elpa.gnu.org/packages/).
 
-Any [[https://www.gnu.org/prep/maintain/html_node/Legally-Significant.html#Legally-Significant][legally significant]] contributions can only be accepted after the
-author has completed their paperwork.  Please see [[https://git.savannah.gnu.org/cgit/gnulib.git/tree/doc/Copyright/request-assign.future][the request form]] if
+Any [legally significant](https://www.gnu.org/prep/maintain/html_node/Legally-Significant.html#Legally-Significant) contributions can only be accepted after the
+author has completed their paperwork.  Please see [the request form](https://git.savannah.gnu.org/cgit/gnulib.git/tree/doc/Copyright/request-assign.future) if
 you want to proceed with the assignment.
 
 The copyright assignment isn't a big deal, it just says that the

Cask

@@ -4,6 +4,7 @@
 (development
  (depends-on "undercover")
  (depends-on "buttercup")
- (depends-on "smooth-scrolling"))
+ (depends-on "smooth-scrolling")
+ (depends-on "linum"))
 
 (package-file "topspace.el")

NEWS.md

@@ -1,5 +1,13 @@
 # History of user-visible changes
 
+## [v0.3.1](https://github.com/trevorpogue/topspace/tree/v0.3.1) (2022-08-24)
+
+[Full Changelog](https://github.com/trevorpogue/topspace/compare/v0.3.0...v0.3.1)
+
+**Fixed bugs:**
+
+- Prevent line `1` indicator sometimes displaying too high in `linum-mode` [\#22](https://github.com/trevorpogue/topspace/pull/22) ([trevorpogue](https://github.com/trevorpogue))
+
 ## [v0.3.0](https://github.com/trevorpogue/topspace/tree/v0.3.0) (2022-05-13)
 
 [Full Changelog](https://github.com/trevorpogue/topspace/compare/v0.2.1...v0.3.0)

README.md

@@ -21,13 +21,14 @@
 <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 lets you display a buffer's first line in the center of a window instead of just at the top.
+This is done by automatically drawing an upper margin/padding above line 1
+as you recenter and scroll it down.
 
 ### Features
 
 * **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.
+* **Easy to use**: No new keybindings are required, keep using all your previous scrolling & recentering commands, except now you can also scroll down the first line. It also integrates seamlessly with  [centered-cursor-mode][1] to keep the cursor centered all the way to the first line.
 
 # Installation
 
@@ -52,7 +53,7 @@ To enable `topspace-mode` globally on startup, add the following to your Emacs c
 ```
 # Usage
 ### Just enable and go
-No new keybindings are required, keep using all your previous scrolling & recentering commands, except now you can also scroll above the top lines.
+No new keybindings are required, keep using all your previous scrolling & recentering commands, except now you can also scroll down the first line.
 
 # Customization
 ```elisp
@@ -80,7 +81,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
@@ -266,8 +267,8 @@ scrolling."
 # How it works
 
 The "upper margin" is created by drawing an [overlay](https://www.gnu.org/software/emacs/manual/html_node/elisp/Overlays.html) before
-window-start containing newline characters.  As you scroll above the
-top line, more newline characters are added or removed accordingly.
+window-start containing newline characters.  As you scroll down the
+first 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`,

test/test-helper.el

@@ -15,6 +15,7 @@
               ))
 
 (require 'smooth-scrolling)
+(require 'linum)
 (require 'topspace)
 
 ;;; test-helper.el ends here

test/topspace-test.el

@@ -83,11 +83,18 @@
  (describe
   "topspace--after-scroll"
   (it "is needed when first scrolling above the top line"
+      (linum-mode 1)
       (goto-char 1)
       (topspace-set-height 0)
       (scroll-up-line)
       (scroll-down 2)
-      (expect (round (topspace-height)) :to-equal 1)))
+      (linum-mode -1)
+      (goto-char 1)
+      (topspace-set-height 0)
+      (scroll-up-line)
+      (scroll-down 2)
+      (expect (round (topspace-height)) :to-equal 1)
+      ))
 
  (describe
   "topspace--window-configuration-change"
@@ -200,10 +207,10 @@ by default"
   ;;               :to-equal
   ;;               (line-number-at-pos (point-max)))))
 
-  (it "can count lines end is larger `window-end'"
+  (it "can count lines'"
       (set-window-start (selected-window) 300)
       (expect (round (topspace--count-lines (window-start)
-                                            (1+ (topspace--window-end))))
+                                            (topspace--window-end)))
               :to-equal (count-screen-lines (window-start)
                                                (topspace--window-end)))
       (set-window-start (selected-window) 1))

topspace.el

@@ -1,12 +1,12 @@
-;;; topspace.el --- Scroll down & recenter top lines / get upper margins/padding -*- lexical-binding: t -*-
+;;; topspace.el --- Recenter line 1 with scrollable upper margin/padding -*- lexical-binding: t -*-
 
 ;; Copyright (C) 2021-2022 Free Software Foundation, Inc.
 
 ;; Author: Trevor Edwin Pogue <trevor.pogue@gmail.com>
 ;; Maintainer: Trevor Edwin Pogue <trevor.pogue@gmail.com>
 ;; URL: https://github.com/trevorpogue/topspace
 ;; Keywords: convenience, scrolling, center, cursor, margin, padding
-;; Version: 0.3.0
+;; Version: 0.3.1
 ;; Package-Requires: ((emacs "25.1"))
 
 ;; This file is part of GNU Emacs.
@@ -26,9 +26,12 @@
 
 ;;; 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 lets you display a buffer's first line in the center of a window
+;; instead of just at the top.
+;; This is done by automatically drawing an upper margin/padding above line 1
+;; as you recenter and scroll it down.
+
+;; See https://github.com/trevorpogue/topspace for a GIF demo & documentation.
 
 ;; Features:
 
@@ -38,27 +41,9 @@
 
 ;; - 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
+;;   can also scroll down the first line.  It also integrates
 ;;   seamlessly with `centered-cursor-mode' to keep the cursor
-;;   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.
-
-;; 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 other commands are called (interactively or
-;; otherwise).
-
-;; See the readme at https://github.com/trevorpogue/topspace for more
-;; information.
+;;   centered all the way to the first line.
 
 ;;; Code:
 
@@ -148,7 +133,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
@@ -435,7 +420,9 @@ command is run in the described case above."
                                      1 topspace--window-start-before-scroll)))
         (setq total-lines (abs total-lines))
         (set-window-start (selected-window) 1)
-        (topspace-set-height (- total-lines lines-already-scrolled)))))))
+        (topspace-set-height (- total-lines lines-already-scrolled)))
+      (when (and (bound-and-true-p linum-mode) (fboundp 'linum-update-window))
+        (linum-update-window (selected-window)))))))
 
 (defun topspace--after-recenter (&optional line-offset redisplay)
   "Recenter near the top of buffers by adding top space appropriately.
@@ -614,10 +601,9 @@ If that doesn't work it uses `topspace--count-lines-slow'."
   (cond
    ((= (round height) 0) "")
    ((= (round height) 1)
-    ;; comment a) It seems there is a bug in Emacs where you cannot set a
-    ;; string's line-height to a positive float less than 1.  So in this
-    ;; condition, settle for rounding the top space height up to 1
-    ;; TODO: open issue with Emacs devel mailing list for this
+    ;; comment a) You cannot set a string's line-height
+    ;; to a positive float less than 1.  So in this condition,
+    ;; settle for rounding the top space height up to 1
     "\n")
    (t
     ;; set the text to a series of newline characters with the last line
@@ -691,7 +677,8 @@ ARG defaults to 1."
 
 (defun topspace--post-command ()
   "Reduce top space height before the cursor can move past `window-end'."
-  (when (= topspace--pre-command-window-start 1)
+  (when (and (= topspace--pre-command-window-start 1)
+             (> (point) topspace--pre-command-point))
     (let ((next-line-point))
       (save-excursion
         (goto-char topspace--pre-command-point)
@@ -768,11 +755,14 @@ Topspace will not be enabled for:
 
 ;;;###autoload
 (define-minor-mode topspace-mode
-  "Scroll down & recenter top lines / get upper margins/padding.
+  "Recenter line 1 with scrollable upper margin/padding.
 
-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 lets you display a buffer's first line in the center of a window
+instead of just at the top.
+This is done by automatically drawing an upper margin/padding above line 1
+as you recenter and scroll it down.
+
+See https://github.com/trevorpogue/topspace for a GIF demo & documentation.
 
 Features:
 
@@ -786,24 +776,6 @@ Features:
   seamlessly with `centered-cursor-mode' to keep the cursor
   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.
-
-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 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'.