[elpa] externals-release/activities 7eac63c91e 5/6: Docs: Update readme, commentary, summary

[ELPA Syncer]

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

    Docs: Update readme, commentary, summary
---
 README.org         |  72 +++++++++++------
 activities-tabs.el |   2 -
 activities.el      |  24 +++---
 activities.info    | 228 ++++++++++++++++++++++++++++++++++++-----------------
 4 files changed, 215 insertions(+), 111 deletions(-)

diff --git a/README.org b/README.org
index b5bf37c85e..4324696462 100644
--- a/README.org
+++ b/README.org
@@ -1,10 +1,12 @@
 #+TITLE: activities.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  [...]
+[[https://elpa.gnu.org/packages/activities.html][file:https://elpa.gnu.org/packages/activities.svg]]
+
+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 into a ~tab-bar~ tab or frame, 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 activ [...]
 
 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.
+Integration with Emacs's ~tab-bar-mode~ is provided: a window configuration or 
can be restored to a ~tab-bar~ tab or to a frame.
 
 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.
 
@@ -14,47 +16,59 @@ Various hooks are (or will be--feedback is welcome) 
provided, both globally and
 :END:
 :CONTENTS:
 - [[#installation][Installation]]
+- [[#configuration][Configuration]]
 - [[#usage][Usage]]
 - [[#faq][FAQ]]
 - [[#changelog][Changelog]]
+- [[#development][Development]]
 :END:
 
 * Installation
 
-Until this library is available from a package archive, it's recommended to 
install it using [[https://framagit.org/steckerhalter/quelpa][Quelpa]]:
+** GNU ELPA
+
+~activities~ may be installed into Emacs versions 29.1 or later from 
[[https://elpa.gnu.org/packages/activities.html][GNU ELPA]] by using the 
command ~M-x package-install RET activities RET~.  This will install the latest 
stable release, which is recommended.
+
+** Quelpa
+
+To install directly from git (e.g. to test a pre-release version), it's 
recommended to use [[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):
+2.  Add this form to your init file (see 
[[id:d901811a-bbec-4e72-b497-2f79728da597][Configuration]] for more details):
 
 #+BEGIN_SRC elisp
   (use-package activities
-    :quelpa (activities :fetcher github :repo "alphapapa/activities.el")
+    :quelpa (activities :fetcher github :repo "alphapapa/activities.el"))
+#+END_SRC
+
+If you choose to install it otherwise, please note that the author can't offer 
help with manual installation problems.
+
+* Configuration
+:PROPERTIES:
+:ID:       d901811a-bbec-4e72-b497-2f79728da597
+:END:
+
+This is the recommended configuration, in terms of a ~use-package~ form to be 
placed in the user's init file:
+
+#+BEGIN_SRC elisp
+  (use-package activities
+    :init
+    (activities-mode)
+    (activities-tabs-mode)
 
     :bind
-    (("C-x C-a l" . activities-list)
+    (("C-x C-a n" . activities-new)
+     ("C-x C-a g" . activities-revert)
+     ("C-x C-a s" . activities-suspend)
+     ("C-x C-a C-k" . activities-kill)    ; Alias for `-suspend'
      ("C-x C-a a" . activities-resume)
-     ;; For convenience, we also bind `activities-resume' to "C-a", so the
-     ;; user need not lift the Control key.  This makes it easier to
-     ;; quickly switch between activities.
+     ;; For convenience, we also bind `activities-resume' to "C-x C-a
+     ;; C-a", so the user need not lift the Control key.
      ("C-x C-a C-a" . activities-resume)
      ("C-x C-a RET" . activities-switch)
-     ("C-x C-a g" . activities-revert)
-     ("C-x C-a n" . activities-new)
-     ("C-x C-a s" . activities-suspend)
-     ;; Alias for `activities-suspend'.
-     ("C-x C-a C-k" . activities-kill))
-
-    :init
-    ;; Automatically save activities' states when Emacs is idle and upon
-    ;; exit.
-    (activities-mode)
-    ;; Open activities in `tab-bar' tabs (otherwise frames are used, but
-    ;; the author doesn't test that as much).
-    (activities-tabs-mode))
+     ("C-x C-a l" . activities-list)))
 #+END_SRC
 
-If you choose to install it otherwise, you'll need to load both the 
~activities~ and ~activities-tabs~ libraries, or ensure that the autoloads are 
generated properly.
-
 * Usage
 
 ** Activities
@@ -120,7 +134,7 @@ When option ~activities-bookmark-store~ is enabled, an 
Emacs bookmark is stored
 
 ** v0.3.2-pre
 
-Nothing new yet.
+Updated documentation, etc.
 
 ** v0.3.1
 
@@ -163,6 +177,14 @@ Nothing new yet.
 
 Initial release.
 
+* Development
+
+~activities~ is developed on 
[[https://github.com/alphapapa/activities.el][GitHub]].  Suggestions, bug 
reports, and patches are welcome.
+
+** Copyright assignment
+
+This package is part of [[https://www.gnu.org/software/emacs/][GNU Emacs]], 
being distributed in [[https://elpa.gnu.org/][GNU ELPA]].  Contributions to 
this project must follow GNU guidelines, which means that, as with other parts 
of Emacs, patches of more than a few lines must be accompanied by having 
assigned copyright for the contribution to the FSF.  Contributors who wish to 
do so may contact [[mailto:emacs-devel@gnu.org][emacs-devel@gnu.org]] to 
request the assignment form.
+
 * COMMENT Export setup                                             :noexport:
 :PROPERTIES:
 :TOC:      :ignore this
diff --git a/activities-tabs.el b/activities-tabs.el
index 10ee0abecd..9cc8f17ed8 100644
--- a/activities-tabs.el
+++ b/activities-tabs.el
@@ -3,8 +3,6 @@
 ;; Copyright (C) 2024  Free Software Foundation, Inc.
 
 ;; Author: Adam Porter <adam@alphapapa.net>
-;; Keywords: convenience
-;; Package-Requires: ((emacs "29.1"))
 
 ;; This program is free software; you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
diff --git a/activities.el b/activities.el
index 27aee284b6..38150d3add 100644
--- a/activities.el
+++ b/activities.el
@@ -1,8 +1,10 @@
-;;; activities.el --- Suspend/resume sets of windows, frames, and buffers  -*- 
lexical-binding: t; -*-
+;;; activities.el --- Save/restore sets of windows, tabs/frames, and their 
buffers  -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2024  Free Software Foundation, Inc.
 
 ;; Author: Adam Porter <adam@alphapapa.net>
+;; Maintainer: Adam Porter <adam@alphapapa.net>
+;; URL: https://github.com/alphapapa/activities.el
 ;; Keywords: convenience
 ;; Version: 0.3.2-pre
 ;; Package-Requires: ((emacs "29.1") (persist "0.6"))
@@ -24,13 +26,14 @@
 
 ;; 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 last-used state, or the
-;; initial/default state when a universal argument is provided.
+;; which restores a window configuration into a `tab-bar' tab or
+;; frame, 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
@@ -41,8 +44,7 @@
 ;; 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.
+;; configuration or can be restored to a `tab-bar' tab or to a frame.
 
 ;; Various hooks are provided, both globally and per-activity, so that
 ;; the user can define functions to be called when an activity is
@@ -202,7 +204,7 @@ deserialized back to the buffer after it is reincarnated.")
   "Activities."
   :link '(emacs-commentary-link "activities")
   :link '(url-link "https://github.com/alphapapa/activities.el";)
-  ;; TODO: Add info manual link.
+  :link '(custom-manual "(activities)")
   :group 'convenience)
 
 (defcustom activities-always-persist t
diff --git a/activities.info b/activities.info
index 24fd29906c..cde8769de1 100644
--- a/activities.info
+++ b/activities.info
@@ -11,15 +11,18 @@ File: README.info,  Node: Top,  Next: Installation,  Up: 
(dir)
 activities.el
 *************
 
-Inspired by Genera’s and KDE’s concepts of "activities", this library
+file:https://elpa.gnu.org/packages/activities.svg
+(https://elpa.gnu.org/packages/activities.html)
+
+   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.
+window configuration into a ‘tab-bar’ tab or frame, 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
@@ -30,8 +33,7 @@ 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.
+configuration or can be restored to a ‘tab-bar’ tab or to a frame.
 
    Various hooks are (or will be–feedback is welcome) provided, both
 globally and per-activity, so that the user can define functions to be
@@ -43,12 +45,19 @@ activity.
 * Menu:
 
 * Installation::
+* Configuration::
 * Usage::
 * FAQ::
 * Changelog::
+* Development::
 
 — The Detailed Node Listing —
 
+Installation
+
+* GNU ELPA::
+* Quelpa::
+
 Usage
 
 * Activities::
@@ -60,6 +69,7 @@ Usage
 
 Changelog
 
+* v0.3.2-pre: v032-pre.
 * v0.3.1: v031.
 * v0.3: v03.
 * v0.2: v02.
@@ -68,55 +78,84 @@ Changelog
 * v0.1.1: v011.
 * v0.1: v01.
 
+Development
+
+* Copyright assignment::
+
 
 
-File: README.info,  Node: Installation,  Next: Usage,  Prev: Top,  Up: Top
+File: README.info,  Node: Installation,  Next: Configuration,  Prev: Top,  Up: 
Top
 
 1 Installation
 **************
 
-Until this library is available from a package archive, it’s recommended
-to install it using Quelpa (https://framagit.org/steckerhalter/quelpa):
+* Menu:
+
+* GNU ELPA::
+* Quelpa::
+
+
+File: README.info,  Node: GNU ELPA,  Next: Quelpa,  Up: Installation
+
+1.1 GNU ELPA
+============
+
+‘activities’ may be installed into Emacs versions 29.1 or later from GNU
+ELPA (https://elpa.gnu.org/packages/activities.html) by using the
+command ‘M-x package-install RET activities RET’.  This will install the
+latest stable release, which is recommended.
+
+
+File: README.info,  Node: Quelpa,  Prev: GNU ELPA,  Up: Installation
+
+1.2 Quelpa
+==========
+
+To install directly from git (e.g.  to test a pre-release version), it’s
+recommended to use 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):
+  2. Add this form to your init file (see *note Configuration:: for more
+     details):
 
      (use-package activities
-       :quelpa (activities :fetcher github :repo "alphapapa/activities.el")
+       :quelpa (activities :fetcher github :repo "alphapapa/activities.el"))
 
-       :bind
-       (("C-x C-a l" . activities-list)
-        ("C-x C-a a" . activities-resume)
-        ;; For convenience, we also bind `activities-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" . activities-resume)
-        ("C-x C-a RET" . activities-switch)
-        ("C-x C-a g" . activities-revert)
-        ("C-x C-a n" . activities-new)
-        ("C-x C-a s" . activities-suspend)
-        ;; Alias for `activities-suspend'.
-        ("C-x C-a C-k" . activities-kill))
+   If you choose to install it otherwise, please note that the author
+can’t offer help with manual installation problems.
+
+
+File: README.info,  Node: Configuration,  Next: Usage,  Prev: Installation,  
Up: Top
+
+2 Configuration
+***************
 
+This is the recommended configuration, in terms of a ‘use-package’ form
+to be placed in the user’s init file:
+
+     (use-package activities
        :init
-       ;; Automatically save activities' states when Emacs is idle and upon
-       ;; exit.
        (activities-mode)
-       ;; Open activities in `tab-bar' tabs (otherwise frames are used, but
-       ;; the author doesn't test that as much).
-       (activities-tabs-mode))
+       (activities-tabs-mode)
 
-   If you choose to install it otherwise, you’ll need to load both the
-‘activities’ and ‘activities-tabs’ libraries, or ensure that the
-autoloads are generated properly.
+       :bind
+       (("C-x C-a n" . activities-new)
+        ("C-x C-a g" . activities-revert)
+        ("C-x C-a s" . activities-suspend)
+        ("C-x C-a C-k" . activities-kill)    ; Alias for `-suspend'
+        ("C-x C-a a" . activities-resume)
+        ;; For convenience, we also bind `activities-resume' to "C-x C-a
+        ;; C-a", so the user need not lift the Control key.
+        ("C-x C-a C-a" . activities-resume)
+        ("C-x C-a RET" . activities-switch)
+        ("C-x C-a l" . activities-list)))
 
 
-File: README.info,  Node: Usage,  Next: FAQ,  Prev: Installation,  Up: Top
+File: README.info,  Node: Usage,  Next: FAQ,  Prev: Configuration,  Up: Top
 
-2 Usage
+3 Usage
 *******
 
 * Menu:
@@ -131,7 +170,7 @@ File: README.info,  Node: Usage,  Next: FAQ,  Prev: 
Installation,  Up: Top
 
 File: README.info,  Node: Activities,  Next: Compatibility,  Up: Usage
 
-2.1 Activities
+3.1 Activities
 ==============
 
 For the purposes of this library, an "activity" is a window
@@ -153,7 +192,7 @@ in general.
 
 File: README.info,  Node: Compatibility,  Next: Modes,  Prev: Activities,  Up: 
Usage
 
-2.2 Compatibility
+3.2 Compatibility
 =================
 
 This library is designed to not interfere with other workflows and
@@ -166,7 +205,7 @@ activity.
 
 File: README.info,  Node: Modes,  Next: Workflow,  Prev: Compatibility,  Up: 
Usage
 
-2.3 Modes
+3.3 Modes
 =========
 
 ‘activities-mode’
@@ -183,7 +222,7 @@ File: README.info,  Node: Modes,  Next: Workflow,  Prev: 
Compatibility,  Up: Usa
 
 File: README.info,  Node: Workflow,  Next: Commands,  Prev: Modes,  Up: Usage
 
-2.4 Workflow
+3.4 Workflow
 ============
 
 An example of a workflow using activities:
@@ -208,7 +247,7 @@ An example of a workflow using activities:
 
 File: README.info,  Node: Commands,  Next: Bookmarks,  Prev: Workflow,  Up: 
Usage
 
-2.5 Commands
+3.5 Commands
 ============
 
 ‘activities-list’ (‘C-x C-a l’)
@@ -240,7 +279,7 @@ File: README.info,  Node: Commands,  Next: Bookmarks,  
Prev: Workflow,  Up: Usag
 
 File: README.info,  Node: Bookmarks,  Prev: Commands,  Up: Usage
 
-2.6 Bookmarks
+3.6 Bookmarks
 =============
 
 When option ‘activities-bookmark-store’ is enabled, an Emacs bookmark is
@@ -251,7 +290,7 @@ universalize the bookmark system).
 
 File: README.info,  Node: FAQ,  Next: Changelog,  Prev: Usage,  Up: Top
 
-3 FAQ
+4 FAQ
 *****
 
 How is this different from Burly.el (https://github.com/alphapapa/burly.el) or 
Bufler.el (https://github.com/alphapapa/bufler.el/)?
@@ -306,13 +345,14 @@ Why did I get an error?
      proceed smoothly.  Please report any bugs you find.
 
 
-File: README.info,  Node: Changelog,  Prev: FAQ,  Up: Top
+File: README.info,  Node: Changelog,  Next: Development,  Prev: FAQ,  Up: Top
 
-4 Changelog
+5 Changelog
 ***********
 
 * Menu:
 
+* v0.3.2-pre: v032-pre.
 * v0.3.1: v031.
 * v0.3: v03.
 * v0.2: v02.
@@ -322,9 +362,17 @@ File: README.info,  Node: Changelog,  Prev: FAQ,  Up: Top
 * v0.1: v01.
 
 
-File: README.info,  Node: v031,  Next: v03,  Up: Changelog
+File: README.info,  Node: v032-pre,  Next: v031,  Up: Changelog
+
+5.1 v0.3.2-pre
+==============
+
+Updated documentation.
+
+
+File: README.info,  Node: v031,  Next: v03,  Prev: v032-pre,  Up: Changelog
 
-4.1 v0.3.1
+5.2 v0.3.1
 ==========
 
 *Fixes*
@@ -336,7 +384,7 @@ File: README.info,  Node: v031,  Next: v03,  Up: Changelog
 
 File: README.info,  Node: v03,  Next: v02,  Prev: v031,  Up: Changelog
 
-4.2 v0.3
+5.3 v0.3
 ========
 
 *Additions*
@@ -349,7 +397,7 @@ File: README.info,  Node: v03,  Next: v02,  Prev: v031,  
Up: Changelog
 
 File: README.info,  Node: v02,  Next: v013,  Prev: v03,  Up: Changelog
 
-4.3 v0.2
+5.4 v0.2
 ========
 
 *Additions*
@@ -365,7 +413,7 @@ File: README.info,  Node: v02,  Next: v013,  Prev: v03,  
Up: Changelog
 
 File: README.info,  Node: v013,  Next: v012,  Prev: v02,  Up: Changelog
 
-4.4 v0.1.3
+5.5 v0.1.3
 ==========
 
 *Fixes*
@@ -375,7 +423,7 @@ File: README.info,  Node: v013,  Next: v012,  Prev: v02,  
Up: Changelog
 
 File: README.info,  Node: v012,  Next: v011,  Prev: v013,  Up: Changelog
 
-4.5 v0.1.2
+5.6 v0.1.2
 ==========
 
 *Fixes*
@@ -384,7 +432,7 @@ File: README.info,  Node: v012,  Next: v011,  Prev: v013,  
Up: Changelog
 
 File: README.info,  Node: v011,  Next: v01,  Prev: v012,  Up: Changelog
 
-4.6 v0.1.1
+5.7 v0.1.1
 ==========
 
 *Fixes*
@@ -393,32 +441,66 @@ File: README.info,  Node: v011,  Next: v01,  Prev: v012,  
Up: Changelog
 
 File: README.info,  Node: v01,  Prev: v011,  Up: Changelog
 
-4.7 v0.1
+5.8 v0.1
 ========
 
 Initial release.
 
+
+File: README.info,  Node: Development,  Prev: Changelog,  Up: Top
+
+6 Development
+*************
+
+‘activities’ is developed on GitHub
+(https://github.com/alphapapa/activities.el).  Suggestions, bug reports,
+and patches are welcome.
+
+* Menu:
+
+* Copyright assignment::
+
+
+File: README.info,  Node: Copyright assignment,  Up: Development
+
+6.1 Copyright assignment
+========================
+
+This package is part of GNU Emacs (https://www.gnu.org/software/emacs/),
+being distributed in GNU ELPA (https://elpa.gnu.org/).  Contributions to
+this project must follow GNU guidelines, which means that, as with other
+parts of Emacs, patches of more than a few lines must be accompanied by
+having assigned copyright for the contribution to the FSF.  Contributors
+who wish to do so may contact emacs-devel@gnu.org <emacs-devel@gnu.org>
+to request the assignment form.
+
 
 
 Tag Table:
 Node: Top231
-Node: Installation2188
-Node: Usage3855
-Node: Activities4043
-Node: Compatibility5031
-Node: Modes5515
-Node: Workflow6183
-Node: Commands7136
-Node: Bookmarks8492
-Node: FAQ8844
-Node: Changelog11920
-Node: v03112119
-Node: v0312436
-Node: v0212826
-Node: v01313318
-Node: v01213467
-Node: v01113644
-Node: v0113807
+Node: Installation2416
+Node: GNU ELPA2567
+Node: Quelpa2932
+Node: Configuration3652
+Node: Usage4499
+Node: Activities4688
+Node: Compatibility5676
+Node: Modes6160
+Node: Workflow6828
+Node: Commands7781
+Node: Bookmarks9137
+Node: FAQ9489
+Node: Changelog12565
+Node: v032-pre12808
+Node: v03112930
+Node: v0313264
+Node: v0213654
+Node: v01314146
+Node: v01214295
+Node: v01114472
+Node: v0114635
+Node: Development14734
+Node: Copyright assignment15006
 
 End Tag Table