[elpa] externals/dtache cb1762ffc2 052/158: Add presentation about dtache version 0.2

[ELPA Syncer]

branch: externals/dtache
commit cb1762ffc217a4602429346cdcf8eeff5fc90cfd
Author: Niklas Eklund <niklas.eklund@posteo.net>
Commit: Niklas Eklund <niklas.eklund@posteo.net>

    Add presentation about dtache version 0.2
---
 README.org                 |   8 ++-
 documentation/demo_v02.org | 156 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 162 insertions(+), 2 deletions(-)

diff --git a/README.org b/README.org
index b1a5246119..658db79ad6 100644
--- a/README.org
+++ b/README.org
@@ -11,6 +11,10 @@
 
 The core concept of =dtache= is its object =dtache-session=. This object 
encapsulate information about a session, such as the =command= which is run in 
the session, the =working directory= from which the session is started, the 
=host= on which the session runs, where the =output= of the session is stored, 
where the =socket= to the underlying =dtach= process resides etc. The program 
[[https://github.com/crigler/dtach][dtach]] is what makes this package 
possible, it takes care of running t [...]
 
+The following videos features demonstrations about the package:
+- [[https://www.youtube.com/watch?v=if1W58SrClk][Dtache - An Emacs package 
that provides detachable shell commands]]
+- [[https://www.youtube.com/watch?v=De5oXdnY5hY][Dtache - Version 0.2]]
+
 ** Features
 
 The way =dtache= is designed with its =dtache-session= objects opens up the 
possibilities for the following features.
@@ -198,9 +202,9 @@ Some programs doesn't play well with =tee=, which =dtache= 
relies upon to redire
 
 Here a command beginning with =ls= would from now on be using redirect only.
 * Tips & Tricks
-** MacOS support
+** macOS support
 
-=Dtache= depends on =filenotify= to trigger events when a =dtach socket= is 
deleted, which defines the transition from active to inactive for a dtache 
session. Currently this implementation causes issues for MacOS users, it should 
work, but until the root cause has been identified this provides a workaround 
solution.
+=Dtache= depends on =filenotify= to trigger events when a =dtach socket= is 
deleted, which defines the transition from active to inactive for a dtache 
session. Currently this implementation causes issues for macOS users, it should 
work, but until the root cause has been identified this provides a workaround 
solution.
 
 #+begin_src elisp :lexical t :results none
   (defun my/dtache--add-end-of-session-notification-advice (session)
diff --git a/documentation/demo_v02.org b/documentation/demo_v02.org
new file mode 100644
index 0000000000..8241b48d36
--- /dev/null
+++ b/documentation/demo_v02.org
@@ -0,0 +1,156 @@
+#+title: dtache.el - Dtach Emacs
+#+author: Niklas Eklund
+#+language: en
+
+* Introduction
+
+=Dtache=, or =Detach Emacs=, is a package to run shell commands completely 
detached from Emacs. With shell commands, we refer to commands that otherwise 
would be run in a terminal. The detachable nature of the package means that 
commands started with it can outlive Emacs, which also works on remote hosts, 
essentially offering a lightweight alternative to 
[[https://github.com/tmux/tmux][Tmux]] or 
[[https://www.gnu.org/software/screen/][GNU Screen]]. The user can effectively 
use =dtache= a [...]
+
+The core concept of =dtache= is its object =dtache-session=. This object 
encapsulate information about a session, such as the =command= which is run in 
the session, the =working directory= from which the session is started, the 
=host= on which the session runs, where the =output= of the session is stored, 
where the =socket= to the underlying =dtach= process resides etc. The program 
[[https://github.com/crigler/dtach][dtach]] is what makes this package 
possible, it takes care of running t [...]
+
+* Version 0.2
+** Improvements to dtache-env
+
+The =dtache-env= shell script, is now provided in the repository. The point of 
this script is to make sure that the exit status of the shell command is 
captured and forwarded to the session's output.
+
+#+begin_src sh
+  #!/usr/bin/env bash
+
+  dtache_command="$*"
+
+  if eval "$dtache_command"; then
+      echo -e "\nDtache session finished"
+  else
+      echo -e "\nDtache session exited abnormally with code $?"
+  fi
+#+end_src
+
+This functionality is opt-in now, so users are advised to configure the 
=dtache-env= variable to point to the location of the script.
+
+#+begin_src elisp :lexical t :results none
+  (setq dtache-env "~/src/emacs-packages/dtache/dtache-env")
+#+end_src
+
+Here is a command to illustrate this.
+
+#+begin_src elisp :lexical t :results none
+  (dtache-start-session "lsl")
+#+end_src
+
+** Support for macOS
+
+It was revealed that =dtache= doesn't work as intended on =macOS=. This is due 
to an issue originating from =filenotify=. Until that issue has been addressed 
users are advised to use the following configuration.
+
+#+begin_src elisp :lexical t :results none
+  (defun demo/dtache--add-end-of-session-notification-advice (session)
+    "Trigger an event when SESSION transition to inactive."
+    (let ((dtache-timer-configuration
+           '(:seconds 0.5 :repeat 0.5 :function run-with-idle-timer)))
+      (dtache--session-timer session)))
+
+  (advice-add 'dtache--add-end-of-session-notification :override 
#'demo/dtache--add-end-of-session-notification-advice)
+#+end_src
+
+** The user interface
+
+I have gotten some valuable feedback from =Daniel Mendler= the co-author of 
=Marginalia=, about how to loosen the dependency that the package had towards 
=Marginalia= and =Embark=.
+
+The result of that is that the following packages has been removed:
+- =embark-dtache=
+- =marginalia-dtache=
+
+This has also resulted in the deprecation of =dtache-list-sessions=, users are 
instead advised to use the =dtache-open-session= command.
+
+**  Annotations
+
+=Dtache= now features its own annotations when listing session using 
=dtache-open-session=. The default configuration is the following, and it now 
becomes easier for users to customize the looks of the annotations.
+
+#+begin_src elisp
+  (defvar dtache-annotation-format
+    `((:width 3 :function dtache--active-str :face dtache-active-face)
+      (:width 3 :function dtache--status-str :face dtache-failure-face)
+      (:width 10 :function dtache--session-host :face dtache-host-face)
+      (:width 40 :function dtache--working-dir-str :face 
dtache-working-dir-face)
+      (:width 30 :function dtache--metadata-str :face dtache-metadata-face)
+      (:width 10 :function dtache--duration-str :face dtache-duration-face)
+      (:width 8 :function dtache--size-str :face dtache-size-face)
+      (:width 12 :function dtache--creation-str :face dtache-creation-face))
+    "The format of the annotations.")
+#+end_src
+
+* Use cases
+** Actions
+
+With =dtache-list-sessions= being deprecated what is the workflow to run 
actions on sessions?
+
+#+begin_src elisp :lexical t :results none
+  (global-set-key (kbd "C-c d") dtache-action-map)
+#+end_src
+
+** Embark integration
+
+If you are an =embark= user the way to integrate =dtache= with =embark= is to 
add the following the configuration.
+
+#+begin_src elisp :lexical t :results none
+  (defvar embark-dtache-map (make-composed-keymap dtache-action-map 
embark-general-map))
+  (add-to-list 'embark-keymap-alist '(dtache . embark-dtache-map))
+#+end_src
+
+** Tweak annotations
+
+#+begin_src elisp :lexical t :results none
+  (setq dtache-max-command-length 30)
+#+end_src
+
+#+begin_src elisp :lexical t :results none
+  (setq dtache-annotation-format
+    `((:width 3 :function dtache--active-str :face dtache-active-face)
+      (:width 3 :function dtache--status-str :face dtache-failure-face)
+      (:width 10 :function dtache--session-host :face dtache-host-face)
+      (:width 30 :function dtache--working-dir-str :face 
dtache-working-dir-face)
+      (:width 20 :function dtache--metadata-str :face dtache-metadata-face)
+      (:width 10 :function dtache--duration-str :face dtache-duration-face)
+      (:width 12 :function dtache--creation-str :face dtache-creation-face)))
+#+end_src
+
+** Shell integration
+
+The package adds support for integration with =M-x shell=. 
+
+#+begin_src elisp
+  (use-package dtache-shell
+    :hook (after-init . dtache-shell-setup)
+    :general
+    (:keymaps 'dtache-shell-mode-map
+              "<S-return>" #'dtache-shell-create-session
+              "<C-return>" #'dtache-shell-attach)
+    :config
+    (setq dtache-shell-history-file "~/.bash_history"))
+#+end_src
+
+*** Demo
+
+#+begin_src sh
+  for i in {1..666} ; do sleep 1; echo "$i" ; done
+#+end_src
+
+- Run the command in the shell
+- =Detach= and then =attach=, notice how only sessions that are active is shown
+- We can run the same command on a remote host
+- We can only attach to a session running on the current host
+
+** Replace compile with dtache
+
+The command =M-x compile= or the function =compile= is utilized in a lot of 
packages. For the daring user its possible to unconditionally replace =compile= 
with =dtache= using the following code.
+
+#+begin_src elisp :lexical t :results none
+  (defun demo/dtache-compile-override (command &optional _)
+    "Run COMMAND with `dtache'."
+    (dtache-start-session command))
+
+  (advice-add 'compile :override #'demo/dtache-compile-override)
+#+end_src
+
+* The End 
+
+Thanks for watching :)