Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 275 lines (198 sloc) 9.022 kb
581fc75 * INSTALL (REQUIREMENTS): proper list of requirements and sources from
jan authored
1 * INTRODUCTION
154c40a * README (whole file): some initial notes
jan authored
2
45133f6 Jan Moringen Small fixes and improvements in README
scymtym authored
3 Rudel is a collaborative editing environment for GNU Emacs. Its
afe40bb * README (INTRODUCTION): extended a bit
jan authored
4 purpose is to share buffers with other users in order to edit the
5 contents of those buffers collaboratively. Rudel supports multiple
6 backends to enable communication with other collaborative editors
2d159b7 * README (INTRODUCTION): emphasize obby backend being the only
Phil Hagelberg authored
7 using different protocols, though currently Obby (for use with the
8 Gobby editor) is the only fully-functional one.
154c40a * README (whole file): some initial notes
jan authored
9
581fc75 * INSTALL (REQUIREMENTS): proper list of requirements and sources from
jan authored
10 Since Rudel is not an application, but an extension to Emacs, it is
11 not started and used like most applications (not even Emacs
12 applications like Gnus). Rudel mostly works in the background to
13 change the behavior of the set of Emacs buffers for which it has
14 been activated.
15
16 The user interface consists of a set of key bindings, a menu entry
0e954bd Jan Moringen * README (INTRODUCTION): mention header line
scymtym authored
17 and some visual status indicators, which are added to the text,
18 header line and/or mode line of buffers for which Rudel has been
19 activated.
581fc75 * INSTALL (REQUIREMENTS): proper list of requirements and sources from
jan authored
20
21 * GETTING STARTED
22
0e954bd Jan Moringen * README (INTRODUCTION): mention header line
scymtym authored
23 Assuming Rudel has already been installed (see file:INSTALL) and
24 auto loading has been set up, a global Rudel mode can be enabled as
25 follows:
581fc75 * INSTALL (REQUIREMENTS): proper list of requirements and sources from
jan authored
26
27 : M-x global-rudel-minor-mode
28
a50caa2 Joe Corneli Extensive documentation changes, new README sections
holtzermann17 authored
29 This will enable key bindings to list available backends, join, and
30 host Rudel sessions (see below). To enable this mode permanently,
31 the following fragment can be added to the Emacs initialization
32 file (usually file:~/.emacs):
45133f6 Jan Moringen Small fixes and improvements in README
scymtym authored
33
34 #+BEGIN_SRC emacs-lisp
35 (global-rudel-minor-mode 1)
36 #+END_SRC
581fc75 * INSTALL (REQUIREMENTS): proper list of requirements and sources from
jan authored
37
a50caa2 Joe Corneli Extensive documentation changes, new README sections
holtzermann17 authored
38 ** LISTING BACKENDS
39
40 : M-x rudel-backend-dump
41
42 This command is available through the Rudel drop down menu.
43 However, typically this is only used for debugging, since backends
44 are chosen automatically when joining or hosting a session.
45
581fc75 * INSTALL (REQUIREMENTS): proper list of requirements and sources from
jan authored
46 ** JOINING A SESSION
47
48 : M-x rudel-join-session [ C-c c j ]
49
50 Depending on the installed Rudel backends, system environment and
51 configuration, a number of questions will be asked, followed by an
52 attempt to join session described by your answers.
53
afe40bb * README (INTRODUCTION): extended a bit
jan authored
54 A typical example of the questions asked when joining a session may
55 look like this:
56
45133f6 Jan Moringen Small fixes and improvements in README
scymtym authored
57 #+BEGIN_EXAMPLE
afe40bb * README (INTRODUCTION): extended a bit
jan authored
58 Server: localhost RET
59 Port (default 6522): RET
60 Username: jan RET
61 Color: light sky blue RET
62 Use Encryption (y or n): n RET
2d159b7 * README (INTRODUCTION): emphasize obby backend being the only
Phil Hagelberg authored
63 Global Password: RET
64 User Password: RET
45133f6 Jan Moringen Small fixes and improvements in README
scymtym authored
65 #+END_EXAMPLE
afe40bb * README (INTRODUCTION): extended a bit
jan authored
66
45133f6 Jan Moringen Small fixes and improvements in README
scymtym authored
67 *IMPORTANT*: For sessions using the obby backend (like in the
68 example above), the following restriction has to be taken into
69 account:
a50caa2 Joe Corneli Extensive documentation changes, new README sections
holtzermann17 authored
70
afe40bb * README (INTRODUCTION): extended a bit
jan authored
71 + When the server is Rudel inside an Emacs process:
72 Encryption cannot be used currently in this case. Consequently
73 the answer to the `Use Encryption (y or n):' prompt above has to
74 be `n RET'.
75 + When the server is a Gobby process:
76 Gobby only supports encrypted connections. So the answer has to
77 be `y RET' is this case.
78
e5c67ef README (JOINING): Mention `rudel-configured-sessions' customization.
Phil Hagelberg authored
79 It is possible to configure frequently used sessions using the
80 customization options `rudel-configured-sessions'. When one or more
81 sessions are configured, `rudel-join-session' will provide choices
82 like "my-configured-session", ... and "ask-protocol". Selecting
83 "ask-protocol" invokes the behavior described above. Selecting one
84 of the configured sessions connects to that session without asking
85 for all the data.
86
a50caa2 Joe Corneli Extensive documentation changes, new README sections
holtzermann17 authored
87 *** SAVING AND REUSING CONFIGURED SESSIONS
88
89 Each session is described as a plist (a list of keys and values
90 see Info node `(elisp)Property Lists'). Keys are specified using
91 keywords and look like this: :host, :username, :color. Values are
92 mostly strings, but symbols and numbers are possible as well.
93
94 The following keys are required for any session:
95
96 * :name (string)
97 * :transport-backend (string or symbol)
98 * :protocol-backend (string or symbol)
99
100 Other keys are optional and depend on the selected
101 backend. Required keys for which no value is specified will be
102 prompted for when selecting the session. The values of the :name
103 properties have to be distinct for all configured sessions.
104
105 Additional keys required by most backends:
106
107 * :host (string)
108 * :port (number)
109 * :username (string)
110 * :color (string)
111
112 Here is a complete example of customized values for the obby
113 backend:
114
115 * :name "sonian"
116 * :transport-backend tcp
117 * :protocol-backend obby
118 * :host "sobby"
119 * :port 6522
120 * :encryption t
121 * :username "phil"
122 * :color "white"
123 * :global-password "" (this means "no password")
124 * :user-password ""
125
126 The programmatic equivalent looks like this:
127
128 #+BEGIN_SRC emacs-lisp
129 (add-to-list
130 'rudel-configured-sessions
131 (list :name "myserver"
132 :protocol-backend 'tcp
133 :transport-backend 'obby
134 :host "my.sobby-server.net"
135 :username user-login-name
136 ;; Use M-x list-colors-display to see color choices.
137 :color "white"
138 :encryption t
139 :port 6522
140 ;; empty string means no password
141 :global-password ""
142 :user-password ""))
143 #+END_SRC
144
145 ** WORKING WITHIN A CONNECTED SESSION
146
147 *** SHARING BUFFERS
148
149 : M-x rudel-publish-buffer [ C-c c p ]
150
151 Make a buffer available for subscription to peers in a
152 collaborative editing session.
153
154 : M-x rudel-subscribe [ C-c c s ]
155
156 Subscribe to a document offered by a peer in a collaborative
157 editing session. Invoking this command will prompt for the name
158 of the document to subscribe to; TAB will show a list of
159 available documents.
160
161 : M-x rudel-unsubscribe [ C-c c u ]
162
163 Detaches the current buffer from the collaborative editing
164 session. The most recent version of the content will remain in
165 the buffer but not be affected by future changes from other
166 peers.
167
168 *** CHANGING COLORS
169
170 : M-x rudel-change-color [ C-c c c ]
171
172 Change the color associated with your edits.
173
174 *** LEAVING A SESSION
175
176 : M-x rudel-end-session [ C-c c e ]
177
178 Exit the current collaborative editing session.
179
581fc75 * INSTALL (REQUIREMENTS): proper list of requirements and sources from
jan authored
180 ** HOSTING A SESSION
181
182 : M-x rudel-host-session [ C-c c h ]
183
184 Note that the session starts out without any participating users
185 (This is sometimes referred to as being a dedicated server). If you
186 want to participate in the session you host, you have to join it as
187 described above.
afe40bb * README (INTRODUCTION): extended a bit
jan authored
188
a50caa2 Joe Corneli Extensive documentation changes, new README sections
holtzermann17 authored
189 * EXTRA MINOR MODES
190
191 ** [Global] Header Subscriptions minor mode
192
193 : rudel-header-subscriptions-minor-mode
194
195 Displays subscribed users and information concerning their
196 respective status in the header line of a buffer.
197
198 : global-rudel-header-subscriptions-mode
199
200 Enables or disables rudel-header-subscriptions-minor-mode
201 automatically for all buffers.
202
203 ** [Global] Mode line publish state minor mode
204
205 : rudel-mode-line-publish-state-minor-mode
206
207 Displays an indicator of the publication status of a buffer in its
208 mode line. This indicator is similar to the read-only
209 vs. read-write and the remote vs. local indicators. Publication is
210 indicated by a the letter P. Buffers that are not published have
211 an - indicator.
212
213 : global-rudel-mode-line-publish-state-mode
214
215 Enables or disables rudel-mode-line-publish-state-minor-mode
216 automatically for all buffers.
217
4adc9c8 Jan Moringen Added reporting bugs and getting help section to README
scymtym authored
218 * REPORTING BUGS AND GETTING HELP
219
220 ** EmacsWiki
221
222 The EmacsWiki page about Rudel has
223 [[http://www.emacswiki.org/emacs/Rudel#toc8][a section for feedback and questions]].
224 Feel free leave feedback or ask questions there. If a reply does
225 not occur promptly, try writing to the mailing list of visiting the
226 IRC channel.
227
228 ** Issue Tracker
229
230 Bugs can be reported using the issue tracker on the sourceforge
231 project page: http://sourceforge.net/tracker/?group_id=249139
232
233 ** Mailing List
234
235 Another possibility for getting help and reporting problems is
236 writing to the Rudel mailing list:
237 http://sourceforge.net/mail/?group_id=249139
238
239 ** IRC Channel
240
241 Rudel users and developers can also be reached on the #rudel IRC
242 channel on the freenode network: irc:/irc.freenode.net:6667/#rudel
243
3ec4cbf README: Mention Eshell issue and license.
Phil Hagelberg authored
244 * KNOWN ISSUES
afe40bb * README (INTRODUCTION): extended a bit
jan authored
245
45133f6 Jan Moringen Small fixes and improvements in README
scymtym authored
246 + Publishing eshell buffers will cause your session to be
247 disconnected since eshell disables the hooks that Rudel uses to
248 catch changes to the buffer. As a workaround, you can use M-x
249 ansi-term or another terminal emulator.
3ec4cbf README: Mention Eshell issue and license.
Phil Hagelberg authored
250
251 * LICENSE
252
0e954bd Jan Moringen * README (INTRODUCTION): mention header line
scymtym authored
253 This file is part of Rudel.
afe40bb * README (INTRODUCTION): extended a bit
jan authored
254
0e954bd Jan Moringen * README (INTRODUCTION): mention header line
scymtym authored
255 Rudel is free software: you can redistribute it and/or modify it
256 under the terms of the GNU General Public License as published by
257 the Free Software Foundation, either version 3 of the License, or
258 (at your option) any later version.
259
260 Rudel is distributed in the hope that it will be useful, but WITHOUT
261 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
262 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
263 License for more details.
264
265 You should have received a copy of the GNU General Public License
266 along with Rudel. If not, see <http://www.gnu.org/licenses/>.
267
268 #+TITLE: Rudel README
269 #+AUTHOR: Jan Moringen
5a67524 Jan Moringen Proper comments for local variables in README, INSTALL
scymtym authored
270 #+STARTUP: showeverything
271
272 # Local variables:
273 # mode: org
274 # end:
Something went wrong with that request. Please try again.