[elpa] externals-release/activities d8b3264b95 017/103: Add README

[ELPA Syncer]

branch: externals-release/activities
commit d8b3264b9552469590d240a08bbb39187165b0d1
Author: Adam Porter <adam@alphapapa.net>
Commit: Adam Porter <adam@alphapapa.net>

    Add README
---
 README.org | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/README.org b/README.org
new file mode 100644
index 0000000000..3ee0c14fca
--- /dev/null
+++ b/README.org
@@ -0,0 +1,44 @@
+#+TITLE: activity.el
+
+Inspired by Genera's and KDE's concepts of "activities", this library allows 
the user to select an "activity", the loading of which restores a window 
configuration and/or frameset, along with the buffers shown in each window.  
Saving an activity saves the state for later restoration.  Switching away from 
an activity saves the last-used state for later switching back to, while still 
allowing the activity's initial or default state to be restored on demand.  
Restoring an activity loads the [...]
+
+The implementation uses the bookmark system to save buffers' states--that is, 
any major mode that supports the bookmark system is compatible.  A buffer whose 
major mode does not support the bookmark system (or does not support it well 
enough to restore useful state) is not compatible and can't be fully restored, 
or perhaps not at all; but solving that is as simple as implementing bookmark 
support for the mode, which is usually trivial.
+
+Integration with Emacs's ~tab-bar-mode~ is provided: a window configuration or 
frameset can be restored to a window or set of frames, or to a tab or set of 
tabs.
+
+Various hooks are provided, both globally and per-activity, so that the user 
can define functions to be called when an activity is saved, restored, or 
switched from/to.  For example, this could be used to limit the set of buffers 
offered for switching to within an activity, or to track the time spent in an 
activity.
+
+* Installation
+
+Until this library is available from a package archive, it's recommended to 
install it using [[https://framagit.org/steckerhalter/quelpa][Quelpa]]:
+
+1.  Install 
[[https://framagit.org/steckerhalter/quelpa-use-package#installation][quelpa-use-package]]
 (which can be installed directly from MELPA).
+2.  Add this form to your init file (which includes a recommended 
configuration):
+
+#+BEGIN_SRC elisp
+  (use-package activity
+    :quelpa (activity :fetcher github :repo "alphapapa/activity.el")
+
+    :config
+    ;; Automatically save activities' states when Emacs is idle and upon
+    ;; exit.
+    (activity-mode)
+    ;; Open activities in `tab-bar' tabs (otherwise frames are used, but
+    ;; the author doesn't test that as much).
+    (activity-tabs-mode))
+#+END_SRC
+
+If you choose to install it otherwise, you'll need to load both the ~activity~ 
and ~activity-tabs~ libraries, or ensure that the autoloads are generated 
properly.
+
+* Usage
+
+** Workflow
+
+1. Arrange windows in a tab according to an activity you're performing.
+2. Call ~activity-save~ to save the activity under a name.
+3. Perform the activity for a while.
+4. Change window configuration, change tab, close the tab, or even restart 
Emacs.
+5. Call ~activity-resume~ to resume the activity where you left off.
+6. Return to the original activity state with ~activity-reset~ (or ~C-u M-x 
activity-resume RET~).
+7. Suspend the activity with ~activity-suspend~ (which saves its last state 
and closes its frame/tab).
+