-
Notifications
You must be signed in to change notification settings - Fork 1
Usage
To work collaboratively on Org files, users should first clone the colorg repository and install colorg. They should then either start a colorg server, or find out about an already running colorg started by someone else. The rest is a matter of activating colorg as needed on the appropriate Emacs buffers. However, if users already have a copy of a colorg resource, they should ensure by other means that this copy is up to date. All these points are detailed below.
To get a copy of the colorg distribution, go to *colorg* site on GitHub and use one of the provided methods, either cloning using Git, or unpacking a tar or zip bundle.
Once this done, install file colorg.el somewhere Emacs will find it.
The colorg-server program relies on the gevent Python package, which itself requires the installation of the system package libevent-dev (on Ubuntu). Once the pre-requisites are in place, install colorg-server at any convenient place from where you may easily start it (unless you plan to always use a colorg server started by someone else).
There are a lot of ways to do this, here is one possibility among others:
sudo apt-get install libevent-dev
git clone git://github.com/pinard/colorg.git
cd colorg
virtualenv env
env/bin/python setup.py install
env/bin/colorg-server -d &It is just a matter of creating one or two keybindings and autoloading the corresponding functions from the colorg client. For one, I use C-c e s to send a message and C-c e . to toggle colorg minor mode, through the following lines in my ~/.emacs file:
(autoload 'colorg-mode "colorg" nil t) (global-set-key "\C-ce." 'colorg-mode) (autoload 'colorg-send-message "colorg" nil t) (global-set-key "\C-ces" 'colorg-send-message)
You may adapt the keybindings to your own preferences or habits, of course.
Here is a way to quickly check that colorg is properly installed. This presumes that the installation and Emacs configuration has been done as per the previous sections. Create two files test1.org and test2.org with identical contents. Then, start two Emacs sessions and a colorg server. Under a window system where Emacs automatically opens a new window, my way of doing this is:
emacs test1.org & emacs test2.org & env/bin/colorg-server -dThis opens two Emacs windows besides the terminal window. The terminal window should display a line like:
colorg server accepting connections on 0.0.0.0, port 7997.
Because of the -d option, the terminal window should displays a trace of all later communications. Then, in one of the Emacs, let’s say the one for test1.org, type:
C-c e . RET RET RET RET
The above presume the C-c e . keybinding I use, but of course, adjust to yours, or even use M-x colorg-mode if you do not have any keybinding for colorg-mode. This Emacs command has the effect of connecting to the server and uploading test1.org. The terminal window should display things:
- something about an incoming connection;
- a request to get a list of resources, yielding none;
- a request to create the resource
test1.org, then given the number 0; - a request to insert
test1.orgcontents at position 0 for resource 0.
In the second Emacs, type:
C-c e . RET RET RET TAB RET
This has the effect of connecting to the server and associating the
current test2.org buffer with the already existing resource named test1.org. The server trace should receive new events:
- something about another incoming connection;
- a request to get a list of resources, yielding
test1.orgas resource0; - a request to join
test1.org, with a check sum of the localtest2.orgcontents.
From now on, modifications to the buffer made in one Emacs should be reflected on the other Emacs buffer. If it does indeed, you may be confident that colorg has been installed correctly.
Prior to using colorg for collaboration, you need a running colorg server. If none is available, just launch colorg-server yourself (as the client wukk not do it), possibly using options to override the default host and port used to receive colorg client connections. Option -h gives a short help reminder. Option -d may be used to see the ongoing protocol in action, this is used for debugging. Two arguments may be given, both optional. The first introduces the host or IP to listen to, which defaults to 0.0.0.0 for all network devices at once; other common values are localhost or 127.0.0.1 for limiting the listening to the loopback device. The second argument (or the first if the host is not given) tells the port to listen to as an integer number, which defaults to 7997.
When the server starts, it has no resource at all. Resources are later uploaded from the colorg clients, easily, as needed. A colorg server may be killed at any time, it does not try to save resources nor connections.
When the function colorg-mode is used, the colorg minor mode is activated for the current buffer. The user gets prompted for the colorg server details, and for the resource name which should be associated, on that server, with the local buffer.
More precisely, colorg prompts for a server name, with completion over the other server names you might already have defined. Usually, you have none yet, or only one. You may choose a new name for a server to define, an empty name either selects the previous server name if you happen to have only one, or local if you have none yet. When a server by that name is not already defined, colorg asks two more questions: a server host and a server port to connect to. The suggested replies are localhost and 9779 respectively, so if these properly describe your running colorg server, just type Enter twice.
Then, if the server connection succeeds, colorg asks for the name of an existing resource to connect to, with completion over all resources known to the server. That question is skipped if the server does not have any resource yet. If you select an existing resource, the server may refuse the association between the resource and your buffer if their contents differ. As a special case, if your buffer is empty, the server understands you want to download a copy of that whole resource into your buffer. If you do not select an existing resource and merely type Enter, colorg assumes that you want to create a new one, and then asks for its name. An empty reply at this point implies the name of the current buffer. If this is really a new name, the server accepts your request and creates the resource, initializing its contents from your local buffer contents.
A lazy user might notice that, given a local colorg server uses the default arguments, it is a simple matter to upload the current buffer as a resource in that server: merely activate colorg minor mode and type Enter four times in a row, or five if the server already has resources.
That’s all: from now on, your modifications to that buffer are sent to the other collaborators, and the modifications they do on their side appear in your own buffer, yet after a lag of one or maybe two seconds. Inserting big chunks of text might imply longer delays. The last incoming text fragment from each collaborator is shown with a hihglighted background, each collaborator using its own highligth color in your own buffers. When a collaborator deletes text instead of inserting it, a one character cursor to the color of the collaborator is left just before the deletion point. Collaborators’ color may vary, however, from one Emacs session to the next.
Another call to colorg-mode acts as a toggle for the colorg minor mode: the buffer gets dissociated from the associated colorg resource, and returns to the state a pure Emacs buffer. To know whether colorg mode is active or not for an Emacs buffer, check its modeline to see if it includes the string co.
If colorg minor mode gets reactivated after the buffer has been locally modified, or after the resource has been remotely modified, the association does not succeed as the buffer and the resource are not identical anymore. See next section for synchronization issues.
Emacs buffers are often loaded from a file, and saved into files. It is then easy to recover the previous contents of a buffer from the file containing it. However, in colorg context, that buffer may have to be associated to colorg server resource, which may happen to have a different contents.
One avenue is to start locally with an empty buffer and load it from a colorg server rather than from a local file. This is not always efficient nor convenient, as one may well decide to modify a buffer locally, without any colorg association. These local modifications may be precious and not thrown away. So, a merge is needed between the local buffer and the remote resource. This may be a difficult issue to automate, especially when the local and remote files are widely or even completely different.
Maybe that in some future, colorg.el might offer machinery to help the user at driving the merge, based on Emacs ediff or something else. Yet for now, merging should be effected by other means, like through a distributed version control system (like Git). Only once the local file and the remote resource are known to be identical, colorg may be activated.
If one ever needs to see two buffers reflecting each other within the same Emacs session, while going through the colorg machinery, the trick is to declare two servers, one for each buffer, each its own server name: yet, declare the same host and port in each.