DVS - EXAMPLE

This document is intended to be a very short tutorial for the use of
dvs. A `reference' guide is provided by the dvs man page. Even
though it is not strictly necessary, it's good to know the basics of
NUCM and its data model. To do so, refer to the NUCM documentation.

INDEX
	0- Setting up the NUCM repository
	1- Example scenario
	2- Setting up the initial workspace
	3- Adding a file or a collection to an existing collection
	4- Modifying artifacts
	5- Closing artifacts
	6- Using multiple servers

0- Setting up the NUCM repository

The example here assumes that a NUCM database is correctly set up and
that a NUCM server is running on serl.cs.colorado.edu using port
1969. Refer to the NUCM documentation for details. Here is a quick
start-up procedure to create a NUCM repository and run the NUCM
server:

% cd /home/carzanig/test
% /tools/serl/nucm-2.0/bin/createrepository DVS

there should not be any file or directory named DVS in
/home/carzanig/test. /tools/serl/nucm-2.0 is the directory in which
NUCM-2.0 is installed. These commands create the repository that I
will use in the following. Now I have to run the NUCM server:

% /tools/serl/nucm-2.0/bin/nucmserver -port 1969 \
                                      -ndbhome
                                      /home/carzanig/test/DVS &

the nucmserver will use the tcp port 1969, so that port should not be
used by any other application. The NUCM server will occasionally print
out some log messages, if you don't want those to be mixed with the
other NUCM-RCS messages, you can redirect stdout and stderr to
/dev/null.


1- Example scenario

In this example, I want to use dvs to maintain all the files related
to a paper. My server is running on serl, so I can either run the
client commands (dvs) from serl or run them from any other machine,
provided that I set the NUCMHOST and NUCMPORT variables appropriately.

% setenv NUCMHOST serl.cs.colorado.edu
% setenv NUCMPORT 1969


2- Setting up the initial workspace

A NUCM database comes with a `root' collection named `nucm_root'. Thus,
the first step is to add some files or some collections to the
nucm_root.

% cd ~
% dvs co -l nucm_root

this checks out and locks the last version of nucm_root (version 1 for
an empty repository). Now a directory called nucm_root shows up in my
home directory. Suppose I already have a directory that contains some
files of my paper, e.g., ~/papers/icse98, then I just move (or copy)
that directory into the workspace and check it in:

% cd nucm_root
% mv ~/papers/icse99 .
% dvs ci -R -m "baseline" icse99

The -R option checks in recursively every file and directory in
icse99. The -m "message" option sets the log message for all the
check-in operations. If I don't specify -m "message", dvs asks for a
log message for every file.

I want to bind immediately icse99 to nucm_root, so I also check in
nucm_root:

% pwd
/home/serl/carzanig/nucm_root
% dvs ci .


3- Adding a file or a collection to an existing collection

Obviously, I can also create and check in one single file, e.g.,
suppose I want to add the file abstract.tex to the icse99 directory:

% dvs lock icse99
% cd icse99
% emacs abstract.tex 
% dvs ci abstract.tex

Similarly I can add a (sub)collection:

% mkdir bib
% dvs ci bib


4- Modifying artifacts

Once a base workspace is set-up I can go through the usual
checkout+lock - edit - checkin cycle:

% dvs co -l example.tex
% emacs example.tex
% dvs ci example.tex

Eventually, I have to check in the current working directory (icse99)
to produce a new version of the main collection that includes the new
files and the new versions:

% dvs ci .


5- Closing artifacts

I can remove the local workspace by issuing:

% cd ..
% pwd
/home/serl/carzanig/nucm_root
% dvs close icse99
% cd ..
% dvs close nucm_root


6- Using artifacts from other servers (Distributed Cooperation)

First I have to open my workspace again. Now I can open it directly in
my paper directory :

% cd ~/papers
% dvs co -R -l -last nucm_root:2/icse99

This contacts the default server (serl:1234) and checks out with lock
the latest version of the icse99 collection. Now I have all the paper
in ~/papers/icse99. 

Now I want to use a file that a friend of mine has stored in his nucm
server on ipese0.elet.poimi.it:2345. I know that a NUCM server is
running there and that there is a file called conclusion.tex in
//ipese0.elet.poimi.it:2345/nucm_root:3/article:2/

% cd icse99
% dvs link //ipese0.elet.poimi.it:2345/nucm_root:3/article:2/conclusion.tex

By doing this I add to the icse99 collection a ``pointer'' to the
conclusion.tex artifact. Now I can use check-in, check-out, lock, log,
etc. on conclusion.tex as if it was a `local' artifact. Whenever
necessary, dvs will access the remote server.

% dvs co -l -last conclusion.tex
% emacs conclusion.tex
% dvs ci conclusion.tex
% dvs ci .
% dvs log conclusion.tex





