Read this before modifying or creating command files for the portal. 

Each file identifies a service that is to be run and the parameters for that service.  
It also specifies any subservices that will be employed and their parameters.  The 
portal uses these files in two ways:

	1. The portal marshals the file into an IDL CommandObject and passes the
	CommandObject to the service to run an anaylsis using that service.

	2. If the portal user wants to configure parameters for the service, the
	portal presents a Gui by using the ui xml file for the service and 
	initializing the components based on the parameters specified in the
	command file.

While the services themselves tend to be fairly flexible about the way the
commands are specified in these xml files, Guigen is *very* picky about the order, 
spacing, case, etc used in the command file.  Inorder to work with guigen, these
files must be generated by guigen! 

PERSISTPARAMS.SH 
================================================================================================================
So how do you generate/modify these files ?  Run persistParams.sh which can
be found in the cipres/build/bin directory.   

	 1. From the Main menu, choose "Get Nexus", and pick a nexus file to work with (it 
	 doesn't matter which one, but choose something SMALL!).

	 2. Again, from the Main (and only) menu, choose "Infer Tree" or "Improve Tree",
	 and then pick the desired service from the list.  

	 3. Set the parameters in the gui and press the "Launch" button.

	 4. Choose the directory and file where the parameters will be saved (this
	 is the step that creates the command xml file).

	 5. At this point the service will be run and you'll be shown the final tree
	 in a message box when it finishes.  You'll be prompted to save the results,
	 but just press the Cancel button if you don't care about them.

	 6. Now you can verify that the command xml file you created can by used
	 to run a service: select "Improve Tree (using stored parameters)" from
	 the Main menu, then navigate to and choose the file you created in
	 step 4.

If you need to tweak the generated files by hand, be careful not to add whitespace.  
If you need to add extra commands that can't be set via the gui, add them in a
separate <commands> element (To Do: I haven't tested whether this work or not.)

TESTGUIXML.JAVA 
=============================================================================================================
To verify that the gui you've tweaked can still be processed by guigen (and that the
gui is initialized with the commands specified in the command xml file), run  

	cipresclass.sh -Dgui=<guixml_file> -Dcommands=<commandxml_file> -Dout=<outputxml_file> \
	-Dapplet=1 org.cipres.guigen.TestGuiXml

This will display the gui.  Verify that it's populated with the values from <commandxml_file>.  
When you press the LAUNCH button, it will serialize the commands from the gui to <outputxml_file>.  
So long as you didn't enter or modify any data in the gui, <commandxml_file> and <outputxml_file> should 
be indentical.

Use the -Dfl (force launch) system parameter to run in "batch" mode.  The program will display
the gui very briefly, then will simulate the pressing of the LAUNCH button, to automatically
save the commands to the file specified by -Dout and exit.

TO DO
=============================================================================================================
Terri, notes to myself: 

1. Many of the command xml files for the portal were hand editted and won't work with
guigen; I need to test and correct them.

2. See if handling of additional hand coded <command> elements works.  The commands shouldn't
interfere with the gui but should be passed on in the results/output.  That latter step
will probably require some changes.

3. See Mark Holder's email about a better format for the command xml file (in my guigen
mailbox).  Adding a <extra-commands> element to the command xml.  Command xml would cease
to be a serialization of the IDL generated CommandObject.

4. Write a script to run TestGuiXml in batch mode, doing the diffs.

5. PersistParams.sh To Do:
	- running service should be optional so that you can record commands even if you don't
	have the tool installed.

	- optionally, initialize gui from a command file.