-
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 conveniently start it (unless you plan to always use a ColOrg server started by someone else).
Prior to using ColOrg for collaboration, you need a running ColOrg server. If none is available, just launch colorg-server, possibly using options to override the default host and port used to receive ColOrg client connections. Option -h 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. Option -p introduces the port to liste to, which defaults to 7997.
When the server starts, it has no resource at all. Resources are later uploaded from the ColOrg clients, as needed. A ColOrg server may be killed at any time, it does not try to save resources nor connections.
The simplest is to create a keybinding to toggle ColOrg in a buffer. For one, I use C-c e . with the following lines in my ~/.emacs file:
(autoload 'colorg-toggle-local "colorg" nil t)
(global-set-key "\C-ce." 'colorg-toggle-local)The first time this keybinding is used, ColOrg is activated for the current buffer: the user is then prompted for the ColOrg server location and resource name. If the resource does not exist on the server, it is created from the current buffer’s contents. If the resource already exists, the buffer ought to hold an identical copy of the resource. As a special case, if the buffer is empty, it is then downloaded from the resource.
The second time this keybinding is used in a buffer, that buffer gets dissociated from the ColOrg resource, and returns to the state a pure Emacs buffer.
If the command is repeated to reactivate ColOrg, after the buffer has been locally modified, or the resource remotely modified, the association may not succeed, it gets refused. 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, 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 Emerge 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.