branch: externals/dtache
commit cb1762ffc217a4602429346cdcf8eeff5fc90cfd
Author: Niklas Eklund <niklas.ekl...@posteo.net>
Commit: Niklas Eklund <niklas.ekl...@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 :)
