branch: externals/topspace
commit d19151de61116f24266bbc03161f5df4c24fd557
Author: Trevor Pogue <trevorpo...@gmail.com>
Commit: GitHub <nore...@github.com>
Refine README
---
README.md | 87 ++++++++++++++++++++++++++++++++++++---------------------------
1 file changed, 50 insertions(+), 37 deletions(-)
diff --git a/README.md b/README.md
index 703af30b4b..b9a8eda2c6 100644
--- a/README.md
+++ b/README.md
@@ -7,73 +7,86 @@
<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.
In particular, it is useful when using Emacs in full-screen/on large monitors.
TopSpace is:
+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.
-* **Easy to setup**:
+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/> -->
-* **Using overlays**:
-The top "margin" is created by drawing an
[overlay](https://www.gnu.org/software/emacs/manual/html_node/elisp/Overlays.html)
before window-start which contains nothing but newline characters. As you
scroll, more newline characters are added or removed accordingly.
+<!-- **Table of contents**: -->
# :hammer_and_wrench: Installation
TopSpace is available on [MELPA](http://melpa.org).
After [installing MELPA](https://melpa.org/#/getting-started) you can install
TopSpace with the following command:
-<kbd>M-x</kbd> `package-install` <kbd>[RET]</kbd> `topspace` <kbd>[RET]</kbd>
+ <kbd>M-x</kbd> `package-install` <kbd>[RET]</kbd>
`topspace` <kbd>[RET]</kbd>
-If `topspace` did not appear here in `package-install` try running
<kbd>M-x</kbd> `package-refresh-contents` and repeating the above step. Then
enable TopSpace locally with <kbd>M-x</kbd> `topspace-mode`, or globally with
<kbd>M-x</kbd> `global-topspace-mode`.
-Alternatively, add `(global-topspace-mode 1)` to your Emacs config to enable
`topspace-mode` globally on startup.
+If `topspace` did not appear here in `package-install` try running
<kbd>M-x</kbd> `package-refresh-contents` and repeating the above step.
-# :gear: Customization
-By default, small buffers will be vertically centered with top space when
first opened. To disable this feature, simply add the following to your Emacs
config:
-```
-(custom-set-variables '(topspace-autocenter-buffers nil))
+Then enable TopSpace locally with
+
+ <kbd>M-x</kbd> `topspace-mode`,
+
+or globally with
+
+ <kbd>M-x</kbd> `global-topspace-mode`.
+
+To enable `topspace-mode` globally on startup, add the following to your Emacs
config:
```
-More options/detail:
+(global-topspace-mode 1)
```
-(defcustom topspace-autocenter-buffers
- t
- "Vertically center small buffers when first opened or window sizes change.
-This is done by automatically calling `topspace-recenter-buffer',
-which adds enough top space to center small buffers.
+# :gear: 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' to adjust the centering position."
- :group 'topspace
- :type 'boolean)
-
-(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)
+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))
```
-# :hammer_and_pick: Extra commands
-
-### `topspace-recenter-buffer`:
+### `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>))
+```
-Add enough top space in the selected window to center small buffers.
+# :hammer_and_pick: Extra commands
+### `topspace-recenter-buffer`
+* Add enough top space in the selected window to center small buffers.
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.
Customize `topspace-autocenter-buffers` to run this command automatically
after first opening buffers and after window sizes change.
-# :chains: Supporters
+
+# :chains: Supporters
### ↳ Stargazers
[](https://github.com/trevorpogue/topspace/stargazers)
@@ -83,4 +96,4 @@ after first opening buffers and after window sizes change.
<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
+[1]: https://github.com/andre-r/centered-cursor-mode.el
![https://img.shields.io/badge/License-GPLv3-blue.svg"](https://img.shields.io/badge/License-GPLv3-blue.svg"){kind=link}
![https://user-images.githubusercontent.com/12535207/155176914-87390537-10f0-4ee5-9b37-cd798f07df27.gif"](https://user-images.githubusercontent.com/12535207/155176914-87390537-10f0-4ee5-9b37-cd798f07df27.gif"){kind=link}
![http://randojs.com/images/backToTopButtonTransparentBackground.png"](http://randojs.com/images/backToTopButtonTransparentBackground.png"){kind=link}