A Quick Guided Tour of Shemacs

Julio Polo
University of Hawaii
2565 The Mall
Honolulu, Hawaii 96822
(808) 956-2405
julio@hawaii.edu

ICS/CSDL-TR-95-16
September 27, 1995

1 Prerequisites

This is a quick guided tour through the main features of Shemacs. It assumes you have already installed Shemacs following the instructions from the provided INSTALLATION file. Unless otherwise specified, an instruction to select a menu item refers to a menu item under the Shemacs menu.

2 Bring up 3 XEmacs processes

Start three XEmacs processes:

xemacs &; xemacs &; xemacs &

After all three XEmacs processes have come up, lay them out on your screen such that all three of them are visible as in figure 1.

3 Bring Up a Shemacs Server

Shemacs is a client-server system. A Shemacs server is sometimes referred to as a sherver. In this demo, we started three XEmacs processes because we will start a sherver on one of them and a client on each of the remaining two.

You need to start a sherver because it will hold the list of documents that you want to make available for shared editing with others, but most importantly, the sherver will perform concurrency control on the changes performed by users simultaneously editing a sherver-shared document. Let's start a sherver on the first XEmacs process. Hereafter, we wil refer to this XEmacs process as the sherver. To start the server, enter

M-x shm*cmd*start-sherver

You will now be asked a series of questions at the minibuffer. Here are the questions you will be asked along with the answers you should provide:

Step Prompt Your Response 1 host name: (press return for default) 2 port number: (press return for default) 3 directory for this sherver: ?/shemacs-demo 4 Is this a brand new sherver? yes
5 Building clients.hb: password for Gagent? kalanianaole 6 Building clients.hb: user and password (if no more, type "exit")? steve kaaawa 7 Building clients.hb: user and password (if no more, type "exit")? dano malaekahana 8 Building clients.hb: user and password (if no more, type "exit")? exit
9 Enter HBS password (db-ID: host.domain.15000, client: Gagent): kalanianaole

It is encouraged that you choose a password of your own in steps 5 through 7 and to substitute them in these instructions as needed. This is to prevent other people reading this demo to access your sherver with the sample passwords used in here.
The sherver is identified by a db-ID which is normally your host's fully qualified domain name followed by a period and the port number used.

Figure 1: Shemacs Demo Session.

Steps 5 through 8 are performed only once: when a brand new sherver is initialized. These steps allow you to create client names and passwords for connecting to the sherver. Please refer to the Egret documentation on hbs-encrypt for additional information.
Several things will flash on the screen until the sherver's minibuffer says ?sherver is up?, and a Shemacs menu has been inserted in front of all other XEmacs menus.

4 Bring Up Two Shemacs Clients

For each of the two remaining XEmacs processes, start a shemacs client as follows:

M-x shm*cmd*start-client

The ?shemacs ready? message will then appear at the minibuffer, and a Shemacs menu appears in front of all other XEmacs menus. Note that these clients have not connected to any sherver yet. When you connect to a sherver, you will be prompted for your user and password on that sherver.

5 Submit the Document to be Shared

We have started a sherver but it is not serving any documents yet. Here we will use the second XEmacs process to connect as client ?steve? to our sherver and then submit the /usr/local/shemacs/demo.doc file so that it may be available for shared editing through our sherver.
Select the ?Submit Document...? menu item (M-x shm*cmd*submit-document) and answer the prompts as follows:

Step Prompt Your Response 1 host name: (press return for default) 2 port number: (press return for default) 3 file to submit: /usr/local/shemacs/demo.doc 4 share it with the name of? (press return for demo.doc) 5 host.domain.15000 login: steve
6 Enter HBS password (db-ID: host.domain.15000, client: steve): kaaawa

You will see several messages showing the connection to the sherver in progress. If you keep your eyes on the sherver's minibuffer, you will see that a file named demo.doc was written out, and that the buffer for this file is in the sherver process as well.
The demo.doc document is now ready to be edited by more than one user.

6 Open demo.doc From Two Shemacs Clients

We will now open the demo.doc document from the second and third XEmacs processes. Select ?Open Document...? (C-c f or M-x shm*cmd*open-document) and answer the prompts as follows:

Step Prompt Your Response 1 host name: (press return for default) 2 port number: (press return for default) 3 document name: demo.doc
4 host.domain.15000 login: dano
5 Enter HBS password (db-ID: host.domain.15000, client: steve): malaekahana

Note that steps 4 and 5 are only needed on the third XEmacs process since we have already logged in as ?steve? in the second XEmacs process when we submitted the demo.doc document to the sherver. The buffer for demo.doc should now be on both clients.

7 Edit demo.doc From Both Shemacs Clients

Switch to the demo.doc buffer on the sherver so that you can also see what happens on the sherver when shared editing is happening on demo.doc

Now go to the second XEmacs process (the one you logged in as ?steve?), highlight the first paragraph, and then select the ?Edit Region? menu item (C-c e or M-x shm*cmd*edit-region). What you have just done is claim the first paragraph for steve to edit. In Shemacs lingo, you have just claimed a region for editing. No other client can touch this paragraph until steve does a ?Close Region? on it.

Notice how the claimed region of text is now in blue boldface and has ?steve? next to it. If you look at the other XEmacs processes, the region steve has claimed is in red italic text and also shows ?steve? as the person editing that region.

Fix the mispelled word ?sornkeling? to ?snorkeling?. Notice that the changes you have made are NOT automatically updated on the other XEmacs processes. You need to select ?Synchronize Region? (C-c z or M-x shm*cmd*synchronize-region) or ?Synchronize All?(shm*cmd*synchronize-all) for that to happen. Shemacs will automatically update other clients during crucial events such as closing a region, closing a document, or disconnecting from a sherver.

Repeat the above on the third XEmacs process. Edit the second paragraph and fix the mispelled word ?beech? to ?beach?. Feel free to experiment by trying to edit regions that have been claimed by someone else and seeing what happens, or by adding and deleting text and observing how fast changes propagate among clients.
Note that the sherver should never be used for shared editing. Only shemacs clients can safely be used for editing a sherver-shared document.

8 Saving in Shemacs

There are actually two demo.doc documents. The original /usr/shemacs/demo.doc and the demo.doc inside the sherver's directory. The latter is the one that is edited by shemacs clients.

To save the shared demo.doc, select the ?Save Document? menu item (C-c s or M-x shm*cmd*savedocument). You will notice that the usual minibuffer message you get after saving a buffer will appear at the sherver's minibuffer. This is because, true to a client-server system, the saving was actually performed at the sherver.

9 Goodies

If you plan to access the demo.doc document often, you can add it to your ?Bookmarks? menu by selecting the menu item ?Bookmarks -> Add Bookmark?. Thereafter, demo.doc can be quickly opened from the ?Bookmarks? menu, but you will still need to enter your login and password if you have not connected to the sherver.

You can also add commonly accessed Shemacs servers to your Shervers menu. The ?Shervers -> Add host.domain.port? menu item will add the sherver for the current document to your Shervers menu. After that, you can easily connect to the sherver by simply selecting it from the Shervers menu. After connecting, the sherver's documents will be available under that sherver's menu item. All of these settings are automatically saved to your .shemacs file in your home directory.

10 Closing up

When you are done editing a region you have claimed, you can relinquish it by selecting the ?Close Region? menu item (C-c c or M-x shm*cmd*close-region). Make sure your cursor is in the region you want to close.
If you are completely done editing a shared document, select the ?Close Document? menu item (C-c k or M-x shm*cmd*close-document).

If you wish to close all documents for a particular sherver, go to any document from that sherver and select the ?Shervers -> Disconnect from host.domain.port? menu item. Note that this will disconnect your connection to that sherver and that you will need to login again if you want to access any document from that sherver.

11 Quitting Shemacs

To quit a Shemacs client, select the ?Exit Shemacs? menu item (M-x shm*cmd*exit-shemacs). This will perform the client updates, closing, saving and disconnection necessary to preserve your editing changes.

To quit the Shemacs server, select the ?Shutdown Sherver? menu item (M-x shm*cmd*shutdownsherver) on the sherver. Make sure that all shemacs clients have logged out or their changes will be lost.

12 Exercise

Bringing up several shervers (in different hosts if possible), submit documents to each one of them, and open one document from each sherver using the same shemacs client.