[elpa] externals/topspace cbdcdff484 051/181: Fix `recenter-top-bottom` bug, add .md files

[ELPA Syncer]

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

    Fix `recenter-top-bottom` bug, add .md files
    
    - Add CHANGELOG.md, CONTRIBUTING.md
    - Update README.md: modify slogan
    - .dir-locals.el: make same as in projectile project
---
 .dir-locals.el  | 11 ++++++-
 CHANGELOG.md    | 34 ++++++++++++++++++++++
 CONTRIBUTING.md | 35 +++++++++++++++++++++++
 README.md       | 38 ++++--------------------
 topspace.el     | 89 +++++++++++++++++++++++++++++++++++++++++----------------
 5 files changed, 149 insertions(+), 58 deletions(-)

diff --git a/.dir-locals.el b/.dir-locals.el
index 83a5eaa381..ce46cf2c8d 100644
--- a/.dir-locals.el
+++ b/.dir-locals.el
@@ -1,2 +1,11 @@
 ((emacs-lisp-mode
-  (indent-tabs-mode nil)))
+  (bug-reference-url-format . 
"https://github.com/trevorpogue/topspace/issues/%s";)
+  (bug-reference-bug-regexp . "#\\(?2:[[:digit:]]+\\)")
+  (indent-tabs-mode . nil)
+  (fill-column . 80)
+  (sentence-end-double-space . t)
+  (emacs-lisp-docstring-fill-column . 75)
+  (checkdoc-symbol-words . ("top-level" "major-mode" "macroexpand-all" 
"print-level" "print-length"))
+  (checkdoc-package-keywords-flag)
+  (checkdoc-arguments-in-order-flag)
+  (checkdoc-verb-check-experimental-flag)))
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000000..2d8ea33942
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,34 @@
+# Changelog
+
+## main (unreleased)
+
+### New features
+
+### Bugs fixed
+* [](): Make `recenter-top-bottom' act correctly when it moves point to bottom 
and top space is added to get there
+
+### Changes
+
+* 
[2584138](https://github.com/trevorpogue/topspace/commit/25841387a5d0300ea49356b9781c357b84df20bd):
 Raise topspace-center-position default to an objectively better position
+
+## 0.1.1 (2021-02-22)
+
+### New features
+
+### Bugs fixed
+* 
[4a69b2e](https://github.com/trevorpogue/topspace/commit/4a69b2eb741f8db9d69169a03a6724af0f2ec7ac):
 Allow recenter and recenter-top-bottom to be called interactively without an 
error
+* 
[4eb27ab](https://github.com/trevorpogue/topspace/commit/4eb27abaa182e856ba3f3c8e1e84fdd2e1f009af):
 Prevent top space from all suddenly disappearing when visual-line-mode is 
enabled and cursor scrolls bellow window-end when top space is present
+
+### Changes
+
+
+## 0.1.0 (2021-02-19)
+
+### New features
+* 
[8ce487b](https://github.com/trevorpogue/topspace/tree/8ce487bd3d36a568bd2b1cb9a2e53b7e02c4474e):
 Make mode work for any scrolling command by using add-advice with scroll-up, 
scroll-down, and recenter
+
+### Bugs fixed
+* 
[8ce487b](https://github.com/trevorpogue/topspace/tree/8ce487bd3d36a568bd2b1cb9a2e53b7e02c4474e):
 Stabilize, clean up, and add performance optimizations to code to make it 
ready for submission to MELPA
+
+### Changes
+* 
[e5b65ec](https://github.com/trevorpogue/topspace/commit/e5b65eccf92571163aa1b6bd738be22d8e0ad1a5):
 Change project name from vertical-center-mode to topspace
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000000..37a2ce29dc
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,35 @@
+# Contributing
+
+Feel free to work on reported and unresolved issues. 
+If you discover issues, have ideas for improvements or new features, please
+report them to the [issue tracker][1] of the repository or submit a pull
+request. Please, try to follow these guidelines when you do so.
+
+## Issue reporting
+
+* Check that the issue has not already been reported.
+* Check that the issue has not already been fixed in the latest code
+  (a.k.a. `master`).
+* Be clear, concise and precise in your description of the problem.
+* Open an issue with a descriptive title and a summary in grammatically 
correct,
+  complete sentences.
+* Include any relevant code to the issue summary.
+* If you're reporting performance issues it'd be nice if you added some 
profiling data (Emacs has a built-in profiler).
+
+## Pull requests
+
+* Read [how to properly contribute to open source projects on Github][2].
+* Use a topic branch to easily amend a pull request later, if necessary.
+* Write [good commit messages][3].
+* Mention related tickets in the commit messages (e.g. `[Fix #N] Add missing 
autoload cookies`)
+* Update the [changelog][5].
+* Use the same coding conventions as the rest of the project.
+* Verify your Emacs Lisp code with `checkdoc` (<kbd>C-c ? d</kbd>).
+* Open a [pull request][4] that relates to *only* one subject with a clear 
title
+  and description in grammatically correct, complete sentences.
+
+[1]: https://github.com/trevorpogue/topspace/issues
+[2]: http://gun.io/blog/how-to-github-fork-branch-and-pull-request
+[3]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+[4]: https://help.github.com/articles/using-pull-requests
+[5]: https://github.com/trevorpogue/topspace/CHANGELOG.md
diff --git a/README.md b/README.md
index 190bd9b14e..c745966c9f 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,7 @@
 <h1 align="center"> TopSpace </h1>
-<p align="center">Scroll above the top line.</p>
+<p align="center">Scroll down and recenter top lines in Emacs.</p>
+
+<!-- padding cursor -->
 
 <p align="center">
   <a href="http://melpa.org/#/topspace";><img 
src="http://melpa.org/packages/topspace-badge.svg"; height="20"/></a>
@@ -7,29 +9,10 @@
   <a href="https://www.gnu.org/licenses/gpl-3.0";><img 
src="https://img.shields.io/badge/License-GPLv3-blue.svg"; height="20"/></a>
 </p>
 
-<p align="center">
-<a 
href="https://github.com/trevorpogue/topspace#hammer_and_wrench-Installation";> 
Installation </a> |
-<a href="https://github.com/trevorpogue/topspace#gear-customization";> 
Customization</a> |
-<a 
href="https://github.com/trevorpogue/topspace#hammer_and_pick-extra-commands";> 
Extra commands</a> |
-<a href="https://github.com/trevorpogue/topspace#chains-supporters";> 
Supporters </a>
-</p>
-
 <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 lets you scroll above the top line to 
vertically center the top text or cursor with a scrollable top margin/padding.
-
-TopSpace is:
-
-* **Easier on the eyes**: Pull down the 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 
commands.
-
-* **Compatible with [centered-cursor-mode][1]**:
-Center the cursor all the way to the top line!
-<!-- <br/> -->
-
-<!-- **Table of contents**:  -->
+* **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.
 
 # :hammer_and_wrench: Installation
 
@@ -85,15 +68,4 @@ 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.
 
-
-# :chains: Supporters
-### &#8627; Stargazers
-[![Stargazers repo roster for 
@trevorpogue/topspace](https://reporoster.com/stars/trevorpogue/topspace)](https://github.com/trevorpogue/topspace/stargazers)
-
-### &#8627; Forkers
-[![Forkers repo roster for 
@trevorpogue/topspace](https://reporoster.com/forks/trevorpogue/topspace)](https://github.com/trevorpogue/topspace/network/members)
-<p align="center"><a href="https://github.com/trevorpogue/topspace#";><img 
src="http://randojs.com/images/barsSmallTransparentBackground.gif"; 
alt="Animated footer bars" width="100%"/></a></p>
-<br/>
-<p align="center"><a href="https://github.com/trevorpogue/topspace#";><img 
src="http://randojs.com/images/backToTopButtonTransparentBackground.png"; 
alt="Back to top" height="29"/></a></p>
-
 [1]: https://github.com/andre-r/centered-cursor-mode.el
diff --git a/topspace.el b/topspace.el
index fce53576fb..546b2ddfb2 100644
--- a/topspace.el
+++ b/topspace.el
@@ -1,4 +1,4 @@
-;;; topspace.el --- Scroll above the top line to vertically center top text or 
cursor with a scrollable top margin/padding -*- lexical-binding: t -*-
+;;; topspace.el --- Scroll down and recenter top lines, upper margin/padding 
-*- lexical-binding: t -*-
 
 ;; Copyright (C) 2021-2022 Trevor Edwin Pogue
 
@@ -23,16 +23,31 @@
 ;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 ;;; Commentary:
-;; Scroll above the top line to vertically center top text or cursor with a
-;; scrollable top margin/padding. An overlay is automatically drawn above the
-;; top text line as you scroll above, giving the equivalent effect of being 
able
-;; to scroll above the top line.
-
-;; 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.
+;; Scroll down and recenter top lines.
+
+;; - Easier on the eyes: Recenter or scroll down top text to a more
+;;   comfortable eye level for reading, especially if 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 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
+;; 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. It also integrates
+;; seamlessly with `centered-cursor-mode' to keep the cursor centered
+;; all the way to the top line.
 
 ;;; Code:
 
@@ -174,7 +189,9 @@ LINE-OFFSET and REDISPLAY are used in the same way as in 
`recenter'."
     (unless line-offset
       (setq line-offset (round (/ (topspace--window-height) 2))))
     (when (< line-offset 0)
-      (setq line-offset (- (topspace--window-height) line-offset)))
+      ;; subtracting 3 below made `recenter-top-bottom' act correctly
+      ;; when it moves point to bottom and top space is added to get there
+      (setq line-offset (- (- (topspace--window-height) line-offset) 3)))
     (topspace--put (- line-offset (topspace--count-screen-lines (window-start)
                                                                 (point))))))
 
@@ -410,18 +427,42 @@ Topspace will not be enabled for:
 
 ;;;###autoload
 (define-minor-mode topspace-mode
-  "Scroll above the top line to vertically center top text or cursor.
-It is like having a scrollable top margin/padding.
-An overlay is automatically drawn above the top text line as you scroll above,
-giving the effect of being able to scroll above the top line.
-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.
-When called interactively, toggle variable `topspace-mode'.  With prefix
-ARG, enable variable `topspace-mode' if ARG is positive, otherwise disable it.
-When called from Lisp, enable variable `topspace-mode' if ARG is omitted,
-nil or positive.  If ARG is `toggle', toggle variable `topspace-mode'.
+  "Scroll down and recenter top lines.
+
+- Easier on the eyes: Recenter or scroll down top text to a more
+  comfortable eye level for reading, especially if 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 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
+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. It also integrates
+seamlessly with `centered-cursor-mode' to keep the cursor centered
+all the way to the top line.
+
+Enabling/disabling:
+When called interactively, toggle variable `topspace-mode'.
+
+With prefix ARG, enable variable `topspace-mode' if
+ARG is positive, otherwise disable it.
+
+When called from Lisp, enable variable `topspace-mode' if
+ARG is omitted, nil or positive.
+
+If ARG is `toggle', toggle variable `topspace-mode'.
 Otherwise behave as if called interactively."
   :init-value nil
   :ligher topspace-mode-line