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

[ELPA Syncer]

branch: externals/topspace
commit da393d3573c611b16c4a09d9a175352bd2dbed10
Merge: 5d30dd0957 cbdcdff484
Author: Trevor Pogue <trevorpogue@gmail.com>
Commit: GitHub <noreply@github.com>

    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 +++++++++++++++++++++++
 topspace.el     | 89 +++++++++++++++++++++++++++++++++++++++++----------------
 4 files changed, 144 insertions(+), 25 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/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