Showing with 451 additions and 151 deletions.
  1. +2 −3 .github/PULL_REQUEST_TEMPLATE.md
  2. +29 −0 .github/workflows/changelog.yml
  3. +15 −4 CHANGELOG.md
  4. +1 −2 CONTRIBUTING.md
  5. +32 −0 HISTORY.md
  6. +103 −30 README.md
  7. +269 −112 topspace.el
5 changes: 2 additions & 3 deletions .github/PULL_REQUEST_TEMPLATE.md
View file
Expand Up @@ -8,10 +8,9 @@ The more detailed you are, the better.**
<!-- Please confirm with `x`: -->

- [ ] I have read the topspace [contributing guidelines](https://github.com/trevorpogue/topspace/blob/main/CONTRIBUTING.md)
- [ ] My changes follow the [Emacs Lisp](https://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html) conventions and the [Emacs Lisp Style Guide](https://github.com/bbatsov/emacs-lisp-style-guide)
- [ ] My changes follow the [Emacs Lisp conventions](https://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html) and the [Emacs Lisp Style Guide](https://github.com/bbatsov/emacs-lisp-style-guide)
- [ ] I've used the latest version of [package-lint](https://github.com/purcell/package-lint) to check for packaging issues, and addressed its feedback
- [ ] The new code is not generating bytecode warnings or `M-x checkdoc` warnings
- [ ] I've updated the [changelog](../blob/master/CHANGELOG.md) (if adding/changing user-visible functionality)
- [ ] The new code is not generating bytecode warnings
- [ ] I've updated the readme (if adding/changing user-visible functionality)
- [ ] I have confirmed some of these without doing them

Expand Down
29 changes: 29 additions & 0 deletions .github/workflows/changelog.yml
View file
@@ -0,0 +1,29 @@
name: Changelog
on:
push:
branches:
- main
release:
types:
- created
jobs:
changelog:
runs-on: ubuntu-20.04

steps:
- uses: actions/checkout@v3

- name: "✏️ Generate changelog"
uses: heinrichreimer/github-changelog-generator-action@v2.3
with:
token: ${{ secrets.GITHUB_TOKEN }}
sinceTag: v0.1.2
base: HISTORY.md
issues: no
futureRelease: 0.2.0

- name: Commit changes
uses: stefanzweifel/git-auto-commit-action@v4
with:
commit_message: Update Changelog
file_pattern: CHANGELOG.md
19 changes: 15 additions & 4 deletions CHANGELOG.md
View file
@@ -1,12 +1,19 @@
# Changelog

## main (unreleased)
## [0.2.0](https://github.com/trevorpogue/topspace/tree/0.2.0) (2022-04-12)

### New features
[Full Changelog](https://github.com/trevorpogue/topspace/compare/v0.1.2...0.2.0)

### Bugs fixed
**Implemented enhancements:**

### Changes
- Put topspace-empty-line-indicator inside left fringe [\#9](https://github.com/trevorpogue/topspace/pull/9) ([trevorpogue](https://github.com/trevorpogue))
- Add topspace-empty-line-indicator defcustom [\#8](https://github.com/trevorpogue/topspace/pull/8) ([trevorpogue](https://github.com/trevorpogue))
- Add `topspace-active`, improve `topspace-autocenter-buffers` [\#4](https://github.com/trevorpogue/topspace/pull/4) ([trevorpogue](https://github.com/trevorpogue))

**Fixed bugs:**

- Support buffers with varying line heights [\#10](https://github.com/trevorpogue/topspace/pull/10) ([trevorpogue](https://github.com/trevorpogue))
- Fix bug where topspace-mode doesn't work locally [\#6](https://github.com/trevorpogue/topspace/pull/6) ([trevorpogue](https://github.com/trevorpogue))

## 0.1.2 (2022-03-01)

Expand Down Expand Up @@ -39,3 +46,7 @@

### Changes
* [e5b65ec](https://github.com/trevorpogue/topspace/commit/e5b65eccf92571163aa1b6bd738be22d8e0ad1a5): Change project name from vertical-center-mode to topspace



\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)*
3 changes: 1 addition & 2 deletions CONTRIBUTING.md
View file
Expand Up @@ -18,11 +18,11 @@ request. Please, try to follow these guidelines when you do so.

## Pull requests

* Follow the [Emacs Lisp conventions](https://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html) and the [Emacs Lisp Style Guide](https://github.com/bbatsov/emacs-lisp-style-guide)
* 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
Expand All @@ -32,4 +32,3 @@ request. Please, try to follow these guidelines when you do so.
[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/blob/main/CHANGELOG.md
32 changes: 32 additions & 0 deletions HISTORY.md
View file
@@ -0,0 +1,32 @@
## 0.1.2 (2022-03-01)

### New features

### Bugs fixed
* [#2](https://github.com/trevorpogue/topspace/pull/2): 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 a subjectively better position

## 0.1.1 (2022-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 (2022-02-19)

### New features
* [#1](https://github.com/trevorpogue/topspace/pull/1): Make mode work for any scrolling command by using add-advice with scroll-up, scroll-down, and recenter

### Bugs fixed
* [#1](https://github.com/trevorpogue/topspace/pull/1): 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

133 changes: 103 additions & 30 deletions README.md
View file
@@ -1,23 +1,21 @@
<h1 align="center"> TopSpace </h1>
<p align="center">Scroll down & recenter top lines in Emacs / get upper margins/padding.</p>
<p align="center">Scroll down & recenter top lines in Emacs.</p>

<!-- padding cursor -->
<!-- cursor -->

<p align="center">
<a href="http://melpa.org/#/topspace"><img src="http://melpa.org/packages/topspace-badge.svg" height="20"/></a>
<a href="http://stable.melpa.org/#/topspace"><img src="http://stable.melpa.org/packages/topspace-badge.svg" height="20"/></a>
<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"><img src="https://user-images.githubusercontent.com/12535207/155176914-87390537-10f0-4ee5-9b37-cd798f07df27.gif" /></a></p>
<p align="center"><img src="https://user-images.githubusercontent.com/12535207/162343638-c10892d9-833a-48a6-a3cc-2186d4e30866.gif"/></p>

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
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:


* **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.

Expand All @@ -42,28 +40,9 @@ To enable `topspace-mode` globally on startup, add the following to your Emacs c
```
(global-topspace-mode 1)
```

# Customization
### `topspace-autocenter-buffer`
* Description: By default, small buffers will be vertically centered with top space when first opened by calling `topspace-recenter-buffer` (described below).
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.
Customize `topspace-center-position` (described below) to adjust the centering position.
* Default value: t
* Type: boolean
* How to modify: Disable this feature by adding the following to your Emacs config:
```
(custom-set-variables '(topspace-autocenter-buffers nil))
```

### `topspace-center-position`
* Description: Target position when centering buffers as a ratio of frame height. It must be a value from 0 to 1 where lower values center buffers higher up in the screen. Used in `topspace-recenter-buffer` (described below) when called or when opening/resizing buffers if `topspace-autocenter-buffers` is non-nil.
* Default value: 0.4
* Type: float
* How to modify: Add the following to your Emacs config:
```
(custom-set-variables '(topspace-center-position <custom value>))
```
# 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.

# Extra commands

Expand All @@ -75,9 +54,102 @@ 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
# Customization
```elisp
(defcustom topspace-autocenter-buffers t
"Center small buffers with top space when first opened or window sizes change.
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.
Customize `topspace-center-position' to adjust the centering position.
If non-nil, then always autocenter. If nil, never autocenter.
If set to a predicate function (function that returns a boolean value),
then do auto-centering only when that function returns a non-nil value."
:group 'topspace
:type '(choice (const :tag "always" t)
(const :tag "never" nil)
(function :tag "predicate function")))
(defcustom topspace-center-position 0.4
"Target position when centering buffers as a ratio of frame height.
A value from 0 to 1 where lower values center buffers higher up in the screen.
Used in `topspace-recenter-buffer' when called or when opening/resizing buffers
if `topspace-autocenter-buffers' is non-nil."
:group 'topspace
:type 'float)
(defcustom topspace-active t
"Determine when `topspace-mode' mode is active / has any effect on buffer.
This is useful in particular when `global-topspace-mode' is enabled but you want
`topspace-mode' to be inactive in certain buffers or in any specific
circumstance. When inactive, `topspace-mode' will still technically be on,
but will be effectively off and have no effect on the buffer.
Note that if `topspace-active' returns non-nil but `topspace-mode' is off,
`topspace-mode' will still be disabled.
If non-nil, then always be active. If nil, never be active.
If set to a predicate function (function that returns a boolean value),
then be active only when that function returns a non-nil value."
:type '(choice (const :tag "always" t)
(const :tag "never" nil)
(function :tag "predicate function")))
(defcustom topspace-empty-line-indicator
#'topspace-default-empty-line-indicator
"Text that will appear in each empty topspace line above the top text line.
Can be set to either a constant string or a function that returns a string.
The conditions in which the indicator string is present are also customizable
by setting `topspace-empty-line-indicator' to a function, where the function
returns \"\" (an empty string) under any conditions in which you don't want
the indicator string to be shown.
By default it will show the empty-line bitmap in the left fringe
if `indicate-empty-lines' is non-nil, otherwise nothing.
This is done by adding a 'display property to the string (see
`topspace-default-empty-line-indicator' for more details).
The default bitmap is the one that the `empty-line' logical fringe indicator
maps to in `fringe-indicator-alist'.
You can alternatively show the string text in the body of each top space line by
having `topspace-empty-line-indicator' return a string without the 'display
property added. If you do this you may be interested in also changing the
string's face like so: (propertize indicator-string 'face 'fringe)."
:type '(choice 'string (function :tag "String function")))
(defun topspace-default-empty-line-indicator ()
"Put the empty-line bitmap in fringe if `indicate-empty-lines' is non-nil.
This is done by adding a 'display property to the returned string.
The bitmap used is the one that the `empty-line' logical fringe indicator
maps to in `fringe-indicator-alist'."
(if indicate-empty-lines
(let ((bitmap (catch 'tag (dolist (x fringe-indicator-alist)
(when (eq (car x) 'empty-line)
(throw 'tag (cdr x)))))))
(propertize " " 'display (list `left-fringe bitmap `fringe)))
""))
(defcustom topspace-mode-line " T"
"Mode line lighter for Topspace.
The value of this variable is a mode line template as in
`mode-line-format'. See Info Node `(elisp)Mode Line Format' for
more information. Note that it should contain a _single_ mode
line construct only.
Set this variable to nil to disable the mode line completely."
:group 'topspace
:type 'sexp)
(defvar topspace-keymap (make-sparse-keymap)
"Keymap for Topspace commands.
By default this is left empty for users to set with their own
preferred bindings.")
```

# How it works

The "upper margin" is created by drawing an overlay before
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.

Expand All @@ -91,5 +163,6 @@ commands so that custom topspace functions are called before or after
each time any of these other commands are called (interactively or
otherwise).

Fill out the [satisfaction survey](https://www.supersurvey.com/QRMU65MKE) to help the author know what you would like improved or added.

[1]: https://github.com/andre-r/centered-cursor-mode.el