Permalink
Browse files

merged Joe's changes

  • Loading branch information...
2 parents ee97f1c + a50caa2 commit 5107f6086682845fcaf3041d83dc2b9aa0eadefa @scymtym scymtym committed Jul 25, 2010
Showing with 171 additions and 15 deletions.
  1. +23 −1 ChangeLog
  2. +135 −3 README
  3. +1 −1 rudel-interactive.el
  4. +2 −2 rudel-mode.el
  5. +10 −8 rudel.el
View
@@ -1,4 +1,26 @@
-2010-07-25 Joseph Corneli <jac2349@dhcp-pub-248.open.pub>
+2010-07-25 Joseph Corneli <holtzermann17@gmail.com>
+
+ Extensive documentation changes, new README sections
+ * README: Extensive documentation changes, including
+ documentation for renamed functions and also:
+ (LISTING BACKENDS): new section
+ (SAVING AND REUSING CONFIGURED SESSIONS): new section
+ (WORKING WITHIN A CONNECTED SESSION): new section
+ (EXTRA MINOR MODES): new section
+
+ Renamed rudel-end-session to rudel-leave-session
+ * rudel.el (rudel-end-session): changed
+ rudel-end-session to rudel-leave-session
+ * rudel-mode.el (rudel-minor-keymap): likewise
+
+ Renamed rudel-unpublish-buffer to rudel-unsubscribe
+ * rudel.el (rudel-attach-to-buffer): changed
+ rudel-unpublish-buffer to rudel-unsubscribe
+ (rudel-detach-from-buffer): likewise
+ (rudel-unsubscribe): likewise
+ * rudel-mode.el (rudel-minor-keymap): likewise
+ * rudel-interactive.el (rudel-allocate-buffer-clear-existing):
+ likewise
Updates to INSTALL file.
* INSTALL: Rearranged and updated instructions so they make more
View
138 README
@@ -26,14 +26,23 @@
: M-x global-rudel-minor-mode
- This will enable Rudel's key bindings and add a menu entry. To
- enable this mode permanently, the following fragment can be added to
- the Emacs initialization file (usually file:~/.emacs):
+ This will enable key bindings to list available backends, join, and
+ host Rudel sessions (see below). To enable this mode permanently,
+ the following fragment can be added to the Emacs initialization
+ file (usually file:~/.emacs):
#+BEGIN_SRC emacs-lisp
(global-rudel-minor-mode 1)
#+END_SRC
+** LISTING BACKENDS
+
+ : M-x rudel-backend-dump
+
+ This command is available through the Rudel drop down menu.
+ However, typically this is only used for debugging, since backends
+ are chosen automatically when joining or hosting a session.
+
** JOINING A SESSION
: M-x rudel-join-session [ C-c c j ]
@@ -58,6 +67,7 @@
*IMPORTANT*: For sessions using the obby backend (like in the
example above), the following restriction has to be taken into
account:
+
+ When the server is Rudel inside an Emacs process:
Encryption cannot be used currently in this case. Consequently
the answer to the `Use Encryption (y or n):' prompt above has to
@@ -74,6 +84,99 @@
of the configured sessions connects to that session without asking
for all the data.
+*** SAVING AND REUSING CONFIGURED SESSIONS
+
+ Each session is described as a plist (a list of keys and values
+ see Info node `(elisp)Property Lists'). Keys are specified using
+ keywords and look like this: :host, :username, :color. Values are
+ mostly strings, but symbols and numbers are possible as well.
+
+ The following keys are required for any session:
+
+ * :name (string)
+ * :transport-backend (string or symbol)
+ * :protocol-backend (string or symbol)
+
+ Other keys are optional and depend on the selected
+ backend. Required keys for which no value is specified will be
+ prompted for when selecting the session. The values of the :name
+ properties have to be distinct for all configured sessions.
+
+ Additional keys required by most backends:
+
+ * :host (string)
+ * :port (number)
+ * :username (string)
+ * :color (string)
+
+ Here is a complete example of customized values for the obby
+ backend:
+
+ * :name "sonian"
+ * :transport-backend tcp
+ * :protocol-backend obby
+ * :host "sobby"
+ * :port 6522
+ * :encryption t
+ * :username "phil"
+ * :color "white"
+ * :global-password "" (this means "no password")
+ * :user-password ""
+
+ The programmatic equivalent looks like this:
+
+ #+BEGIN_SRC emacs-lisp
+ (add-to-list
+ 'rudel-configured-sessions
+ (list :name "myserver"
+ :protocol-backend 'tcp
+ :transport-backend 'obby
+ :host "my.sobby-server.net"
+ :username user-login-name
+ ;; Use M-x list-colors-display to see color choices.
+ :color "white"
+ :encryption t
+ :port 6522
+ ;; empty string means no password
+ :global-password ""
+ :user-password ""))
+ #+END_SRC
+
+** WORKING WITHIN A CONNECTED SESSION
+
+*** SHARING BUFFERS
+
+ : M-x rudel-publish-buffer [ C-c c p ]
+
+ Make a buffer available for subscription to peers in a
+ collaborative editing session.
+
+ : M-x rudel-subscribe [ C-c c s ]
+
+ Subscribe to a document offered by a peer in a collaborative
+ editing session. Invoking this command will prompt for the name
+ of the document to subscribe to; TAB will show a list of
+ available documents.
+
+ : M-x rudel-unsubscribe [ C-c c u ]
+
+ Detaches the current buffer from the collaborative editing
+ session. The most recent version of the content will remain in
+ the buffer but not be affected by future changes from other
+ peers.
+
+*** CHANGING COLORS
+
+ : M-x rudel-change-color [ C-c c c ]
+
+ Change the color associated with your edits.
+
+*** LEAVING A SESSION
+
+ : M-x rudel-end-session [ C-c c e ]
+
+ Exit the current collaborative editing session.
+
** HOSTING A SESSION
: M-x rudel-host-session [ C-c c h ]
@@ -83,6 +186,35 @@
want to participate in the session you host, you have to join it as
described above.
+* EXTRA MINOR MODES
+
+** [Global] Header Subscriptions minor mode
+
+ : rudel-header-subscriptions-minor-mode
+
+ Displays subscribed users and information concerning their
+ respective status in the header line of a buffer.
+
+ : global-rudel-header-subscriptions-mode
+
+ Enables or disables rudel-header-subscriptions-minor-mode
+ automatically for all buffers.
+
+** [Global] Mode line publish state minor mode
+
+ : rudel-mode-line-publish-state-minor-mode
+
+ Displays an indicator of the publication status of a buffer in its
+ mode line. This indicator is similar to the read-only
+ vs. read-write and the remote vs. local indicators. Publication is
+ indicated by a the letter P. Buffers that are not published have
+ an - indicator.
+
+ : global-rudel-mode-line-publish-state-mode
+
+ Enables or disables rudel-mode-line-publish-state-minor-mode
+ automatically for all buffers.
+
* REPORTING BUGS AND GETTING HELP
** EmacsWiki
View
@@ -205,7 +205,7 @@ sources for a matching password entry."
(error "Buffer `%s' already attached to a document" name)))
;; Delete buffer contents; maybe detach buffer first.
(when (rudel-buffer-has-document-p buffer)
- (rudel-unpublish-buffer buffer))
+ (rudel-unsubscribe buffer))
(with-current-buffer buffer
(erase-buffer)))
(setq buffer (get-buffer-create name)))
View
@@ -541,7 +541,7 @@ line publish state mode; otherwise, turn it off."
'("Rudel"
[ "Join Session" rudel-join-session
(not rudel-current-session) ]
- [ "Leave Session" rudel-end-session
+ [ "Leave Session" rudel-leave-session
rudel-current-session ]
"---"
[ "Host a Session" rudel-host-session
@@ -556,7 +556,7 @@ line publish state mode; otherwise, turn it off."
[ "Publish current Buffer" rudel-publish-buffer
(and rudel-current-session
(not (rudel-buffer-has-document-p))) ]
- [ "Unpublish current Buffer" rudel-unpublish-buffer
+ [ "Unsubscribe from current Buffer" rudel-unpublish-buffer
(rudel-buffer-has-document-p) ]
[ "Subscribe to Document" rudel-subscribe
rudel-current-session ]
View
@@ -465,7 +465,7 @@ collaborative editing session can subscribe to."
;; Add a handler to the kill-buffer hook to unsubscribe from the
;; document when the buffer gets killed.
(add-hook 'kill-buffer-hook
- #'rudel-unpublish-buffer
+ #'rudel-unsubscribe
nil t)
;;
@@ -486,7 +486,7 @@ Do nothing, if THIS is not attached to any buffer."
(with-current-buffer buffer
;; Remove our handler function from the kill-buffer hook.
(remove-hook 'kill-buffer-hook
- #'rudel-unpublish-buffer
+ #'rudel-unsubscribe
t)
;; Remove our handler function from the after-change hook.
@@ -938,13 +938,13 @@ will be prompted for."
session))
;;;###autoload
-(defun rudel-end-session ()
- "End the current collaborative editing session."
+(defun rudel-leave-session ()
+ "Leave the current collaborative editing session."
(interactive)
(unless rudel-current-session
(error "No active Rudel session"))
- ;; Actually end the session.
+ ;; Close the connection.
(rudel-end rudel-current-session)
)
@@ -1046,9 +1046,11 @@ If BUFFER is nil, the current buffer is used."
)
;;;###autoload
-(defun rudel-unpublish-buffer (&optional buffer)
- "Deny peers access to BUFFER in a collaborative editing session.
-If BUFFER is nil, the current is used."
+(defun rudel-unsubscribe (&optional buffer)
+ "Detaches BUFFER from the collaborative editing session.
+The most recent version of the content will remain in the
+buffer but not be affected by future changes from other
+peers. If BUFFER is nil, the current is used."
(interactive)
;; Make sure we have a session.

0 comments on commit 5107f60

Please sign in to comment.