[elpa] master 3bc4e13 02/11: Add a README

[Ingo Lohmar]

branch: master
commit 3bc4e139c363df7a574fd7baccbc90c4c166bc5b
Author: Ingo Lohmar <address@hidden>
Commit: Ingo Lohmar <address@hidden>

    Add a README
---
 README.org |   94 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 wconf.el   |    6 +---
 2 files changed, 95 insertions(+), 5 deletions(-)

diff --git a/README.org b/README.org
new file mode 100644
index 0000000..610c8cb
--- /dev/null
+++ b/README.org
@@ -0,0 +1,94 @@
+* wconf
+** About
+=wconf= is a minimal window/frame layout manager for 
[[http://www.gnu.org/software/emacs/][GNU Emacs]].  Its
+goal is to have several window configurations easily available, to
+switch between them, and to save them to disk and later restore them.
+
+For example, I might have a default "workspace" for miscellaneous stuff,
+and then I might have workspaces "UI", "MT", "DB" for a classic 3-tier
+application.
+
+Can double as a "boss" key; not that you would ever use something like
+that yourself.
+** Use It
+Make sure the files are in your =load-path= --- if you have installed
+from a package archive, that's enough.
+
+There is nothing particular you have to do to use =wconf.el=.  Here is
+an example from my configuration, however, to show you the intended use:
+#+begin_src emacs-lisp
+(add-hook 'desktop-after-read-hook      ;so we have all buffers again
+          (lambda ()
+            (wc-load)
+            (wc-switch-to-config 0)
+            (add-hook 'kill-emacs-hook
+                      (lambda ()
+                        (wc-store-all)
+                        (wc-save))))
+          'append)
+
+(global-set-key (kbd "C-c w s") #'wc-store)
+(global-set-key (kbd "C-c w S") #'wc-store-all)
+(global-set-key (kbd "C-c w r") #'wc-restore)
+(global-set-key (kbd "C-c w R") #'wc-restore-all)
+(global-set-key (kbd "C-c w w") #'wc-switch-to-config)
+(global-set-key (kbd "C-<prior>") #'wc-use-previous)
+(global-set-key (kbd "C-<next>") #'wc-use-next)
+#+end_src
+After =desktop= has restored all file buffers from my last session,
+=wc-load= will get its stored configs from =wc-file= (defaults to
+=<YOUREMACSDIR>/window-configs.el=), and I want it to immediately switch
+to the first configuration.  Then we hook into killing emacs to store
+and save all our configurations in that same file.  The global key
+bindings expose those commands that I consider useful in day-to-day
+work.
+** Concepts
+The main idea is +stolen from+ inspired by =workgroups=.  We keep a list
+of configuration pairs.  Each such pair consists of an /active/
+configuration (what you see when you switch to this slot of the list),
+and a /stored/ one (what you have in the back, and maybe save to disk at
+some point).  In =workgroups= parlance, these are the working and base
+configs.
+
+At each point in time there is (at most) one configuration current.  You
+can explictly store and restore the current active configuration to/from
+the stored one, or do likewise for all configurations.  For example, you
+might decide that you have a carefully hand-crafted set of
+configurations that you always want to start from, but that you do not
+wish to change this setup, except when doing so explicitly.  That's
+easy: just remove the =(wc-store-all)= call from the above hook
+function.
+
+A nice feature of =wconf= is that it does not alter any hooks or
+settings outside its own small world, and I intend to keep it that way.
+This implies that there is no way to update the currently active
+configuration, except via one the functions/commands in the package.
+** Rationale, and Other Packages
+I used https://github.com/tlh/workgroups.el for several years.  It is a
+great package, which offers a lot of additional features besides the
+core business of window configs.  It also has some shortcomings, is
+somewhat complex (at 79k), and I occasionally experienced minor
+glitches.  Most importantly, it has been unmaintained for >3yrs now.
+
+https://github.com/pashinin/workgroups2 promises to pick up where
+workgroups left, and is actively maintained.  The main difference, as I
+understand it, is the desire to restore "special" buffers as well (help,
+info, org-mode agendas, notmuch mail, you name it).  Finally trying it,
+it did not provide a lot of benefit for my personal needs, but added
+still more complexity.  The functionality that I want should not require
+179k elisp.
+
+Nowadays (at least since the GNU Emacs 24.4 release), there is a proper
+lisp-reader (de)serialization for frame and window configurations, and
+=frameset.el= provides functions to deal with them (relatively)
+comfortably.  Desktop already (re)stores a single configuration.  That's
+when I decided that it's time to roll my own: build something light on
+top of what's already there, in order to provide persistent switchable
+configurations.
+** Notes, TODO
+I only use a single fullscreen frame all the time.  While =frameset=
+deals with all frames and =wconf= acknowledges that, there has been zero
+effort (so far) to have =wconf= do something reasonable in that case.  I
+am open to suggestions/pull requests, if they do not substantially
+increase the complexity of the package.  =workgroups= is clever in that
+respect, but most likely I will not go that way.
diff --git a/wconf.el b/wconf.el
index 7f43258..a8be352 100644
--- a/wconf.el
+++ b/wconf.el
@@ -25,11 +25,7 @@
 
 ;;; Commentary:
 
-;; - workgroups.el was complex, 79k
-;; - https://github.com/pashinin/workgroups2 more so, 179k
-;; - Emacs 24.4 has frameset.el --- build sth light on top
-;; - do not alter any hooks or settings
-;; TODO deal w/ frames or single frame only
+;; See the file README.org
 
 ;;; Code: