diff --git a/README.org b/README.org index ae3d8eb..87ccef9 100644 --- a/README.org +++ b/README.org @@ -1,6 +1,12 @@ * ob-tmux Ob-tmux is an Emacs library that allows org mode to evaluate code blocks in a tmux session. + +Ob-tmux is useful for keeping notes on how to perform tasks in the +terminal, especially when some interactivity is required. The +functionality can be used to document software installation, build +instructions, and administrative tasks. The documentation can be +tested and adjusted while it is written. * Installation Unfortunately, ob-tmux has not yet been added to melpa. You will need to copy the ~ob-tmux.el~ file to a directory in your ~load-path~. @@ -18,17 +24,22 @@ In your ~.emacs~ or ~.emacs.d/init.el~ file, add the following: ;; You can customize this if you like. (setq org-babel-tmux-session-prefix "org-babel-session-") - ;; Finally, if you tmux is not in your $PATH for whatever reason, you + ;; Syntax highlighting can be added with the following line: + (add-to-list 'org-src-lang-modes (cons "tmux" 'sh)) + + ;; Finally, if your tmux is not in your $PATH for whatever reason, you ;; may set the path to the tmux binary as follows: (setq org-babel-tmux-location "/usr/bin/tmux") + + #+END_SRC * Usage You can start a new terminal window with a tmux session as follows: : #+BEGIN_SRC tmux :session hello : echo hello : #+END_SRC -If you press =C-c C-c= with your point in the code block, a new -terminal window will pop up with a new tmux session named +If you press =C-c C-c= with your point in the code block, a terminal +window will pop up with a new tmux session named =org-babel-session-hello=. You can continue work in this session with another code block. @@ -38,8 +49,11 @@ You can continue work in this session with another code block. If you press =C-c C-c= now, no new terminal window will open, but the code will be sent to the existing tmux session. -You can open new windows within the existing session using the -familiar tmux syntax. +You can also specify to which tmux window the source block should be +sent. If the tmux window does not yet exist, ob-tmux will create it. +To specify the window, you may use the tmux target syntax. In the +following example, the ~:session~ argument has been changed to +=hello:new-world=: : #+BEGIN_SRC tmux :session hello:new-window : echo hello world in new-window : #+END_SRC @@ -48,15 +62,12 @@ session. You can exit your tmux session by detaching. The terminal window will close automatically. Ob-tmux will not detect that you have -detached. Any commands you send will be sent in the background. You -can reattach to your tmux session at any time and check that the -commands have indeed been executed. - -Ob-tmux is useful for keeping notes on how to install software -or perform tasks in the terminal, especially when some interactivity -is required. It is also very useful for starting up your tmux -sessions after a reboot. Take a Look at the following snippet. +detached. Any commands you send will be sent to the tmux session in +the background. You can reattach to your tmux session at any time and +check that the commands have indeed been executed. +*Tip*. Ob-tmux is also very useful for restarting your tmux sessions +after a reboot. Take a Look at the following snippet. : ** Startup tmux : Use ~C-c C-v s~ to execute subtree. : *** Jupyter @@ -72,17 +83,16 @@ sessions after a reboot. Take a Look at the following snippet. : #+BEGIN_SRC tmux :session daemons:dmesg : dmesg : #+END_SRC - If your point is on the =Startup tmux= header, you can execute all -code blocks in the subtree with ~C-c C-v s~ to jump start your tmux -sessions. +code blocks in the subtree with ~C-c C-v s~ to restart your favorite +tmux sessions. * Known bugs and or possible issues My tmux indexes start at 1. By default, tmux window indexes start at zero. This might lead to problems. I have not yet checked. Terminals other than xterm and gnome-terminal have not been -checked. If you have positive or negative experiences with any other +tested. If you have positive or negative experiences with any other terminal, let me know. I will try to respond within a week to any issues raised. I cannot