[elpa] externals/detached 0beadb74e0 4/5: Update detached.info file

[ELPA Syncer]

branch: externals/detached
commit 0beadb74e094e68c5a2015a819a7ec7392359fc3
Author: Niklas Eklund <niklas.eklund@posteo.net>
Commit: Niklas Eklund <niklas.eklund@posteo.net>

    Update detached.info file
---
 doc/detached.info | 211 ++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 157 insertions(+), 54 deletions(-)

diff --git a/doc/detached.info b/doc/detached.info
index a13429e991..1a595bc3d9 100644
--- a/doc/detached.info
+++ b/doc/detached.info
@@ -44,11 +44,12 @@ customizations.
 * Dependencies::
 * Installation::
 * Configuration::
+* Workflows::
 * Customization::
 * Design::
 * Known limitations::
 * Contributions::
-* Acknowledgements::
+* Acknowledgments::
 
 — The Detailed Node Listing —
 
@@ -58,6 +59,16 @@ Installation
 * Install from package archives::
 * Install from Guix::
 
+Workflows
+
+* Integration with shells::
+* Integration with compile and shell-command::
+* Session management::
+
+Session management
+
+* Detached list sessions::
+
 Customization
 
 * Notifications::
@@ -78,7 +89,7 @@ Known limitations
 * Quotation marks::
 * Reproducible environments::
 
-Acknowledgements
+Acknowledgments
 
 * Code contributors::
 * Idea contributors::
@@ -95,15 +106,15 @@ independent from Emacs itself.  This is accomplished by 
offloading the
 process creation to the program ‘dtach’.
 
    The package introduces a concept of a detached session.  A session
-constitues of three parts:
+constitutes of three parts:
 
    • a dtach process
    • a log with all the process output
    • a datastructure in Emacs-Lisp
 
    After a session has been created, Emacs can optionally attach to the
-process.  This is something that can be done seemlessly and therefore
-provides no dissruption in the ordinary workflows.  Another feature
+process.  This is something that can be done seamlessly and therefore
+provides no disruption in the ordinary workflows.  Another feature
 provided by the package is its monitoring of sessions.  It will notify
 the user whenever a session transitions from active to inactive.  Since
 all the output of the session is captured, and stored persistently, it
@@ -136,6 +147,7 @@ features from the package are:
    • ‘tail’
    • ‘script’
    • ‘grep’
+   • ‘tee’
 
 
 File: detached.info,  Node: Installation,  Next: Configuration,  Prev: 
Dependencies,  Up: Top
@@ -189,7 +201,7 @@ To install ‘detached’ with Guix run the following command 
in a terminal.
      guix install emacs-detached
 
 
-File: detached.info,  Node: Configuration,  Next: Customization,  Prev: 
Installation,  Up: Top
+File: detached.info,  Node: Configuration,  Next: Workflows,  Prev: 
Installation,  Up: Top
 
 4 Configuration
 ***************
@@ -206,9 +218,95 @@ This is a a minimal ‘use-package’ configuration.
                 (detached-terminal-data-command system-type)))
 
 
-File: detached.info,  Node: Customization,  Next: Design,  Prev: 
Configuration,  Up: Top
+File: detached.info,  Node: Workflows,  Next: Customization,  Prev: 
Configuration,  Up: Top
+
+5 Workflows
+***********
+
+* Menu:
+
+* Integration with shells::
+* Integration with compile and shell-command::
+* Session management::
+
+
+File: detached.info,  Node: Integration with shells,  Next: Integration with 
compile and shell-command,  Up: Workflows
+
+5.1 Integration with shells
+===========================
+
+The package supports integration with ‘shell’, ‘eshell’ and ‘vterm’.
+All of the integrations work similarly.  In all cases a detached minor
+mode is provided.  Each of the minor modes provides keybindings for the
+following operations:
+
+   • Creating a session
+   • Detaching from a session
+   • Attach to a session
+
+   When creating a session Emacs will automatically attach to the
+underlying ‘dtach’ process and the result will look the same as if
+‘detached’ wasn’t used.  The difference is that the user can detach from
+the session with the keybinding determined by the ‘detached-detach-key’.
+If the prefix argument is provided when creating the session detached
+will not attach to the session.  To later attach to a running session
+the user can do this with the attach command, by default bound to
+‘C-<return>’.
+
+
+File: detached.info,  Node: Integration with compile and shell-command,  Next: 
Session management,  Prev: Integration with shells,  Up: Workflows
+
+5.2 Integration with compile and shell-command
+==============================================
+
+When creating a session with ‘detached-compile’ or
+‘detached-shell-command’ Emacs will attach to the process and show the
+result in a buffer.  It is possible to detach from the process with the
+‘detached-detach-key’ and the buffer will then be closed.  Later on to
+attach to a session use any of the commands provided mentioned in
+Session management.
 
-5 Customization
+
+File: detached.info,  Node: Session management,  Prev: Integration with 
compile and shell-command,  Up: Workflows
+
+5.3 Session management
+======================
+
+The package offers two different interfaces for session management,
+‘detached-open-session’ and ‘detached-list-sessions’.  The former uses
+the completing-read interface, whilst the latter uses the tabulated list
+interface.  Each of the interfaces can be used to interact with a
+session.  The ‘detached-list-sessions’ interface is however more feature
+rich, and is what is recommended from the package author.
+
+* Menu:
+
+* Detached list sessions::
+
+
+File: detached.info,  Node: Detached list sessions,  Up: Session management
+
+5.3.1 Detached list sessions
+----------------------------
+
+After opening ‘detached-list-sessions’ the user can press ‘?’ to view a
+list of all commands accessible in the buffer.  Generally speaking there
+are commands to either operate on the session at point, such as
+rerunning it and deleting it.  Or there are commands that operate on
+multiple sessions at once, such as marking sessions or narrow the list
+of sessions based on a criteria.
+
+   Narrow criteria are composable so that they each take effect after
+each other.  For example narrowing based on local sessions, narrows the
+list of candidates, which further can be narrowed to sessions where the
+command match a regular expression.  The mode also features a command
+‘detached-list-select-filter’ which allows the user to select a
+preconfigured set of criteria defined in ‘detached-list-filters’.
+
+
+File: detached.info,  Node: Customization,  Next: Design,  Prev: Workflows,  
Up: Top
+
+6 Customization
 ***************
 
 * Menu:
@@ -219,7 +317,7 @@ File: detached.info,  Node: Customization,  Next: Design,  
Prev: Configuration,
 
 File: detached.info,  Node: Notifications,  Next: Detached list,  Up: 
Customization
 
-5.1 Notifications
+6.1 Notifications
 =================
 
 By default ‘detached’ uses the built in ‘notifications’ library to issue
@@ -237,7 +335,7 @@ that doesn’t work the user has the posbility to customize 
the
 
 File: detached.info,  Node: Detached list,  Prev: Notifications,  Up: 
Customization
 
-5.2 Detached list
+6.2 Detached list
 =================
 
 The buffer created by ‘detached-list-sessions’ can be customized in its
@@ -257,7 +355,7 @@ the following value can be used:
 
 File: detached.info,  Node: Design,  Next: Known limitations,  Prev: 
Customization,  Up: Top
 
-6 Design
+7 Design
 ********
 
 * Menu:
@@ -267,7 +365,7 @@ File: detached.info,  Node: Design,  Next: Known 
limitations,  Prev: Customizati
 
 File: detached.info,  Node: Sessions,  Up: Design
 
-6.1 Sessions
+7.1 Sessions
 ============
 
 * Menu:
@@ -279,7 +377,7 @@ File: detached.info,  Node: Sessions,  Up: Design
 
 File: detached.info,  Node: Session creation,  Next: Session initialization,  
Up: Sessions
 
-6.1.1 Session creation
+7.1.1 Session creation
 ----------------------
 
 When creating a session ‘three actions’ are taken:
@@ -310,7 +408,7 @@ the database and then become aware of existence the session.
 
 File: detached.info,  Node: Session initialization,  Next: Session transition, 
 Prev: Session creation,  Up: Sessions
 
-6.1.2 Session initialization
+7.1.2 Session initialization
 ----------------------------
 
 The initialization of ‘sessions’ when ‘detached’ is loaded is performed
@@ -334,7 +432,7 @@ in the following steps:
 
 File: detached.info,  Node: Session transition,  Prev: Session initialization, 
 Up: Sessions
 
-6.1.3 Session transition
+7.1.3 Session transition
 ------------------------
 
 The ‘detached’ sessions are read from the persistent ‘detached.db’ file
@@ -351,7 +449,7 @@ session basis
 
 File: detached.info,  Node: Known limitations,  Next: Contributions,  Prev: 
Design,  Up: Top
 
-7 Known limitations
+8 Known limitations
 *******************
 
 The ‘detached’ package have some known limitations.  It is designed
@@ -367,24 +465,24 @@ use-case with for example ‘tmux’.
 
 File: detached.info,  Node: Quotation marks,  Next: Reproducible environments, 
 Up: Known limitations
 
-7.1 Quotation marks
+8.1 Quotation marks
 ===================
 
 The way the package transforms, the command the user wants to run, into
-a ‘detached’ command behaves incorrectly when it contain double qutation
-marks.  For example the following command:
+a ‘detached’ command behaves incorrectly when it contain double
+quotation marks.  For example the following command:
 
      git shortlog --summary --numbered --all --no-merges --since="01 Jan 2022"
 
-   Will unfortunatelly not be interpreted correctly.  Instead the user
-needs to use single quation marks in order for it to work:
+   Will unfortunately not be interpreted correctly.  Instead the user
+needs to use single quotation marks in order for it to work:
 
      git shortlog --summary --numbered --all --no-merges --since='01 Jan 2022'
 
 
 File: detached.info,  Node: Reproducible environments,  Prev: Quotation marks, 
 Up: Known limitations
 
-7.2 Reproducible environments
+8.2 Reproducible environments
 =============================
 
 The package works best when sessions can be re-run.  For this to work,
@@ -409,9 +507,9 @@ content:
      direnv_command python foo.py
 
 
-File: detached.info,  Node: Contributions,  Next: Acknowledgements,  Prev: 
Known limitations,  Up: Top
+File: detached.info,  Node: Contributions,  Next: Acknowledgments,  Prev: 
Known limitations,  Up: Top
 
-8 Contributions
+9 Contributions
 ***************
 
 The package is part of ‘ELPA’, which means that if you want to
@@ -419,9 +517,9 @@ contribute, you must have a copyright assignement
 
(https://www.gnu.org/software/emacs/manual/html_node/emacs/Copyright-Assignment.html).
 
 
-File: detached.info,  Node: Acknowledgements,  Prev: Contributions,  Up: Top
+File: detached.info,  Node: Acknowledgments,  Prev: Contributions,  Up: Top
 
-9 Acknowledgements
+10 Acknowledgments
 ******************
 
 This package wouldn’t have been were it is today without these
@@ -433,20 +531,20 @@ contributors.
 * Idea contributors::
 
 
-File: detached.info,  Node: Code contributors,  Next: Idea contributors,  Up: 
Acknowledgements
+File: detached.info,  Node: Code contributors,  Next: Idea contributors,  Up: 
Acknowledgments
 
-9.1 Code contributors
-=====================
+10.1 Code contributors
+======================
 
    • rosetail (https://gitlab.com/rosetail)
    • protesilaos (https://lists.sr.ht/~protesilaos)
    • Stefan Monnier (https://www.iro.umontreal.ca/~monnier/)
 
 
-File: detached.info,  Node: Idea contributors,  Prev: Code contributors,  Up: 
Acknowledgements
+File: detached.info,  Node: Idea contributors,  Prev: Code contributors,  Up: 
Acknowledgments
 
-9.2 Idea contributors
-=====================
+10.2 Idea contributors
+======================
 
    • rosetail (https://gitlab.com/rosetail) for all the great ideas and
      improvements to the package.  Without those contributions
@@ -468,28 +566,33 @@ File: detached.info,  Node: Idea contributors,  Prev: 
Code contributors,  Up: Ac
 
 Tag Table:
 Node: Top852
-Node: Overview2193
-Node: Dependencies3484
-Node: Installation3979
-Node: Install from source4370
-Node: Install from package archives4787
-Node: Install from Guix5240
-Node: Configuration5503
-Node: Customization6060
-Node: Notifications6231
-Node: Detached list6892
-Node: Design7511
-Node: Sessions7649
-Node: Session creation7810
-Node: Session initialization9326
-Node: Session transition10564
-Node: Known limitations11260
-Node: Quotation marks11709
-Node: Reproducible environments12339
-Node: Contributions13399
-Node: Acknowledgements13743
-Node: Code contributors13996
-Node: Idea contributors14303
+Node: Overview2363
+Node: Dependencies3654
+Node: Installation4166
+Node: Install from source4557
+Node: Install from package archives4974
+Node: Install from Guix5427
+Node: Configuration5690
+Node: Workflows6243
+Node: Integration with shells6471
+Node: Integration with compile and shell-command7501
+Node: Session management8109
+Node: Detached list sessions8732
+Node: Customization9684
+Node: Notifications9851
+Node: Detached list10512
+Node: Design11131
+Node: Sessions11269
+Node: Session creation11430
+Node: Session initialization12946
+Node: Session transition14184
+Node: Known limitations14880
+Node: Quotation marks15329
+Node: Reproducible environments15961
+Node: Contributions17021
+Node: Acknowledgments17364
+Node: Code contributors17616
+Node: Idea contributors17924
 
 End Tag Table