Improve README.org

- Spelling improvements
- Add syntax highlighting to configuration
- Improve wording where needed.
hello-test
Allard Hendriksen 2018-01-11 23:33:13 +01:00
parent c6d716a53c
commit 510b5f4fee
1 changed files with 27 additions and 17 deletions

View File

@ -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