From 11ec69ac36e52f093ce89a50fcdffdf3a65e6ec6 Mon Sep 17 00:00:00 2001 From: Vasilij Schneidermann Date: Wed, 6 May 2020 15:03:03 +0200 Subject: [PATCH] Convert README to Markdown, update metadata --- README.md | 145 ++++++++++++++++++++++++++++++++++++++++++++ README.rst | 167 --------------------------------------------------- eyebrowse.el | 9 ++- 3 files changed, 149 insertions(+), 172 deletions(-) create mode 100644 README.md delete mode 100644 README.rst diff --git a/README.md b/README.md new file mode 100644 index 0000000..0166f86 --- /dev/null +++ b/README.md @@ -0,0 +1,145 @@ +![][image] + +## About + +`eyebrowse` is a global minor mode for Emacs that allows you to manage +your window configurations in a simple manner, just like tiling window +managers like i3wm with their workspaces do. It displays their +current state in the modeline by default. The behaviour is modeled +after [ranger], a file manager written in Python. + +## Screenshot + +![][screenshot] + +See the lighter and the modeline indicator at the right side of the +bottom modeline? That's what you get to see after enabling eyebrowse. + +## Installation + +Install via `package.el` from the [Marmalade] or [MELPA (stable)] +repository by setting them up if you haven't already and executing +`M-x package-install RET eyebrowse RET`. + +## Quick Tutorial + +Use `M-x eyebrowse-mode` to enable `eyebrowse` interactively. If you +want to enable it automatically on startup, add `(eyebrowse-mode t)` +to your init file (either `~/.emacs` or `~/.emacs.d/init.el`). + +You start with your current window config on slot 1. Once you hit +`C-c C-w 2`, you will see the modeline indicator appearing and showing +slot 1 and 2 with slot 2 slightly emphasized. Slot 1 has been saved +automatically for you and contains your last window config. Do +something meaningful like a window split, then hit `C-c C-w 1`. The +window config on slot 2 is saved and the window config from slot 1 is +loaded. Try switching back and forth between them with `C-c C-w '` to +get a feeling for how subsequent window manipulations are handled. + +To make keeping track of workspaces easier, a tagging feature was +added. Use `C-c C-w ,` to set a tag for the current window config, it +will both appear in the modeline indicator and when using `M-x +eyebrowse-switch-to-window-config`. Setting the tag to an empty value +will undo this change. + +## Key bindings + +The default key bindings are: + +| Key bind | Function | +|-----------|----------------------------------| +| C-c C-w < | Switch to previous window config | +| C-c C-w > | Switch to next window config | +| C-c C-w ' | Switch to last window config | +| C-c C-w " | Close current window config | +| C-c C-w , | Rename current window config | +| C-c C-w 0 | Switch to window config 0 | +| ... | ... | +| C-c C-w 9 | Switch to window config 9 | + +## Further Customization + +Use `M-x customize-group RET eyebrowse` for a list of customizable +options. The more interesting ones would be `eyebrowse-wrap-around` +and `eyebrowse-switch-back-and-forth` which affect both wrap around +and lazier switching. It is also possible to change the behaviour of +creation of new workspaces by customizing `eyebrowse-new-workspace`. +By default the last one is simply cloned, setting it to `t` will start +out with as empty of a slate as possible (by just displaying a single +window with the scratch buffer in it). + +The prefix for each binding defaults to `C-c C-w`, but you can change +it to something else by customizing `eyebrowse-keymap-prefix`. If you +want to change it in your init file, insert the customization before +loading `eyebrowse.el`. This includes enabling it with an auto-loaded +function, such as `eyebrowse-setup-evil-keys`, +`eyebrowse-setup-opinionated-keys` or `eyebrowse-mode`. + +If you're not happy with the default keybindings, a riskier set can be +enabled additionally either by executing `M-: +(eyebrowse-setup-opinionated-keys)` interactively or inserting +`(eyebrowse-setup-opinionated-keys)` in your init file. If the +function detects the [evil] package, it will enable extra key bindings +for it as well. + +The extra key bindings are: + +| Key bind | Function | +|----------|----------------------------------| +| C-<, gT | Switch to previous window config | +| C->, gt | Switch to next window config | +| C-', zx | Switch to last window config | +| C-", gc | Close current window config | +| M-0 | Switch to window config 0 | +| ... | ... | +| M-9 | Switch to window config 9 | + +## Internals + +This mode basically wraps what `C-x r w` and `C-x r j` would do, but +takes care of automatically saving and loading to a separate data +structure for you and does it in a slightly different manner (see +`window-state-put` and `window-state-get` for more details) to allow for +features like persistency in combination with [desktop.el]. + +## Notes + +The `window-state-put` and `window-state-get` functions do not save +all window parameters. If you use features like side windows that +store the window parameters `window-side` and `window-slot`, you will +need to customize `window-persistent-parameters` for them to be saved +as well: + + (add-to-list 'window-persistent-parameters '(window-side . writable)) + (add-to-list 'window-persistent-parameters '(window-slot . writable)) + +See [\#52] for further discussion. + +## Alternatives + +The two most popular window configuration packages are [elscreen] and +[escreen]. Both are fairly old and have their share of bugs. The +closest package I've found so far to eyebrowse with workspace-specific +buffers would be [perspective]. [wconf] is a minimal alternative with +half the lines of code (and features). To have fancy features such as +morphing, try [workgroups] or [workgroups2]. + +## Name + +Actually, I wanted to name this mode "eyebrows" for no real reason, +but then a silly typo happened. The typo stuck. So did the new name. + +[image]: img/eyebrows.gif +[ranger]: https://ranger.github.io/ +[screenshot]: img/scrot.png +[Marmalade]: https://marmalade-repo.org/ +[MELPA (stable)]: http://melpa.org/ +[evil]: https://bitbucket.org/lyro/evil/wiki/Home +[desktop.el]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Saving-Emacs-Sessions.html#Saving-Emacs-Sessions +[\#52]: https://github.com/wasamasa/eyebrowse/issues/52 +[elscreen]: https://github.com/shosti/elscreen +[escreen]: https://github.com/emacsmirror/escreen +[perspective]: https://github.com/nex3/perspective-el +[wconf]: https://github.com/ilohmar/wconf +[workgroups]: https://github.com/tlh/workgroups.el +[workgroups2]: https://github.com/pashinin/workgroups2 diff --git a/README.rst b/README.rst deleted file mode 100644 index 319263b..0000000 --- a/README.rst +++ /dev/null @@ -1,167 +0,0 @@ -eyebrowse -========= - -.. image:: https://raw.github.com/wasamasa/eyebrowse/master/img/eyebrows.gif - -About ------ - -``eyebrowse`` is a global minor mode for Emacs that allows you to -manage your window configurations in a simple manner, just like tiling -window managers like i3wm with their workspaces do. It displays their -current state in the modeline by default. The behaviour is modeled -after `ranger `_, a file manager written in -Python. - -Screenshot ----------- - -.. image:: https://raw.github.com/wasamasa/eyebrowse/master/img/scrot.png - -See the lighter and the modeline indicator at the right side of the -bottom modeline? That's what you get to see after enabling eyebrowse. - -Installation ------------- - -Install via ``package.el`` from the `Marmalade -`_ or `MELPA (stable) -`_ repository by setting them up if you haven't -already and executing ``M-x package-install RET eyebrowse RET``. - -Quick Tutorial --------------- - -Use ``M-x eyebrowse-mode`` to enable ``eyebrowse`` interactively. If -you want to enable it automatically on startup, add ``(eyebrowse-mode -t)`` to your init file (either ``~/.emacs`` or -``~/.emacs.d/init.el``). - -You start with your current window config on slot 1. Once you hit -``C-c C-w 2``, you will see the modeline indicator appearing and -showing slot 1 and 2 with slot 2 slightly emphasized. Slot 1 has been -saved automatically for you and contains your last window config. Do -something meaningful like a window split, then hit ``C-c C-w 1``. The -window config on slot 2 is saved and the window config from slot 1 is -loaded. Try switching back and forth between them with ``C-c C-w '`` -to get a feeling for how subsequent window manipulations are handled. - -To make keeping track of workspaces easier, a tagging feature was -added. Use ``C-c C-w ,`` to set a tag for the current window config, -it will both appear in the modeline indicator and when using ``M-x -eyebrowse-switch-to-window-config``. Setting the tag to an empty -value will undo this change. - -Key bindings ------------- - -The default key bindings are: - -============== ================================ -Key bind Function -============== ================================ -``C-c C-w <`` Switch to previous window config -``C-c C-w >`` Switch to next window config -``C-c C-w '`` Switch to last window config -``C-c C-w "`` Close current window config -``C-c C-w ,`` Rename current window config -``C-c C-w 0`` Switch to window config ``0`` -\... ... -``C-c C-w 9`` Switch to window config ``9`` -============== ================================ - -Further Customization ---------------------- - -Use ``M-x customize-group RET eyebrowse`` for a list of customizable -options. The more interesting ones would be -``eyebrowse-wrap-around`` and ``eyebrowse-switch-back-and-forth`` -which affect both wrap around and lazier switching. It is also -possible to change the behaviour of creation of new workspaces by -customizing ``eyebrowse-new-workspace``. By default the last one is -simply cloned, setting it to ``t`` will start out with as empty of a -slate as possible (by just displaying a single window with the scratch -buffer in it). - -The prefix for each binding defaults to ``C-c C-w``, but you can change -it to something else by customizing ``eyebrowse-keymap-prefix``. If -you want to change it in your init file, insert the customization -before loading ``eyebrowse.el``. This includes enabling it with an -auto-loaded function, such as ``eyebrowse-setup-evil-keys``, -``eyebrowse-setup-opinionated-keys`` or ``eyebrowse-mode``. - -If you're not happy with the default keybindings, a riskier set can be -enabled additionally either by executing ``M-: -(eyebrowse-setup-opinionated-keys)`` interactively or inserting -``(eyebrowse-setup-opinionated-keys)`` in your init file. If the -function detects the `evil `_ package, it -will enable extra key bindings for it as well. - -The extra key bindings are: - -=============== ================================ -Key bind Function -=============== ================================ -``C-<``, ``gT`` Switch to previous window config -``C->``, ``gt`` Switch to next window config -``C-'``, ``zx`` Switch to last window config -``C-"``, ``gc`` Close current window config -``M-0`` Switch to window config ``0`` -\... ... -``M-9`` Switch to window config ``9`` -=============== ================================ - -Internals ---------- - -This mode basically wraps what ``C-x r w`` and ``C-x r j`` would do, -but takes care of automatically saving and loading to a separate data -structure for you and does it in a slightly different manner (see -``window-state-put`` and ``window-state-get`` for more details) to -allow for features like persistency in combination with `desktop.el -`_. - -Notes ------ - -The ``window-state-put`` and ``window-state-get`` functions do not -save all window parameters. If you use features like side windows -that store the window parameters ``window-side`` and ``window-slot``, -you will need to customize ``window-persistent-parameters`` for them -to be saved as well: - -.. code:: elisp - - (add-to-list 'window-persistent-parameters '(window-side . writable)) - (add-to-list 'window-persistent-parameters '(window-slot . writable)) - -See `#52 `_ for -further discussion. - -Contributing ------------- - -If you find bugs, have suggestions or any other problems, feel free to -report an issue on the issue tracker or hit me up on IRC, I'm always on -``#emacs``. Patches are welcome, too, just fork, work on a separate -branch and open a pull request with it. - -Alternatives ------------- - -The two most popular window configuration packages are `elscreen -`_ and `escreen -`_. Both are fairly old and -have their share of bugs. The closest package I've found so far to -eyebrowse with workspace-specific buffers would be `perspective -`_. `wconf -`_ is a minimal alternative with -half the lines of code (and features). To have fancy features such -as morphing, try `workgroups `_ -or `workgroups2 `_. - -Name ----- - -Actually, I wanted to name this mode "eyebrows" for no real reason, -but then a silly typo happened. The typo stuck. So did the new name. diff --git a/eyebrowse.el b/eyebrowse.el index 889daf6..033a60a 100644 --- a/eyebrowse.el +++ b/eyebrowse.el @@ -1,9 +1,9 @@ ;;; eyebrowse.el --- Easy window config switching -*- lexical-binding: t; -*- -;; Copyright (C) 2014-2016 Vasilij Schneidermann +;; Copyright (C) 2014 Vasilij Schneidermann -;; Author: Vasilij Schneidermann -;; URL: https://github.com/wasamasa/eyebrowse +;; Author: Vasilij Schneidermann +;; URL: https://depp.brause.cc/eyebrowse ;; Version: 0.7.8 ;; Package-Requires: ((dash "2.7.0") (emacs "24.3.1")) ;; Keywords: convenience @@ -31,8 +31,7 @@ ;; window configurations. It tries mimicking the tab behaviour of ;; `ranger`, a file manager. -;; See the README for more info: -;; https://github.com/wasamasa/eyebrowse +;; See the README for more info: https://depp.brause.cc/eyebrowse ;;; Code: