				VSSExtractor & CServer
					MANUAL file


Here you will find a few guidelines on how to use the software. However, this
is not at all a complete manual yet! Any help for writing documentation would 
be highly appreciated.


1/ How to configure and run the program

First you'll need to properly install both parts of the program (the windows 
client and the Linux server). Please see the INSTALL file for installation
instructions.

Server program needs a configuration file, cserver.conf, to run properly.
Package contains a sample, documented cserver.conf file, please have a look
at it. It mainly specifies the ports for network connections, the name of the
log file and of the temp directory.
When config file is OK, simply run ./cserver to start conversion server. 
The server will give you various informations about its status and the 
information it gets from the client. You need not worry about it too much : 
once started, the server program gets all its input from the client program
and does not need user intervention.

Client program needs a configuration file, too. Its name is VSSExtractor.ini and it should be placed in the current directory when you run VSSExtractor.
You'll also need to place Xerces DLL somewhere in your PATH.
Config file contains system-related parameters (name and port on the server, 
name of the log file, name of the temp dir) along with conversion-specific
parameters (name of the projects to convert, conversion mode, recursion, 
name of XML report file, and so on). Please see sample VSSExtractor.ini file for information on parameters to be provided.
Once config file is OK, simply run VSSExtractor.exe. 


2/ How to use the program to convert files

As to the server, the only thing you have to do is to edit the config file and 
run cserver program, and it will build a CVS repository for you.

To run a conversion, you must specify, in windows VSSExtractor.ini config file,
at least one project to convert, using a line

[Project] $/myproject/mysubproject

(there can be as many projects as you want - but, if you allow recursion, you
need not enumerate all subprojects!).

You'll have to specify if you want to recurse down through the subprojects
( [Recursion] tag in config file) and if you want the program to pause to 
allow you to edit the XML file ([EditXML] tag in config file). When you think
your config file is OK, run VSSExtractor.exe.

The program will first browse through project tree and project history in 
SourceSafe database, then it will generate an XML report about the projects
you are to convert.
If you enabled the program to do so, it will stop to show you the XML report
and to allow you to set conversion parameters. Otherwise you'll get a 
default conversion process.

Then the client program will try to connect to the server (which must be up and waiting at that time), and will run the conversion, which will take a little 
time, especially when converting a large project through a slow network 
connection.
Client and server program will continuously give an output of what they are 
doing, they will also generate log files about the conversion process.
Conversion should end successfully, then client program will terminate and
server will return to idle mode.


3/ XML report and configuration file

While extracting data from sourcesafe database, client program will generate
an XML report about the projects being processed. This file, after modification,
will be used as a config file for making the CVS repository.
Here are a few words on the contents of the XML file.

* <Parameters> section
	<AllowRelocation> Yes/No
		allows to specify a target name for a project, different from its
		original sourcesafe name.
	<Allowbinaries> Yes/No
		if No, all files will be considered text
	<WriteMode> Insert/Replace
		if Replace, will delete any existing CVS module with the same name
		as the project being converted
	<From> ALL/YYYY.MM.DD.HH.MM.SS/Label "mylabel"/Version XXXX
	<To> ALL/YYYY.MM.DD.HH.MM.SS/Label "mylabel"/Version XXXX
		These parameters are for incremental conversion.
		If ALL, the whole project history will be converted.
		Otherwise, the conversion will only operate from or to the given 
		timestamp, label or project version. Note that timestamp has to
		be given under this specific CVSlike format, that a label has to be
		quoted (and preceded by the word Label), and a version has to be a 
		number (preceded by the word Version).

* <Userlist> section
	<Mode> Simple/Mapped
		Simple mode checks all SourceSafe users in CVS user list, and, for 
		those not registered, creates a new user mapped on DefaultUser
		(see CVS doc about this user mapping)
		Mapped mode maps each SourceSafe user to a CVS user
	<Defaultuser> user
		A default unix/cvs user 
	<User>
		<VSSUser> username1
		<CVSUser> username2
	</User>
		In Simple mode, CVSUser can be blank
		In mapped mode both fields must be set

* <Subdir> section
	Here comes a recursive structure of <Subdir>s describing the project
	tree. Some <Subdir> blocks can be removed if you do not want the
	corresponding projects to be converted.

	For each <Subdir> node, the following parameters can be specified :
	<SourcePath> name of the subproject in SourceSafe
	<DestPath> name of the subdir in CVS repository (if AllowRelocation)
	<Branch> yes/no if this project is a share from another one
	
	Shared, deleted and checked-out files will be reported for each 
	project within this <Subdir> block - for information only.


4/ Conversion modes

Standard conversion mode is the one described over.
However, another conversion mode can be used when you already have an XML file
(for example, when you have already converted a project and you want to do
an incremental conversion to take recent changes into account).

To access this mode you'll need to set [GenerateXML] to No in VSSExtractor.ini
config file. The program will look for an existing XML file (and will terminate
if it cannot find it), then run the conversion according to the parameters
fond in that file.


5/ That's it!

Hope these few hints will help you understand and use VSSExtractor/Cserver 
program. A more detailed documentation is to be expected in a few time.




