[elpa] externals/dtache 6037219c0a 018/158: Update documentation

[ELPA Syncer]

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

    Update documentation
    
    Update the README file as well as adding a demo.org file under
    documentation.
---
 README.org             |  2 +-
 documentation/demo.org | 80 +++++++++++++++++++++++++++++++++++++-------------
 dtache.el              |  8 ++---
 3 files changed, 65 insertions(+), 25 deletions(-)

diff --git a/README.org b/README.org
index 405fdded31..c90047d02c 100644
--- a/README.org
+++ b/README.org
@@ -36,7 +36,7 @@ Here is a list of features that =dtache= provides for a 
session.
     + If the session has the status success the output is opened
     + If the session has the status failure the session is compiled
 
-  To see examples of the features listed above please see the following 
presentation =PLACEHOLDER=.
+  To see examples of the features listed above please see the following 
[[https://www.youtube.com/watch?v=if1W58SrClk][video]].
   
 * Configuration
 ** Dtache
diff --git a/documentation/demo.org b/documentation/demo.org
index df520614a3..08b167a95e 100644
--- a/documentation/demo.org
+++ b/documentation/demo.org
@@ -16,27 +16,19 @@ Tangle the code block above into a shell script.
   (call-interactively #'org-babel-tangle-file)
 #+end_src
 
-Need to make sure =ediff= behaves.
-
-#+begin_src elisp :results none
-  (let ((window-conf))
-    (add-hook 'ediff-before-setup-hook
-              (defun ne/ediff-save-window-conf ()
-                (setq window-conf (current-window-configuration))))
-    (dolist (hook '(ediff-quit-hook ediff-suspended-hook))
-      (add-hook hook (defun ne/ediff-restore-window-conf ()
-                       (set-window-configuration window-conf)))))
-#+end_src
-
 * Introduction
 
-  =Dtache=, or =Detach Emacs=, is a package to run shell commands in sessions 
that are isolated from Emacs. The name of the package comes from 
[[https://github.com/crigler/dtach][dtach]], which is the program that makes 
this package possible.
+  [[https://gitlab.com/niklaseklund/dtache][Dtache]], or =Detach Emacs=, is a 
package to run and interact with shell commands which are run isolated from 
Emacs. The name of the package comes from 
[[https://github.com/crigler/dtach][dtach]], which is the program that makes 
this package possible.
 
   The inspiration for the package comes from those situations where I would 
chose to run commands in a terminal outside of Emacs.
 
-* How do I?
-** Start a session
-*** With M-x
+  My reasons for not using Emacs at those points where:
+  - performance
+  - stability
+  - remote support
+
+* How to start a session?
+** With M-x
 
 A session can be started with the command =dtache-shell-command=.
 
@@ -44,7 +36,7 @@ A session can be started with the command 
=dtache-shell-command=.
   (call-interactively #'dtache-shell-command)
 #+end_src
 
-*** With a function
+** With a function
 
 A session can also be started with the =dtache-start-session= function. Which 
can be included in custom commands.
 
@@ -52,7 +44,7 @@ A session can also be started with the =dtache-start-session= 
function. Which ca
   (dtache-start-session "pylint demo.py ")
 #+end_src
 
-*** With shell
+** With shell
 
 A session can also be started from =M-x shell=, making it a dispatcher for 
=dtache= sessions.
 
@@ -63,10 +55,10 @@ A session can also be started from =M-x shell=, making it a 
dispatcher for =dtac
 Run the following command.
 
 #+begin_src sh
-  sleep 10 && ls -la
+  /tmp/dtache/loop.sh && ls -la
 #+end_src
 
-** Interact with a session
+* How to interact with a session?
 
 To list all sessions.
 
@@ -199,6 +191,54 @@ The duration becomes very valuable when the shell commands 
are deterministic.
 
 In combination with the =git-branch= annotator the =dtache-diff-session= 
command becomes useful in comparing two sessions.
 
+#+begin_src elisp :results none
+  (let ((window-conf))
+    (add-hook 'ediff-before-setup-hook
+              (defun demo/ediff-save-window-conf ()
+                (setq window-conf (current-window-configuration))))
+    (dolist (hook '(ediff-quit-hook ediff-suspended-hook))
+      (add-hook hook (defun demo/ediff-restore-window-conf ()
+                       (set-window-configuration window-conf)))))
+#+end_src
+
 ** Transient combo
 
 [[https://github.com/magit/transient][Transient]] and =dtache= plays very well 
together. At work I use the power of transient to compose shell commands and 
=dtache= to run them.
+
+** Create sessions with custom open functions
+
+Sometimes you need to tweak =dtache's= behavior in how to interact with 
specific sessions. If that is the case it is best done by adding a custom 
=open-function= or a custom =callback-function=.
+
+#+begin_src elisp :results none
+  (defun demo/dtache-custom-session (command)
+    "Run COMMAND in a very custom way."
+    (let ((dtache-open-session-function
+           (lambda (session)
+             (let ((buffer (get-buffer-create "*dtache-custom-open*")))
+               (with-current-buffer buffer
+                 (erase-buffer)
+                 (insert "This is a custom view of the session\n")
+                 (insert (dtache-session-output session)))
+               (pop-to-buffer buffer)))))
+      (dtache-start-session command)))
+
+  (demo/dtache-custom-session "ls")
+#+end_src
+
+* The End 
+
+The last thing we need to actually prove is the ability to actually run 
independently from Emacs.
+
+Local session.
+
+#+begin_src elisp :results none
+  (dtache-start-session "/tmp/dtache/loop.sh && echo end")
+#+end_src
+
+Remote session.
+
+#+begin_src elisp :dir /ssh:pi:~/bin :results none
+  (dtache-start-session "sleep 30 && ls -la")
+#+end_src
+
+Thanks for watching :)
diff --git a/dtache.el b/dtache.el
index 17e8795066..cb346bd68b 100644
--- a/dtache.el
+++ b/dtache.el
@@ -150,8 +150,8 @@
            (dtache-select-session))))
   (if-let ((open-function
             (dtache--session-open-function session)))
-      (funcall open-function session))
-  (dtache-open-dwim session))
+      (funcall open-function session)
+    (dtache-open-dwim session)))
 
 ;;;###autoload
 (defun dtache-compile-session (session)
@@ -381,7 +381,7 @@ Sessions running on  current host or localhost are updated."
         (setf (dtache--session-status session) (funcall status session)))
       (dtache-session-finish-notification session)
       (when-let ((callback (dtache--session-callback-function session)))
-        (funcall callback))))
+        (funcall callback session))))
   (setf (dtache--session-output-size session)
         (file-attribute-size (file-attributes
                               (dtache-session-file session 'log))))
@@ -755,7 +755,7 @@ Sessions running on  current host or localhost are updated."
 
          ;; Execute callback
          (when-let ((callback (dtache--session-callback-function session)))
-           (funcall callback)))))))
+           (funcall callback session)))))))
 
 (defun dtache--eat-cookie (&rest _)
   "Eat the disambiguation cookie in the minibuffer."