[elpa] externals/dtache 52c82428ac 110/158: Remove documentation directory

[ELPA Syncer]

branch: externals/dtache
commit 52c82428acb5529351ddb81e0a818945ba07da7a
Author: Niklas Eklund <niklas.eklund@zenseact.com>
Commit: Niklas Eklund <niklas.eklund@posteo.net>

    Remove documentation directory
---
 documentation/demo.org     | 244 ---------------------------------------------
 documentation/demo_v02.org | 156 -----------------------------
 2 files changed, 400 deletions(-)

diff --git a/documentation/demo.org b/documentation/demo.org
deleted file mode 100644
index c8de5702f9..0000000000
--- a/documentation/demo.org
+++ /dev/null
@@ -1,244 +0,0 @@
-#+title: dtache.el - Dtach Emacs
-#+author: Niklas Eklund
-#+language: en
-
-* COMMENT Preparations
-
-A simple script that runs for 20 seconds.
-
-#+begin_src sh :tangle /tmp/dtache/loop.sh :tangle-mode (identity #o755)
-  for i in {1..20} ; do sleep 1; echo "$i" ; done
-#+end_src
-
-Tangle the code block above into a shell script.
-
-#+begin_src elisp :results none
-  (call-interactively #'org-babel-tangle-file)
-#+end_src
-
-* Introduction
-
-  [[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.
-
-  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=.
-
-#+begin_src elisp :results none
-  (call-interactively #'dtache-shell-command)
-#+end_src
-
-** With a function
-
-A session can also be started with the =dtache-start-session= function. Which 
can be included in custom commands.
-
-#+begin_src elisp :results none :dir ~/code/python
-  (dtache-start-session "pylint demo.py ")
-#+end_src
-
-** With shell
-
-A session can also be started from =M-x shell=, making it a dispatcher for 
=dtache= sessions.
-
-#+begin_src elisp :results none
-  (call-interactively #'shell)
-#+end_src
-
-Run the following command.
-
-#+begin_src sh
-  /tmp/dtache/loop.sh && ls -la
-#+end_src
-
-* How to interact with a session?
-
-To list all sessions.
-
-#+begin_src elisp :results none
-  (dtache-list-sessions)
-#+end_src
-
-The commands that are available.
-
-| Command                       | Description                  | Keybinding |
-|-------------------------------+------------------------------+------------|
-| =dtache-open-session=         | A DWIM function              | Return     |
-| =dtache-post-compile-session=      | Post compilation             | c        
  |
-| =dtache-delete-session=       | Delete an active session     | d          |
-| =dtache-kill-session=         | Kill an active session       | k          |
-| =dtache-open-output=          | Open sessions output         | o          |
-| =dtache-rerun-session=        | Rerun a session              | r          |
-| =dtache-tail-session=         | Tail the output of a session | t          |
-| =dtache-copy-session-command= | Copy command                 | w          |
-| =dtache-copy-session-output=  | Copy the output              | W          |
-
-* Configuration
-** Annotators
-
-An annotator function runs when a session is started. Its intent is to capture 
metadata information.
-
-#+begin_src elisp :results none
-  (defun dtache--session-git-branch ()
-    "Return current git branch."
-    (let ((git-directory (locate-dominating-file "." ".git")))
-      (when git-directory
-        (let ((args '("name-rev" "--name-only" "HEAD")))
-          (with-temp-buffer
-            (apply #'process-file `("git" nil t nil ,@args))
-            (string-trim (buffer-string)))))))
-#+end_src
-
-Register the annotator function.
-
-#+begin_src elisp :results none
-  (setq dtache-metadata-annotators-alist '((branch . 
dtache--session-git-branch)))
-#+end_src
-
-Create a session.
-
-#+begin_src elisp :results none :dir ~/src/emacs-packages/dtache
-  (dtache-start-session "sleep 2 && ls")
-#+end_src
-
-** External package integration
-
-Here are some examples on how =dtache= can be further improved with external 
packages.
-
-*** Embark & Marginalia
-
-The command =dtache-open-session= is an alternative to the 
=dtache-list-sessions=.
-
-#+begin_src elisp :results none
-  (call-interactively #'dtache-open-session)
-#+end_src
-
-The =dtache-open-session= can be enhanced with 
[[https://github.com/minad/marginalia/][marginalia]] annotations.
-
-#+begin_src elisp :results none
-  (use-package marginalia-dtache
-    :after (dtache marginalia)
-    :config
-    (setq dtache-max-command-length 50)
-    (add-to-list 'marginalia-annotator-registry '(dtache 
marginalia-dtache-annotate builtin none)))
-#+end_src
-
-The =dtache-open-session= can also be given actions through 
[[https://github.com/oantolin/embark/][embark]].
-
-#+begin_src elisp :results none
-  (use-package embark-dtache
-    :after (dtache embark))
-#+end_src
-
-*** Alert
-
-By default =dtache= uses the echo area to notify the user when a session has 
finished. An alternative is to utilize the 
[[https://github.com/jwiegley/alert][alert]] package to get a system 
notification instead.
-
-#+begin_src elisp :results none
-  (defun dtache-session-finish-alert (session)
-    "Send an alert notification when SESSION finish."
-    (let ((status (dtache--session-status session))
-          (title
-           (pcase (dtache--session-status session)
-             ('success "Dtache finished!")
-             ('failure "Dtache failed!"))))
-      (alert (dtache--session-command session)
-             :title title
-             :severity (pcase status
-                         ('success 'moderate)
-                         ('failure 'high))
-             :category 'compile
-             :id (pcase status
-                   ('success 'compile-ok)
-                   ('failure 'compile-fail)))))
-
-  (advice-add 'dtache-session-finish-notification :override 
#'dtache-session-finish-alert)
-#+end_src
-
-A successful session.
-
-#+begin_src elisp :results none :dir ~/src/emacs-packages/dtache
-  (dtache-start-session "ls")
-#+end_src
-
-A failing session.
-
-#+begin_src elisp :results none :dir ~/src/emacs-packages/dtache
-  (dtache-start-session "lsl")
-#+end_src
-
-* Other use cases
-** Remote execution
-
-=Dtache= has support for remote execution which is made possible through 
=TRAMP=. The only difference from a users perspective is that there might be 
some delay before the notification is issued. 
-
-#+begin_src elisp :dir /ssh:pi:~/bin :results none
-  (dtache-start-session "sleep 5 && ls -la")
-#+end_src
-
-** Duration
-
-The duration becomes very valuable when the shell commands are deterministic.
-
-** Diff two sessions
-
-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/documentation/demo_v02.org b/documentation/demo_v02.org
deleted file mode 100644
index 638ec2e254..0000000000
--- a/documentation/demo_v02.org
+++ /dev/null
@@ -1,156 +0,0 @@
-#+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--state-str :face dtache-state-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--state-str :face dtache-state-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-send-input
-              "<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 :)