-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME-elpa
226 lines (165 loc) · 7.94 KB
/
README-elpa
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
1 Introduction
══════════════
`crdt.el' is a real-time collaborative editing environment for Emacs
using Conflict-free Replicated Data Types.
Highlights:
• [CRDT], darling child of collaborative editing researches…
• Share multiple buffer in one session
• See other users' cursor and region
• Synchronize Org mode folding status
• Org mode integration
• Comint derivatives integration (experimental)
[CRDT]
<https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type>
2 Usage
═══════
2.1 Installation
────────────────
`crdt.el' is now on GNU ELPA! Just `M-x package-install crdt'.
*Caution!!!* Please make sure that you and your peers are on the same
`crdt.el' version! It turns out to be one of the most common causes
of `crdt.el' not working. Because currently the network protocol is
not stablized, behavior when using mismatched versions is
unexpectable.
• Strictly speaking, it should work when `crdt-protocol-version' are
defined (added after version `0.2.5') and the same on all peers.
But why not save some hassle and keep everyone on the latest
version.
• To upgrade, just `M-x package-reinstall crdt', then preferably
restart Emacs. To check your `crdt.el' version, `M-x crdt-version'.
2.2 Start a shared session
──────────────────────────
A shared session is a place that can contains multiple buffers (or
files), and multiple users can join to collaboratively edit those
buffers (or files). Think about a meeting room with some people
working together on some papers.
In some buffer, `M-x crdt-share-buffer'. Then enter session name.
This add the current buffer to the existing session with that name.
If no such exists, it creates a new session with the provided session
name, and initially contains the current buffer as a shared buffer.
If a new session is to be created, you need to enter port (default to
6530), optional password and your display name (default to your
current `(user-full-name)').
Experimental settings: "Secure Port" specifies TLS port, and "Command
Functions" specifies user permissions. It's ok to just use the default
values.
2.3 Join a session
──────────────────
`M-x crdt-connect', then enter address, port, and your display name.
If the server has provided the permission (this is the default case),
connected user may also add their buffers to the session via `M-x
crdt-share-buffer'.
Connection URLs look like `ein://ipaddress:6530'
2.4 Navigate through sessions
─────────────────────────────
Sessions
`M-x crdt-list-sessions' lists all sessions.
Buffers
`M-x crdt-list-buffers' lists all buffers in current session.
In the displayed buffer list, press `RET' in the session list to
see buffers in the selected session.
You can also use `M-x crdt-switch-to-buffer' to interactively
switch to another buffer in the current session.
Users
In a CRDT shared buffer (either server or client), `M-x
crdt-list-users' to list active users. In the displayed user
list, press `RET' on an entry to goto that user's cursor
position. Press `f' to follow that user, and press `f' again or
`M-x crdt-stop-follow' to stop following.
You can also use `M-x crdt-goto-next-user' and `M-x
crdt-goto-prev-user' to cycle through users' cursor positions
from any CRDT shared buffer (don't need to be in the user list
buffer).
2.5 Stop sharing
────────────────
`M-x crdt-stop-session' stops a session you've started and disconnect
all other users from it. This will ask for your confirmation,
customize `crdt-confirm-stop-session' if you want to disable it.
You can also press `k' or `d' in the session list (show it by `M-x
crdt-list-sessions').
`M-x crdt-stop-share-buffer' removes current buffer from its CRDT
session (this operation is only allowed at server side). You can also
press `k' or `d' in the buffer list.
2.6 Disconnect from a session
─────────────────────────────
`M-x crdt-disconnect', then choose a session to disconnect from.
You can also press `k' or `d' in the session list (show it by `M-x
crdt-list-sessions').
The server Emacs has the privilege to disconnect a user from a
session. To do so, press `k' or `d' on an entry in the user list
(show it by `M-x crdt-list-users').
2.7 Fancy stuff
───────────────
Visualizing author of parts of the document
Turn on `crdt-visualize-author-mode' to color text based on
which user authored it.
Synchronizing Org folding status
Turn on `crdt-org-sync-overlay-mode'. All peers that have this
enabled have their folding status synchronized. Peers without
enabling this minor mode are unaffected.
Comint integration
Just go ahead and share you comint REPL buffer! Tested: `shell'
and `cmuscheme'. By default, when sharing a comint buffer,
`crdt.el' temporarily reset input history (as in `M-n' `M-p') so
others don't spy into your `.bash_history' and alike. You can
customize this behavior using variable
`crdt-comint-share-input-history'.
2.8 What if we don't have a public IP?
──────────────────────────────────────
There're various workaround.
• You can use [tuntox] to proxy your connection over the [Tox]
protocol. `crdt.el' has experimental built-in integration for
`tuntox'. To enable it, you need to install `tuntox', set up the
custom variable `crdt-tuntox-executable' accordingly (the path to
your `tuntox' binary), and set the custom variable
`crdt-use-tuntox'. Setting it to `t' make `crdt.el' always create
`tuntox' proxy for new server sessions, and setting it to `'confirm'
make `crdt.el' ask you every time when creating new sessions. After
starting a session with `tuntox' proxy, you can `M-x crdt-copy-url'
to copy a URL recognizable by `M-x crdt-connect' and share it to
your friends. Be aware that according to my experience, `tuntox'
takes significant time to establish a connection (sometimes up to
half a minute), however it gets much faster after the connection is
established.
• You can use SSH port forwarding if you have a VPS with public IP.
Example usage:
┌────
│ $ ssh -R EXAMPLE.COM:6530:127.0.0.1:6530 EXAMPLE.COM
└────
This make your `crdt.el' session on local port `6530' accessible
from `EXAMPLE.COM:6530'.
Note that you need to set the following `/etc/ssh/sshd_config'
option on your VPS
┌────
│ GatewayPorts yes
└────
• For other tunneling solutions, see
<https://github.com/anderspitman/awesome-tunneling>
[tuntox] <https://gitlab.com/gjedeer/tuntox>
[Tox] <https://tox.chat>
3 Service
═════════
`crdt.el' uses emacs' built in `(make-network-process)' to exchange
elisp messages between clients, see `crdt--format-message'.
You can see these messages in within emacs with `(setq
crdt--log-network-traffic t)' and outside emacs with `nc' or `telnet'.
┌────
│ nc localhost 6530 <<< '(hello "0.3.0")'
└────
Demonstrating `(hello)', `(get)', and `(leave)'
┌────
│ telnet localhost 6530
│ ...
│ (hello "0.3.0")
│
│ (login 2)(add "testfile.org") ....
│
│ (get "testfile.org")
│ (sync "testfile.org" (#("FILE CONTENTS ....
│
│ (leave 2)
└────
3.1 Messages
────────────
hello, leave, get, cursor, overlay-move, overlay-remove, overlay-put,
return, var, ready