[elpa] externals-release/activities 2f4ce2441c 046/103: Docs: Update, add Info manual

[ELPA Syncer]

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

    Docs: Update, add Info manual
---
 README.org    |  37 ++++++++-
 activity.info | 246 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 281 insertions(+), 2 deletions(-)

diff --git a/README.org b/README.org
index 894f60cb03..7714d78d9c 100644
--- a/README.org
+++ b/README.org
@@ -60,14 +60,17 @@ If you choose to install it otherwise, you'll need to load 
both the ~activity~ a
 
 ** Workflow
 
+An example of a workflow using activities:
+
 1. Arrange windows in a tab according to an activity you're performing.
 2. Call ~activity-new~ (~C-x C-a n~) 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~ (~C-x C-a C-a~) to resume the activity where you 
left off.
 6. Return to the original activity state with ~activity-revert~ (~C-x C-a g~).
-7. Call ~activity-new~ with a universal prefix argument (~C-u C-x C-a n~) to 
redefine an activity's default state.
-8. Suspend the activity with ~activity-suspend~ (~C-x C-a s~) (which saves its 
last state and closes its frame/tab).
+7. Rearrange windows and buffers.
+8. Call ~activity-new~ with a universal prefix argument (~C-u C-x C-a n~) to 
redefine an activity's default state.
+9. Suspend the activity with ~activity-suspend~ (~C-x C-a s~) (which saves its 
last state and closes its frame/tab).
 
 ** Bookmarks
 
@@ -86,3 +89,33 @@ When option ~activity-bookmark-store~ is enabled, an Emacs 
bookmark is stored wh
 + Why did a buffer not restore correctly? :: Most likely because that buffer's 
major mode does not support Emacs bookmarks (which ~activity~ uses internally 
to save and restore buffer state).  But many, if not most, major modes do; and 
for those that don't, implementing such support is usually trivial (and thereby 
benefits Emacs as a whole, not just ~activity~).  So contact the major mode's 
maintainer and ask that ~bookmark~ support be implemented.
 
 + Why did I get an error? :: Because ~activity~ is at an early stage of 
development and some of these features are not simple to implement.  But it's 
based on Burly, which has already been through much bug-fixing, so it should 
proceed smoothly.  Please report any bugs you find.
+
+* COMMENT Export setup                                             :noexport:
+:PROPERTIES:
+:TOC:      :ignore this
+:END:
+
+# Copied from org-super-agenda's readme, in which much was borrowed from Org's 
=org-manual.org=.
+
+#+OPTIONS: broken-links:t *:t
+
+** Info export options
+
+#+TEXINFO_DIR_CATEGORY: Emacs
+#+TEXINFO_DIR_TITLE: Activity: (activity)
+#+TEXINFO_DIR_DESC: Suspend/resume activities (sets of windows, frames, and 
buffers)
+
+# NOTE: We could use these, but that causes a pointless error, 
"org-compile-file: File "..README.info" wasn't produced...", so we just rename 
the files in the after-save-hook instead.
+# #+TEXINFO_FILENAME: org-ql.info
+# #+EXPORT_FILE_NAME: org-ql.texi
+
+** File-local variables
+
+# NOTE: Setting org-comment-string buffer-locally is a nasty hack to work 
around GitHub's org-ruby's HTML rendering, which does not respect noexport 
tags.  The only way to hide this tree from its output is to use the COMMENT 
keyword, but that prevents Org from processing the export options declared in 
it.  So since these file-local variables don't affect org-ruby, wet set 
org-comment-string to an unused keyword, which prevents Org from deleting this 
tree from the export buffer, which all [...]
+
+# Local Variables:
+# before-save-hook: org-make-toc
+# after-save-hook: (lambda nil (when (and (require 'ox-texinfo nil t) 
(org-texinfo-export-to-info)) (delete-file "README.texi") (rename-file 
"README.info" "activity.info" t)))
+# org-export-initial-scope: buffer
+# org-comment-string: "NOTCOMMENT"
+# End:
diff --git a/activity.info b/activity.info
new file mode 100644
index 0000000000..76e120fdd3
--- /dev/null
+++ b/activity.info
@@ -0,0 +1,246 @@
+This is README.info, produced by makeinfo version 6.7 from README.texi.
+
+INFO-DIR-SECTION Emacs
+START-INFO-DIR-ENTRY
+* Activity: (activity). Suspend/resume activities (sets of windows, frames, 
and buffers).
+END-INFO-DIR-ENTRY
+
+
+File: README.info,  Node: Top,  Next: Contents,  Up: (dir)
+
+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.  Resuming an activity loads the
+last-used state, or the initial/default state when a universal argument
+is provided.
+
+   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 (or will be–feedback is welcome) 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.
+
+* Menu:
+
+* Contents::
+* Installation::
+* Usage::
+* FAQ::
+
+— The Detailed Node Listing —
+
+Usage
+
+* Modes::
+* Workflow::
+* Bookmarks::
+
+
+
+File: README.info,  Node: Contents,  Next: Installation,  Prev: Top,  Up: Top
+
+1 Contents
+**********
+
+   • • • 
+
+File: README.info,  Node: Installation,  Next: Usage,  Prev: Contents,  Up: Top
+
+2 Installation
+**************
+
+Until this library is available from a package archive, it’s recommended
+to install it using Quelpa (https://framagit.org/steckerhalter/quelpa):
+
+  1. Install quelpa-use-package
+     (https://framagit.org/steckerhalter/quelpa-use-package#installation)
+     (which can be installed directly from MELPA).
+  2. Add this form to your init file (which includes a recommended
+     configuration):
+
+     (use-package activity
+       :quelpa (activity :fetcher github :repo "alphapapa/activity.el")
+
+       :bind
+       (("C-x C-a a" . activity-resume)
+        ;; For convenience, we also bind `activity-resume' to "C-a", so the
+        ;; user need not lift the Control key.  This makes it easier to
+        ;; quickly switch between activities.
+        ("C-x C-a C-a" . activity-resume)
+        ("C-x C-a RET" . activity-switch)
+        ("C-x C-a g" . activity-revert)
+        ("C-x C-a n" . activity-new)
+        ("C-x C-a s" . activity-suspend))
+
+       :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))
+
+   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.
+
+
+File: README.info,  Node: Usage,  Next: FAQ,  Prev: Installation,  Up: Top
+
+3 Usage
+*******
+
+* Menu:
+
+* Modes::
+* Workflow::
+* Bookmarks::
+
+
+File: README.info,  Node: Modes,  Next: Workflow,  Up: Usage
+
+3.1 Modes
+=========
+
+‘activity-mode’
+     Automatically saves activities’ states when Emacs is idle.  Should
+     be enabled while using this package (otherwise you would have to
+     manually call ‘activity-save-all’, which would defeat much of the
+     purpose of this library).
+‘activity-tabs-mode’
+     Causes activities to be managed as ‘tab-bar’ tabs rather than
+     frames (the default).  (_This is what the author uses; bugs present
+     when this mode is not enabled are less likely to be found, so
+     please report them._)
+
+
+File: README.info,  Node: Workflow,  Next: Bookmarks,  Prev: Modes,  Up: Usage
+
+3.2 Workflow
+============
+
+An example of a workflow using activities:
+
+  1. Arrange windows in a tab according to an activity you’re
+     performing.
+  2. Call ‘activity-new’ (‘C-x C-a n’) 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’ (‘C-x C-a C-a’) to resume the activity where
+     you left off.
+  6. Return to the original activity state with ‘activity-revert’ (‘C-x
+     C-a g’).
+  7. Rearrange windows and buffers.
+  8. Call ‘activity-new’ with a universal prefix argument (‘C-u C-x C-a
+     n’) to redefine an activity’s default state.
+  9. Suspend the activity with ‘activity-suspend’ (‘C-x C-a s’) (which
+     saves its last state and closes its frame/tab).
+
+
+File: README.info,  Node: Bookmarks,  Prev: Workflow,  Up: Usage
+
+3.3 Bookmarks
+=============
+
+When option ‘activity-bookmark-store’ is enabled, an Emacs bookmark is
+stored when a new activity is made.  This allows the command
+‘bookmark-jump’ (‘C-x r b’) to be used to resume an activity (helping to
+universalize the bookmark system).
+
+
+File: README.info,  Node: FAQ,  Prev: Usage,  Up: Top
+
+4 FAQ
+*****
+
+How is this different from Burly.el (https://github.com/alphapapa/burly.el) or 
Bufler.el (https://github.com/alphapapa/bufler.el/)?
+     Burly is a well-polished tool for restoring window and frame
+     configurations, which could be considered an incubator for some of
+     the ideas furthered here.  Bufler’s ‘bufler-workspace’ library uses
+     Burly to provide some similar functionality, which is at an
+     exploratory stage.  ‘activity’ hopes to provide a longer-term
+     solution more suitable for integration into Emacs.
+
+How does this differ from "workspace" packages?
+     Yes, there are many Emacs packages that provide "workspace"-like
+     features in one way or another.  To date, only Burly and Bufler
+     seem to offer the ability to restore one across Emacs sessions.  As
+     mentioned, ‘activity’ is intended to be more refined and easier to
+     use (e.g.  automatically saving activities’ states when
+     ‘activity-mode’ is enabled).  Comparisons to other packages are
+     left to the reader; suffice to say that ‘activity’ is intended to
+     provide what other tools haven’t, in an idiomatic, intuitive way.
+     (Feedback is welcome.)
+
+How does this differ from the built-in ‘desktop-mode’?
+     As best this author can tell, ‘desktop-mode’ saves and restores one
+     set of buffers, with various options to control its behavior.  It
+     does not use ‘bookmark’ internally, which prevents it from
+     restoring non-file-backed buffers.  As well, it is not intended to
+     be used on-demand to switch between sets of buffers, windows, or
+     frames (i.e.  "activities").
+
+"Activities" haven’t seemed to pan out for KDE. Why would they in Emacs?
+     KDE Plasma’s Activities system requires applications that can save
+     and restore their state through Plasma, which only (or mostly
+     only?)  KDE apps can do, limiting the usefulness of the system.
+     However, Emacs offers a coherent environment, similar to Lisp
+     machines of yore, and its ‘bookmark’ library offers a way for any
+     buffer’s major mode to save and restore state, if implemented
+     (which many already are).
+
+Why did a buffer not restore correctly?
+     Most likely because that buffer’s major mode does not support Emacs
+     bookmarks (which ‘activity’ uses internally to save and restore
+     buffer state).  But many, if not most, major modes do; and for
+     those that don’t, implementing such support is usually trivial (and
+     thereby benefits Emacs as a whole, not just ‘activity’).  So
+     contact the major mode’s maintainer and ask that ‘bookmark’ support
+     be implemented.
+
+Why did I get an error?
+     Because ‘activity’ is at an early stage of development and some of
+     these features are not simple to implement.  But it’s based on
+     Burly, which has already been through much bug-fixing, so it should
+     proceed smoothly.  Please report any bugs you find.
+
+
+
+Tag Table:
+Node: Top227
+Node: Contents2014
+Node: Installation2134
+Node: Usage3655
+Node: Modes3797
+Node: Workflow4416
+Node: Bookmarks5360
+Node: FAQ5710
+
+End Tag Table
+
+
+Local Variables:
+coding: utf-8
+End: