[CIShell-SVN] SF.net SVN: cishell: [642] trunk/core/org.cishell.docs/src

[<bh...@us...>]

Revision: 642
          http://cishell.svn.sourceforge.net/cishell/?rev=642&view=rev
Author:   bh2
Date:     2008-03-04 15:53:10 -0800 (Tue, 04 Mar 2008)

Log Message:
-----------
* fixed doclet to fix some latex output bugs
* incorporating lots of various suggestions from team members
* fought an epic battle with latex/javadoc to make it line break in a sane manner
* added exceptions to algorithm and converter
* made periods in javadocs consistent: Javadocs with only one 'sentence' do not get a period. Those with more than one 'sentence' do.
* added a section on 'dataset algorithms'
* added DataProperty.SHORT_LABEL

Modified Paths:
--------------
    branches/spec_update/org.cishell.framework/src/org/cishell/app/service/datamanager/DataManagerListener.java
    branches/spec_update/org.cishell.framework/src/org/cishell/app/service/datamanager/DataManagerService.java
    branches/spec_update/org.cishell.framework/src/org/cishell/app/service/scheduler/SchedulerListener.java
    branches/spec_update/org.cishell.framework/src/org/cishell/app/service/scheduler/SchedulerService.java
    branches/spec_update/org.cishell.framework/src/org/cishell/framework/CIShellContext.java
    branches/spec_update/org.cishell.framework/src/org/cishell/framework/LocalCIShellContext.java
    branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/Algorithm.java
    branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/AlgorithmFactory.java
    branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/DataValidator.java
    branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressMonitor.java
    branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressTrackable.java
    branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/BasicData.java
    branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/Data.java
    branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/DataProperty.java
    branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/Converter.java
    branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/DataConversionService.java
    branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/GUI.java
    branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/GUIBuilderService.java
    branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/SelectionListener.java
    trunk/core/org.cishell.docs/src/specification/main.tex
    trunk/core/org.cishell.docs/src/specification/tex/algorithms.tex
    trunk/core/org.cishell.docs/src/specification/tex/algorithmtypes.tex
    trunk/core/org.cishell.docs/src/specification/tex/data.tex
    trunk/core/org.cishell.docs/src/specification/tex/dataconversionservice.tex
    trunk/core/org.cishell.docs/src/specification/tex/datamanagerservice.tex
    trunk/core/org.cishell.docs/src/specification/tex/framework.tex
    trunk/core/org.cishell.docs/src/specification/tex/introduction.tex
    trunk/core/org.cishell.docs/src/specification/tex/logservice.tex
    trunk/core/org.cishell.docs/src/specification/tex/osgidependencies.tex
    trunk/core/org.cishell.docs/src/specification/tex/preferencesservice.tex
    trunk/core/org.cishell.docs/src/specification/tex/schedulerservice.tex
    trunk/core/org.cishell.docs/src/texdoclet/src/org/wonderly/doclets/TexDoclet.java

Added Paths:
-----------
    branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/AlgorithmExecutionException.java
    branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/ConversionException.java

Modified: branches/spec_update/org.cishell.framework/src/org/cishell/app/service/datamanager/DataManagerListener.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/app/service/datamanager/DataManagerListener.java	2008-02-27 19:04:07 UTC (rev 641)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/app/service/datamanager/DataManagerListener.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -17,7 +17,7 @@
 
 
 /**
- * A listener that is notified of changes in the {@link DataManagerService}.
+ * A listener that is notified of changes in the {@link DataManagerService}
  * 
  * @author Bruce Herr (bh...@bh...)
  */

Modified: branches/spec_update/org.cishell.framework/src/org/cishell/app/service/datamanager/DataManagerService.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/app/service/datamanager/DataManagerService.java	2008-02-27 19:04:07 UTC (rev 641)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/app/service/datamanager/DataManagerService.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -94,7 +94,7 @@
      * to change the label so that it is unique.
      * 
      * @param data The Data
-     * @param label The new label for the data model.
+     * @param label The new label for the data model
      */
     public void setLabel(Data data, String label);
 }

Modified: branches/spec_update/org.cishell.framework/src/org/cishell/app/service/scheduler/SchedulerListener.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/app/service/scheduler/SchedulerListener.java	2008-02-27 19:04:07 UTC (rev 641)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/app/service/scheduler/SchedulerListener.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -45,7 +45,7 @@
     
     /**
      * Notification that an already scheduled Algorithm has been unscheduled
-     * and will therefore not be run.
+     * and will therefore not be run
      * 
      * @param algorithm The scheduled Algorithm that was unscheduled
      */
@@ -62,8 +62,8 @@
      * Notification that an Algorithm has finished executing
      * 
      * @param algorithm The scheduled Algorithm
-     * @param createdData The Data(s) it returned, or <code>null</code> if
-     *                  it returned <code>null</code>
+     * @param createdData The {@link Data} array it returned, or 
+     * 					  <code>null</code> if it returned <code>null</code>
      */
     public void algorithmFinished(Algorithm algorithm, Data[] createdData);
     
@@ -86,7 +86,7 @@
     
     /**
      * Notification that the scheduler's schedule of Algorithms to be run has 
-     * been cleared.
+     * been cleared
      */
     public void schedulerCleared();
 }

Modified: branches/spec_update/org.cishell.framework/src/org/cishell/app/service/scheduler/SchedulerService.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/app/service/scheduler/SchedulerService.java	2008-02-27 19:04:07 UTC (rev 641)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/app/service/scheduler/SchedulerService.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -89,7 +89,7 @@
     public boolean unschedule(Algorithm algorithm);
     
     /**
-     * Adds a listener to be notified of events happening in the scheduler. 
+     * Adds a listener to be notified of events happening in the scheduler
      * 
      * @param listener The listener to be added
      */
@@ -138,7 +138,7 @@
      * 
      * @param algorithm The Algorithm
      * @return The scheduled time for the Algorithm to run or <code>null</code>
-     *         if the Algorithm is not scheduled or has completed execution.
+     *         if the Algorithm is not scheduled or has completed execution
      */
     public Calendar getScheduledTime(Algorithm algorithm);
     

Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/CIShellContext.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/CIShellContext.java	2008-02-27 19:04:07 UTC (rev 641)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/CIShellContext.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -44,10 +44,10 @@
      * Locates and returns a standard service given the service name. The 
      * service name is generally the full class name of the service interface.
      * For example, <code>LogService</code>'s string is 
-     * <code>org.osgi.service.log.LogService</code>
+     * <code>org.osgi.service.log.LogService</code>.
      * 
      * @param service A string (usually the associated interface's full 
-     *                class name) that specifies the service to retrieve.
+     *                class name) that specifies the service to retrieve
      * @return An instantiated version of the service requested
      */
     public Object getService(String service);

Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/LocalCIShellContext.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/LocalCIShellContext.java	2008-02-27 19:04:07 UTC (rev 641)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/LocalCIShellContext.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -36,7 +36,7 @@
      * <code>BundleContext</code>
      * 
      * @param bContext The <code>BundleContext</code> to use to find 
-     *                 the registered standard services. 
+     *                 the registered standard services
      */
     public LocalCIShellContext(BundleContext bContext) {
         this(bContext, DEFAULT_SERVICES);
@@ -48,9 +48,9 @@
      * this <code>CIShellContext</code>.
      * 
      * @param bContext         The <code>BundleContext</code> to use to find 
-     *                         registered standard services.
+     *                         registered standard services
      * @param standardServices An array of strings specifying the services that
-     *                         are allowed to be retrieved from this class.
+     *                         are allowed to be retrieved from this class
      */
     public LocalCIShellContext(BundleContext bContext, String[] standardServices) {
         this.bContext = bContext;

Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/Algorithm.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/Algorithm.java	2008-02-27 19:04:07 UTC (rev 641)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/Algorithm.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -28,9 +28,13 @@
 public interface Algorithm {
     
    /**
-    * Executes and optionally returns a Data array. 
+    * Executes and optionally returns a Data array
     * 
-    * @return A Data array that was created or <code>null</code>
+    * @return A Data array that was created. <code>null</code> is ONLY acceptable
+    * when the algorithms out_data is null.
+    * @throws AlgorithmExecutionException An exception has occured while executing
+    * the algorithm. This exception should have a user-comprehendable message if
+    * at all possible.
     */
-   public Data[] execute(); 
+   public Data[] execute() throws AlgorithmExecutionException; 
 }

Added: branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/AlgorithmExecutionException.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/AlgorithmExecutionException.java	                        (rev 0)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/AlgorithmExecutionException.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -0,0 +1,32 @@
+/* **************************************************************************** 
+ * CIShell: Cyberinfrastructure Shell, An Algorithm Integration Framework.
+ * 
+ * All rights reserved. This program and the accompanying materials are made
+ * available under the terms of the Apache License v2.0 which accompanies
+ * this distribution, and is available at:
+ * http://www.apache.org/licenses/LICENSE-2.0.html
+ * 
+ * Created on Feb 8, 2008 at Indiana University.
+ * 
+ * Contributors:
+ *     Indiana University - Initial API
+ * ***************************************************************************/
+package org.cishell.framework.algorithm;
+
+/**
+ * An exception which is thrown when an error occurs in the process of executing
+ * an {@link Algorithm}
+ * 
+ * @author Bruce Herr (bh...@bh...)
+ */
+public class AlgorithmExecutionException extends Exception {
+	private static final long serialVersionUID = 9017277008277139930L;
+
+	public AlgorithmExecutionException(Exception exception) {
+		super(exception);
+	}
+	
+	public AlgorithmExecutionException(String message) {
+		super(message);
+	}
+}

Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/AlgorithmFactory.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/AlgorithmFactory.java	2008-02-27 19:04:07 UTC (rev 641)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/AlgorithmFactory.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -22,18 +22,18 @@
 /**
  * A class for creating {@link Algorithm}s. This class provides the 
  * parameters needed by its associated <code>Algorithm</code> on demand and when
- * given correct data, will create an <code>Algorithm</code> that can be executed. 
- * An algorithm developer who wishes to be usable by CIShell applications must 
- * create an implementation of this interface and register it (along with some 
- * standard metadata about the algorithm, defined in the 
- * {@link AlgorithmProperty} class) in the OSGi service registry. 
+ * given correct data, will create an <code>Algorithm</code> that can be executed.
+ * <br> 
+ * An algorithm developer must create an implementation of this interface and 
+ * register it (along with some standard metadata about the algorithm, defined 
+ * in the {@link AlgorithmProperty} class) in the OSGi service registry. 
  * 
  * @author Bruce Herr (bh...@bh...)
  */
 public interface AlgorithmFactory {
     /**
-     * Creates a set of parameter definitions that define what parameters are 
-     * needed in order to run its associated Algorithm.  
+     * Creates a set of parameter definitions that specify what parameters are 
+     * needed in order to run its associated Algorithm
      * 
      * @param data An optional argument, the Data array that will be given to 
      *           this class to create an Algorithm with the createAlgorithm 
@@ -46,7 +46,7 @@
     public MetaTypeProvider createParameters(Data[] data);
     
     /**
-     * Creates an {@link Algorithm} to be executed. 
+     * Creates an {@link Algorithm} to be executed
      * 
      * @param data       The data to be given to the Algorithm to process. 
      *                   Some Algorithms may ignore this value. The order and
@@ -54,7 +54,7 @@
      *                   dictionary (the 'in_data' key) when registered as a 
      *                   service in OSGi.
      * @param parameters A set of key-value pairs that were created based on 
-     *                   the parameters given by the createParameters method.
+     *                   the parameters given by the createParameters method
      * @param context    The context by which the Algorithm can gain access to 
      *                   standard CIShell services
      * @return An <code>Algorithm</code> primed for execution

Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/DataValidator.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/DataValidator.java	2008-02-27 19:04:07 UTC (rev 641)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/DataValidator.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -24,7 +24,7 @@
  * make additional checks. For example, if an algorithm only worked on 
  * symmetric matrices, this interface would check the data ahead of time
  * to ensure that the given matrix was in fact a symmetric matrix.
- * <br />
+ * <br>
  * In order for CIShell applications to fully recognize this additional validation 
  * method, an algorithm developer must register this interface in addition to the 
  * algorithm interface when registering their service.

Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressMonitor.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressMonitor.java	2008-02-27 19:04:07 UTC (rev 641)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressMonitor.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -59,14 +59,14 @@
 	
     /**
      * Notifies the start of execution of the algorithm in addition to 
-     * revealing how many work units will be used.  
+     * revealing how many work units will be used 
      * 
      * @param capabilities   An OR'ed int that tells the monitor what the 
      *                       algorithm is capable of with respect to the 
      *                       monitor. The OR'ed values are taken from the int
      *                       constants specified in this interface.
      * @param totalWorkUnits The number of work units, -1 if the  
-     *                       algorithm does not provide progress information.
+     *                       algorithm does not provide progress information
      */
     public void start(int capabilities, int totalWorkUnits);
     
@@ -74,19 +74,19 @@
      * Notifies that a certain number of units of work has been completed
      * 
      * @param work The number of units of work completed 
-     *             since last notification.
+     *             since last notification
      */
     public void worked(int work);
     
     /**
-     * The algorithm is finished executing.
+     * The algorithm is finished executing
      */
     public void done();
     
     /**
      * Sets or clears a flag for cancellation of this algorithm's execution.
      * An algorithm developer can ignore or clear this flag if it cannot stop 
-     * midstream. This is one of the methods that can be called by someone 
+     * midstream. This is one of the methods that can be called by something 
      * other than the algorithm.
      * 
      * @param value Set or clear the cancellation request
@@ -105,7 +105,7 @@
     /**
      * Sets or clears a flag for pausing of this algorithm's execution. An
      * algorithm developer can ignore or clear this flag if it cannot pause 
-     * midstream. This is one of the methods that can be called by someone 
+     * midstream. This is one of the methods that can be called by something 
      * other than the algorithm.
      * 
      * @param value Set or clear the pause request
@@ -123,7 +123,7 @@
     
     /**
      * Method to describe what the algorithm is currently doing for the benefit
-     * of the users of the algorithm as it progresses during execution.
+     * of the users of the algorithm as it progresses during execution
      * 
      * @param currentWork A short description of the current work the algorithm
      *                    is doing

Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressTrackable.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressTrackable.java	2008-02-27 19:04:07 UTC (rev 641)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressTrackable.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -38,10 +38,10 @@
     
     /**
      * Returns the progress monitor currently in use, or <code>null</code> if
-     * no monitor has been set.
+     * no monitor has been set
      * 
      * @return The current progress monitor, or <code>null</code> if there 
-     * isn't one set.
+     * isn't one set
      */
     public ProgressMonitor getProgressMonitor();
 }

Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/BasicData.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/BasicData.java	2008-02-27 19:04:07 UTC (rev 641)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/BasicData.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -58,9 +58,9 @@
     }
 
     /**
-     * @see org.cishell.framework.data.Data#getMetaData()
+     * @see org.cishell.framework.data.Data#getMetadata()
      */
-    public Dictionary getMetaData() {
+    public Dictionary getMetadata() {
         return properties;
     }
 

Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/Data.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/Data.java	2008-02-27 19:04:07 UTC (rev 641)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/Data.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -29,10 +29,10 @@
 	 * 
 	 * @return The data's metadata
 	 */
-    public Dictionary getMetaData();
+    public Dictionary getMetadata();
     
     /**
-     * Returns the data stored in this Data object.
+     * Returns the data stored in this Data object
      * 
      * @return The data (a Java object)
      */

Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/DataProperty.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/DataProperty.java	2008-02-27 19:04:07 UTC (rev 641)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/DataProperty.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -16,7 +16,7 @@
 
 /**
  * Standard property keys to use when creating metadata for a 
- * {@link Data} object.
+ * {@link Data} object
  * 
  * @author Bruce Herr (bh...@bh...)
  */
@@ -28,12 +28,20 @@
     public static final String LABEL = "Label";
     
     /** 
+     * A short label to give the Data object for shorter displays. It is 
+     * recommended to keep the string length below 20 characters. This will often
+     * be used for recommended file names when saving the data to disk. The type 
+     * associated with this property is of type {@link String}.
+     */
+    public static final String SHORT_LABEL = "Short_Label";
+    
+    /** 
      * The parent Data object of the Data object. This is used when a Data object
      * is derived from another Data object to show the hierarchical relationship
      * between them. This property can be null, signifying that the Data object
      * was not derived from any other Data object, such as when loading a new Data
      * object from a file. The type associated with this property is of type 
-     * {@link Data} 
+     * {@link Data}.
      */
     public static final String PARENT = "Parent";    
     
@@ -48,7 +56,7 @@
     /**
      * Flag to determine if the Data object has been modified and not saved since
      * the modification. This is used to do things like notify the user before 
-     * they exit that a modified Data object exists and see if they want to save 
+     * they exit that a modified Data object exists and ask if they want to save 
      * it. The type associated with this property is of type {@link Boolean}.
      */
     public static final String MODIFIED = "Modified";
@@ -68,6 +76,6 @@
     /** Says this data model is abstractly a plain text file */
     public static String TEXT_TYPE = "Text";
     
-    /** Says this data model is abstractly an informational graph. */
-    public static String GRAPH_TYPE = "Graph";
+    /** Says this data model is abstractly a data plot */
+    public static String PLOT_TYPE = "Plot";
 }

Added: branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/ConversionException.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/ConversionException.java	                        (rev 0)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/ConversionException.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -0,0 +1,33 @@
+/* **************************************************************************** 
+ * CIShell: Cyberinfrastructure Shell, An Algorithm Integration Framework.
+ * 
+ * All rights reserved. This program and the accompanying materials are made
+ * available under the terms of the Apache License v2.0 which accompanies
+ * this distribution, and is available at:
+ * http://www.apache.org/licenses/LICENSE-2.0.html
+ * 
+ * Created on Feb 8, 2008 at Indiana University.
+ * 
+ * Contributors:
+ *     Indiana University - Initial API
+ * ***************************************************************************/
+package org.cishell.service.conversion;
+
+
+/**
+ * An exception which is thrown when an error occurs in the process of data 
+ * conversion
+ * 
+ * @author Bruce Herr (bh...@bh...)
+ */
+public class ConversionException extends Exception {
+	private static final long serialVersionUID = 1749134893481511313L;
+
+	public ConversionException(Exception exception) {
+		super(exception);
+	}
+	
+	public ConversionException(String message) {
+		super(message);
+	}
+}

Modified: branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/Converter.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/Converter.java	2008-02-27 19:04:07 UTC (rev 641)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/Converter.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -21,7 +21,7 @@
 import org.osgi.framework.ServiceReference;
 
 /**
- * A class for converting Data objects.
+ * A class for converting Data objects
  * 
  * @author Bruce Herr (bh...@bh...)
  */
@@ -29,16 +29,16 @@
     
     /**
      * Returns an array of ServiceReferences to converter algorithms in the order
-     * in which they will be called when converting a Data object.
+     * in which they will be called when converting a Data object
      *  
-     * @return An array of ServiceReferences to converter algorithms to be used. 
+     * @return An array of ServiceReferences to converter algorithms to be used
      */
     public ServiceReference[] getConverterChain();
     
     /**
      * Returns the AlgorithmFactory that can be invoked to convert a given 
      * Data object of the correct input format (as specified in the Dictionary 
-     * from getProperties()) to a Data object of the correct output format.
+     * from getProperties()) to a Data object of the correct output format
      * 
      * @return The AlgorithmFactory to do the converting
      */
@@ -58,11 +58,11 @@
     /**
      * Uses this Converter to convert the given Data object to a new format. 
      * This is a convenience method that uses this Converter to convert a Data 
-     * object of the corrent format to a Data object of the defined output format
+     * object of the corrent format to a Data object of the defined output format.
      * 
      * @param data The Data object with compatible format
-     * @return A Data object of correct output format, or <code>null</code> if the
-     *         conversion fails
+     * @return A Data object of correct output format
+     * @throws ConversionException If the data conversion fails while converting
      */
-    public Data convert(Data data);
+    public Data convert(Data data) throws ConversionException;
 }

Modified: branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/DataConversionService.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/DataConversionService.java	2008-02-27 19:04:07 UTC (rev 641)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/DataConversionService.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -46,8 +46,8 @@
 	 * 			        String should be formatted in the same way as an 
 	 *                  algorithm's {@link AlgorithmProperty#OUT_DATA}.
 	 * @return An array of {@link Converter}s that can convert a Data object of
-	 *         the given inFormat to the given outFormat, or <code>null</code> 
-	 *         if there is no way to convert.
+	 *         the given inFormat to the specified outFormat, or 
+	 *         <code>null</code> if there is no valid conversion sequence
 	 */
     public Converter[] findConverters(String inFormat, String outFormat);
     
@@ -57,20 +57,22 @@
      * 
      * @param data      The Data object to convert
      * @param outFormat The output format to convert to
-     * @return An array of converters (may be zero length) that can convert the
-     *         given Data object to the specified output format.
+     * @return An array of {@link Converter}s that can convert the
+     *         given Data object to the specified output format, or 
+     *         <code>null</code> if there is no valid conversion sequence
      */
     public Converter[] findConverters(Data data, String outFormat);
     
     /**
      * Tries to convert a given Data object to the specified output format. If 
      * the conversion fails or there is no way to convert it, this method will 
-     * return a <code>null</code>
+     * return a <code>null</code>.
      * 
      * @param data      The Data to convert
      * @param outFormat The format of the Data object to be returned 
      * @return A Data object with the specified output format, or 
-     *         <code>null</code> if the conversion fails
+     * 		   <code>null</code> if there is no valid conversion sequence
+     * @throws ConversionException If the data conversion fails while converting
      */
-    public Data convert(Data data, String outFormat);
+    public Data convert(Data data, String outFormat) throws ConversionException;
 }

Modified: branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/GUI.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/GUI.java	2008-02-27 19:04:07 UTC (rev 641)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/GUI.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -24,13 +24,13 @@
 public interface GUI {
 	/**
      * Pops up this GUI, gets data from the user, and returns what they entered.
-     * This is a convenience method that first opens the GUI, then pops the GUI 
-     * up to the user, who then enters in the needed information, which is then 
+     * This is a convenience method that first opens the GUI, then shows the GUI 
+     * to the user, who then enters in the needed information, which is then 
      * taken and put into a {@link Dictionary}, and is given to this method's 
      * caller.
      * 
-	 * @return The data the user entered or <code>null</code> if they cancelled
-	 *         the operation.
+	 * @return The data the user entered or <code>null</code> if the operation 
+	 * 		   was cancelled
 	 */
     public Dictionary openAndWait();
     
@@ -52,7 +52,7 @@
     
     /**
      * Sets the selection listener to be informed when the user finishes 
-     * entering information and hits 'Ok' or cancels.
+     * entering information and hits 'Ok' or cancels
      * 
      * @param listener The listener to notify
      */

Modified: branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/GUIBuilderService.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/GUIBuilderService.java	2008-02-27 19:04:07 UTC (rev 641)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/GUIBuilderService.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -35,7 +35,7 @@
  * 
  * Algorithm writers are encouraged to use this service if they need to get
  * additional input from the user rather than creating their own GUI. This is
- * to ensure a consistant user input method and so that the GUI can easily be 
+ * to ensure a consistent user input method and so that the GUI can easily be 
  * routed to the user when running remotely.
  * 
  * @author Bruce Herr (bh...@bh...)
@@ -66,8 +66,8 @@
 	 *                   MetaTypeProvider
 	 * @param parameters Provides the parameters needed to get information from 
 	 *                   the user
-     * @return The data the user entered or <code>null</code> if they cancelled
-     *         the operation.
+     * @return The data the user entered or <code>null</code> if the operation 
+     * 		   was cancelled
      */
     public Dictionary createGUIandWait(String id, MetaTypeProvider parameters);
     
@@ -77,7 +77,7 @@
      * @param title   The title of the pop-up
      * @param message The message to display
      * @param detail  Additional details
-     * @return If they clicked "Ok", <code>true</code>, otherwise 
+     * @return If they clicked "Ok," <code>true</code>, otherwise 
      *         <code>false</code>
      */
     public boolean showConfirm(String title, String message, String detail);
@@ -88,7 +88,7 @@
      * @param title   The title of the pop-up
      * @param message The question to display
      * @param detail  Additional details
-     * @return If they clicked "Yes", <code>true</code>, otherwise 
+     * @return If they clicked "Yes," <code>true</code>, otherwise 
      *         <code>false</code>
      */
     public boolean showQuestion(String title, String message, String detail);

Modified: branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/SelectionListener.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/SelectionListener.java	2008-02-27 19:04:07 UTC (rev 641)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/SelectionListener.java	2008-03-04 23:53:10 UTC (rev 642)
@@ -17,8 +17,8 @@
 
 /**
  * A listener that is notified when all values entered by a {@link GUI} user 
- * have been validated and they have clicked 'Ok' to proceed or if they 
- * cancelled the operation 
+ * have been validated and they have clicked 'Ok' to proceed or if the operation
+ * was cancelled
  * 
  * @author Bruce Herr (bh...@bh...)
  */

Modified: trunk/core/org.cishell.docs/src/specification/main.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/main.tex	2008-02-27 19:04:07 UTC (rev 641)
+++ trunk/core/org.cishell.docs/src/specification/main.tex	2008-03-04 23:53:10 UTC (rev 642)
@@ -2,8 +2,8 @@
 %%
 %
 
-\documentclass[pdftex,11pt,a4paper]{report}
-\usepackage[top=0.4in, left=0.5in, right=0.5in, bottom=0.6in]{geometry}
+\documentclass[pdftex,11pt,letterpaper]{report}
+\usepackage[top=1in, left=1in, right=1in, bottom=1in]{geometry}
 \usepackage[pdftex]{graphicx}
 \DeclareGraphicsExtensions{.pdf,.png,.jpg,.mps,.eps}
 \usepackage[pdftex]{hyperref}

Modified: trunk/core/org.cishell.docs/src/specification/tex/algorithms.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/algorithms.tex	2008-02-27 19:04:07 UTC (rev 641)
+++ trunk/core/org.cishell.docs/src/specification/tex/algorithms.tex	2008-03-04 23:53:10 UTC (rev 642)
@@ -7,9 +7,9 @@
 The CIShell Platform has been specifically designed around the idea of the
 algorithm. It is the central and most important concept. Algorithms are fully
 defined and self-contained bits of execution. They can do many things from data
-conversion, data analysis, and can even spawn whole outside programs if it needs
-to. Algorithms are very well defined black boxes in that what can come into and
-out of the algorithm is specified in each algorithm's metadata. Other than that,
+conversion, data analysis, and can even spawn whole outside programs if needed.
+Algorithms are very well defined black boxes in that what can come into and out
+of the algorithm is specified in each algorithm's metadata. Other than that,
 CIShell makes no attempt to understand the algorithm.
 
 To be recognized by CIShell, an \class{AlgorithmFactory} must be registered with
@@ -54,10 +54,10 @@
 When an algorithm is registered with OSGi's service registry, a dictionary of
 metadata is provided. Since the algorithm itself is a black box, the metadata is
 used to provide information about the algorithm. Information such as the format
-of each \class{Data} item to be inputted and outputted is provided. In addition
-to the mechanics of the algorithms, interesting data such as the authors, label,
-urls, and description are provided. This metadata can be searched by anyone using
-OSGi's service registry to find relevant algorithms for use.
+of each \class{Data} item to be input and output is provided. In addition to the
+mechanics of the algorithms, data such as the authors, label, urls, citation
+references, and description are provided. This metadata can be searched by anyone
+using OSGi's service registry to find relevant algorithms.
 
 Each standard metadata element required by the CIShell specification is defined
 below and in the interface \class{AlgorithmProperty}. It defines each key string
@@ -68,7 +68,7 @@
 A string that uniquely identifies the algorithm. The service.pid should not
 change between sessions and only one algorithm with a given service.pid should
 be available in the service registry at any given time. It is recommended to 
-use the Java naming scheme including path for this purpose, i.e.
+use the Java naming scheme including path for this purpose, i.e.,
 ``org.cishell.my.algorithm.MyAlgorithm''. This metadata element is defined
 as part of the OSGi Service Platform Core Specification, section 6.1.12.58. 
 
@@ -93,8 +93,8 @@
 \subsection*{parentage}
 If this metadata element is used, it defines how the output \class{Data}
 produced by the algorithm should be arranged. \class{Data} items can be given a parent as
-part of their metadata (which qsually means the \class{Data} was derived from the
-referenced \class{Data}). If parentage is set to ``default'' then each of the
+part of their metadata (which usually means the \class{Data} was derived from
+the referenced \class{Data}). If parentage is set to ``default'' then each of the
 algorithm's outputted \class{Data} items will have their parent \class{Data} item
 set as the first inputted \class{Data} item (if applicable) by the
 CIShell-conforming application. If parentage is set to something else or is not
@@ -135,7 +135,7 @@
 
 \subsection*{conversion}
 For converter algorithms, this metadata element specifies if any data is
-lossed in the conversion. Possible values are ``lossy'' and ``lossless''. A
+lost in the conversion. Possible values are ``lossy'' and ``lossless''. A
 description of what type of information is lost should be explained in the
 description.
 

Modified: trunk/core/org.cishell.docs/src/specification/tex/algorithmtypes.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/algorithmtypes.tex	2008-02-27 19:04:07 UTC (rev 641)
+++ trunk/core/org.cishell.docs/src/specification/tex/algorithmtypes.tex	2008-03-04 23:53:10 UTC (rev 642)
@@ -3,7 +3,11 @@
 \subsection*{\textit{Version 1.0}}
 
 \label{algConstraints}
+\subsection{Introduction}
 
+CIShell algorithms are a generic concept which have many uses. \comments{flesh
+out\ldots}
+
 \subsection{Base Algorithm Constraints}
 
 All conformant algorithms regardless of type, must adhere to the following
@@ -13,7 +17,7 @@
 \begin{itemize}
   \item The algorithm must be a conformant \class{AlgorithmFactory}
   implementation and properly registered as a service.
-  \item The algorithm's service metadata must contain a legal ``service.pid''.
+  \item The algorithm's service metadata must contain a valid ``service.pid''.
 \end{itemize}
 
 \subsubsection*{Optional:}
@@ -23,7 +27,7 @@
   \item The algorithm's service metadata should have a ``label'' which is a
   short human-readable name for the algorithm.
   \item The algorithm's service metadata should have a ``description''
-  describing what the algorithm does in more detail.
+  explaining what the algorithm does in more detail.
   \item As much of the informational metadata as possible should be
   provided. This includes ``authors'', ``implementors'', ``integrators'',
   ``documentation\_url'', ``reference'', ``reference\_url'', and ``written\_in''.
@@ -38,12 +42,12 @@
 \begin{itemize}
   \item The algorithm must be a conformant \class{AlgorithmFactory}
   implementation and properly registered as a service.
-  \item The algorithm's service metadata must contain a legal ``service.pid''.
+  \item The algorithm's service metadata must contain a valid ``service.pid''.
   \item The algorithm's service metadata must have a ``label'' which is a
   short human-readable name for the algorithm. This is typically used to label
   an algorithm for an end-user to see.
   \item The algorithm's service metadata must have a ``description''
-  describing what the algorithm does in more detail.
+  explaining what the algorithm does in more detail.
   \item The algorithm's service metadata must have a ``menu\_path'' which is
   simultaneously a classification and a location on a GUI's menubar to place
   the algorithm in. See section \ref{algMetaData} for how to format a
@@ -52,7 +56,9 @@
 
 \subsubsection*{Optional:}
 \begin{itemize}
-  
+  \item If additional user-entered parameters are needed, the algorithm should
+  provide a \class{MetaTypeProvider} through its AlgorithmFactory's
+  createParameters method.
   \item The algorithm's service metadata should have ``remoteable=true'' if it
   meets the requirements of a remoteable algorithm.
   \item The algorithm's service metadata should have ``parentage=default'' if
@@ -64,7 +70,44 @@
   ``documentation\_url'', ``reference'', ``reference\_url'', and ``written\_in''.
 \end{itemize}
 
+\subsection{Dataset Algorithms}
 
+A dataset algorithm is a custom type of CIShell algorithm for providing
+pre-generated data for use in the CIShell Platform. Dataset algorithms act just
+like standard algorithms and have a superset of requirements. CIShell
+Applications may not even treat them any differently than standard algorithms. A
+dataset algorithm has the following constraints:
+
+\subsubsection*{Required:}
+\begin{itemize}
+  \item The algorithm must be a conformant \class{AlgorithmFactory}
+  implementation and properly registered as a service.
+  \item The algorithm's service metadata must contain a valid ``service.pid''.
+  \item The algorithm's service metadata must have a ``label'' which is a
+  short human-readable name for the dataset being provided. This is typically
+  used to label a dataset for an end-user to see.
+  \item The algorithm's service metadata must have a ``description''
+  explaining what the dataset is in more detail.
+  \item The algorithm's service metadata must have a ``menu\_path'' which is
+  simultaneously a classification and a location on a GUI's menubar to place
+  the dataset in. Datasets will typically be in ``File/Datasets/additions''
+  See section \ref{algMetaData} for how to format a ``menu\_path''.
+  \item The algorithm's service metadata must have ``type=dataset''.
+  \item The algorithm's service metadata must have ``in\_data=null'' or
+  not defined at all.
+  \item The algorithm's service metadata must have at least one data item set
+  as its ``out\_data''.
+\end{itemize}
+
+\subsubsection*{Optional:}
+\begin{itemize}
+  \item The algorithm's service metadata should have ``remoteable=true'' if it
+  meets the requirements of a remoteable algorithm.
+  \item As much of the informational metadata as possible should be
+  provided. This includes ``authors'', ``implementors'', ``integrators'',
+  ``documentation\_url'', ``reference'', and ``reference\_url''.
+\end{itemize}
+
 \subsection{Converter Algorithms}
 \label{converterAlg}
 
@@ -80,22 +123,26 @@
   \item The algorithm must take in a single \class{Data} item and convert the
   item, producing a single \class{Data} item. This must be reflected in the
   algorithm's service metadata where ``in\_data'' and ``out\_data'' have only
-  one format each.
-  \item The algorithm's service metadata must contain a legal ``service.pid''.
+  one data item each.
+  \item The algorithm's service metadata must contain a valid ``service.pid''.
   \item The algorithm's service metadata must have ``type=converter''.
   \item The algorithm's service metadata must have ``conversion=lossy'' if
   data is lost during conversion or ``conversion=lossless'' if not.
+  \item The algorithm must not require any parameters. The
+  \class{AlgorithmFactory}'s createParameters method will never be called and
+  the \class{Dictionary} passed to the createAlgorithm method will always be
+  empty.
 \end{itemize}
 
 \subsubsection*{Optional:}
-\begin{itemize}
+\begin{itemize}an
   \item The algorithm's service metadata should have ``remoteable=true'' if it
   meets the requirements of a remoteable algorithm.
   \item The algorithm's service metadata should have a ``label'' which is a
   short human-readable name for the converter, usually with the common name of
   the input data format and output data format.
   \item The algorithm's service metadata should have a ``description''
-  describing the conversion in more detail, especially what data may be lossed
+  explaining the conversion in more detail, especially what data may be lossed
   if ``conversion=lossy''.
   \item The algorithm's service metadata should have ``implementers'' filled
   in accordingly.  
@@ -120,15 +167,19 @@
   item producing a single \class{Data} item (with the same data, but changed
   format) or \class{null} if the file being validated is not of the right
   type. This must be reflected in the algorithm's service metadata where
-  ``in\_data'' and ``out\_data'' have only one format each with one containing
-  a ``file:'' format and the other a ``file-ext:'' depending on the direction
-  of validation.
+  ``in\_data'' and ``out\_data'' have only one data item each with one
+  containing a ``file:'' format and the other a ``file-ext:'' depending on the 
+  direction of validation.
   \item The algorithm must not alter the data. Its only purpose is to validate
   the proposed incoming or outgoing file.
-  \item The algorithm's service metadata must contain a legal ``service.pid''.
+  \item The algorithm's service metadata must contain a valid ``service.pid''.
   \item The algorithm's service metadata must have ``type=validator''.
   \item The algorithm's service metadata must have a ``label'' which is the
   common name of the data format being validated.
+  \item The algorithm must not require any parameters. The
+  \class{AlgorithmFactory}'s createParameters method will never be called and
+  the \class{Dictionary} passed to the createAlgorithm method will always be
+  empty.
 \end{itemize}
 
 \subsubsection*{Optional:}

Modified: trunk/core/org.cishell.docs/src/specification/tex/data.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/data.tex	2008-02-27 19:04:07 UTC (rev 641)
+++ trunk/core/org.cishell.docs/src/specification/tex/data.tex	2008-03-04 23:53:10 UTC (rev 642)
@@ -9,9 +9,9 @@
 a mime type if it is a \class{java.io.File}. The mime type corresponds to the
 file's data type and has the following form - ``file:\textit{mime/type}''. Note
 that if no official mime type is available for a file format, a made up one can
-be used, but must still conform to how mime types are constructed. See RFCs 3023
-and 4288 for more information on how to construct MIME types. Finally, the
-properties help describe the data. The label to give the data, the parent
-\class{Data} object from which it was derived from, and a coarse data type can
+be used, but must still conform to how mime types are constructed. See RFCs
+3023\footnote{http://tools.ietf.org/html/rfc3023} and
+4288\footnote{http://tools.ietf.org/html/rfc4288} for more information on how to
+construct MIME types. Finally, the properties help describe the data. The label to give the data, the parent \class{Data} object from which it was derived from, and a coarse data type can
 all be defined in the \class{Data}'s properties. See the \class{DataProperty}
 interface definition for specific properties to use.

Modified: trunk/core/org.cishell.docs/src/specification/tex/dataconversionservice.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/dataconversionservice.tex	2008-02-27 19:04:07 UTC (rev 641)
+++ trunk/core/org.cishell.docs/src/specification/tex/dataconversionservice.tex	2008-03-04 23:53:10 UTC (rev 642)
@@ -3,11 +3,11 @@
 \section{Introduction}
 
 A conscious design decision was made for CIShell not to enforce a central data
-model/format that all algorithms had to work with. Instead, an algorithm
-expresses in its service metadata for each data item coming into and out of the
-algorithm what the format of the data is. It is the job of the code calling the
-algorithm to get the data in the right format before calling the algorithm. The
-Data Conversion Service is used here to simplify the process of converting data.
+model/format that all algorithms have to work with. Instead, an algorithm
+expresses the data format of each data item coming into and out of the algorithm
+in its service metadata. It is the job of the code calling the algorithm to get
+the data in the right format before calling the algorithm. The Data Conversion
+Service is used here to simplify the process of converting data.
 
 \subsection{Entities}
 

Modified: trunk/core/org.cishell.docs/src/specification/tex/datamanagerservice.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/datamanagerservice.tex	2008-02-27 19:04:07 UTC (rev 641)
+++ trunk/core/org.cishell.docs/src/specification/tex/datamanagerservice.tex	2008-03-04 23:53:10 UTC (rev 642)
@@ -7,7 +7,7 @@
 The Data Manager Service is an optional service designed for application
 developers to have a central \class{Data} management system. Algorithm
 developers may use this too if they wish, but it is not guaranteed to be
-available accross all CIShell-compliant systems.
+available across all CIShell-compliant systems.
 
 \subsection{Entities}
 

Modified: trunk/core/org.cishell.docs/src/specification/tex/framework.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/framework.tex	2008-02-27 19:04:07 UTC (rev 641)
+++ trunk/core/org.cishell.docs/src/specification/tex/framework.tex	2008-03-04 23:53:10 UTC (rev 642)
@@ -46,7 +46,7 @@
   \item \textit{BasicData} - A simple implementation of the \class{Data}
   interface.
   \item \textit{DataProperty} - The interface which provides string constants
-  for \class{Data}'s metadata.
+  for \class{Data} metadata.
   \item \textit{CIShellContext} - The interface for a class to be passed in to
   an \class{AlgorithmFactory} for use in gaining access to standard CIShell
   services.

Modified: trunk/core/org.cishell.docs/src/specification/tex/introduction.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/introduction.tex	2008-02-27 19:04:07 UTC (rev 641)
+++ trunk/core/org.cishell.docs/src/specification/tex/introduction.tex	2008-03-04 23:53:10 UTC (rev 642)
@@ -7,8 +7,8 @@
 while retaining their intellectual rights after distribution; (2) data holders to
 easily disseminate their data for use by others; (3) application developers to
 design applications from custom sets of algorithms and datasets that interoperate
-seamlessly; and finally (4) researchers, educators, and practitioners to use
-existing datasets and algorithms to further science.
+seamlessly; and finally (4) end-users to use existing datasets and algorithms
+effectively.
 
 \section{CIShell Platform Overview}
 
@@ -16,42 +16,53 @@
 services for algorithm developers, and services for application developers. Much
 of the platform uses metadata and is fully defined.
 
-\section{What is New}
+%The next version should have this section.
+%\section{What is New}
 
-This is the first release of the CIShell Platform Specification. Future
-versions will strive for backwards compatibility.
+%This is the first release of the CIShell Platform Specification. Future
+%versions will strive for backwards compatibility.
 
 \section{Reader Level}
 
 This specification is written for the following audiences:
 \begin{itemize}
-  \item Java Algorithm developers
-  \item Non-Java Algorithm developers
+  \item Java algorithm developers
+  \item Non-Java algorithm developers
   \item Framework and system service developers (system developers)
   \item Application developers building on CIShell
 \end{itemize}
 
 The CIShell Specifications assume that the reader has at least one year of
 practical experience in writing Java programs. CIShell is built to run on the
-OSGi Service Platform Release 4 and thus a working knowledge of OSGi is expected.
-OSGi (and thus CIShell) is highly dynamic and must be taken into consideration
+OSGi Service Platform Release 4\footnote{http://www.osgi.org/Release4/Download}
+and thus a working knowledge of OSGi is expected. OSGi (and thus CIShell) is highly dynamic and must be taken into consideration
 when developing anything on CIShell.
 
-Non-Java Algorithm developers may not need to know any Java and should be mainly
+Non-Java algorithm developers may not need to know any Java and should be mainly
 concerned with the metadata definitions for algorithms and data. They may also
 need to be aware of OSGi and the other services CIShell provides, but more than
 likely will not directly interact with them.
 
 \section{Conventions and Terms}
 
-The conventions and terms are exactly the same as from OSGi's Core
+In this specification, algorithms are referred to in three different contexts. An
+abstract algorithm, is the pure idea of the algorithm with no actual source code.
+It is a series of steps sometimes put into psuedo-code and often published in
+academic journals. An \class{Algorithm} with a capital A refers the Java class
+called Algorithm. And finally, an algorithm with a lowercase A refers to the
+bundle of code that encompasses an algorithm written in code to work with the
+CIShell Platform. This includes the implementation of \class{AlgorithmFactory}
+and \class{Algorithm}, and the metadata, files, and other code that go into an
+OSGi bundle.
+
+All other conventions and terms are exactly the same as from OSGi's Core
 Specification, section 1.4.
 
 \section{Version Information}
 
 This is the first release of the CIShell Platform Specification. All packages are
 at 1.0 for this release. Subsequent releases may increase the version number of
-specific packages, if changes have been made.
+specific packages if changes have been made.
 
 \begin{table}[h!]
 \begin{tabular}{l l l}
@@ -65,8 +76,6 @@
 1.0 \\
 Log Service Specification & org.osgi.service.log & Version 1.3 \\
 Preferences Service Specification & org.osgi.service.prefs & Version 1.1 \\
-GUI Preferences Service Specification & org.cishell.service.\comments{TBD} &
-Version 1.0 \\
 Data Manager Application Service Specification & org.cishell.app.datamanager &
 Version 1.0 \\
 Scheduler Application Service Specification & org.cishell.app.scheduler &

Modified: trunk/core/org.cishell.docs/src/specification/tex/logservice.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/logservice.tex	2008-02-27 19:04:07 UTC (rev 641)
+++ trunk/core/org.cishell.docs/src/specification/tex/logservice.tex	2008-03-04 23:53:10 UTC (rev 642)
@@ -8,8 +8,8 @@
 built on CIShell a standard logging sytem to use. This service has not been
 extended or modified. More information about the \class{LogService} is available
 in the OSGi Service Platform Service Compendium Specification R4, section 101
-under ``Log Service Specification''. Recommend output per log level for CIShell
-algorithms are listed in table \ref{table:logLevels}.
+under ``Log Service Specification.'' Recommended output per log level for
+CIShell algorithms are listed in table \ref{table:logLevels}.
 
 \begin{table}[htb!]
 \begin{center}
@@ -18,10 +18,10 @@
 LOG\_DEBUG & Used for problem determination and may be irrelevent to anyone but
 the algorithm developer. \\
 LOG\_ERROR & Indicates a problem occurred while the algorithm was executing.
-Indicators of possible fixes should be outputted to this level along with
+Indicators of possible fixes should be output to this level along with
 relevent information describing what went wrong, if possible. \\
 LOG\_INFO & Used for providing information about and while the algorithm is
-executing and does not indicate a problem. \\
+executing. It does not indicate a problem. \\
 LOG\_WARNING & Indicates that the algorithm will still be executed, but
 that outputs may not be what was expected. This is often in response to
 illogical, but still valid user inputs.

Modified: trunk/core/org.cishell.docs/src/specification/tex/osgidependencies.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/osgidependencies.tex	2008-02-27 19:04:07 UTC (rev 641)
+++ trunk/core/org.cishell.docs/src/specification/tex/osgidependencies.tex	2008-03-04 23:53:10 UTC (rev 642)
@@ -4,21 +4,22 @@
 implementation. In addition to the base OSGi implementation, several
 optional OSGi services are required to be available in a fully compliant CIShell
 implementation. Each additional required service is described in the OSGi
-Service Platform Service Compendium R4.
+Service Platform Service Compendium
+R4\footnote{http://www.osgi.org/Release4/Download}.
 
 \subsection*{Required Services}
 \begin{description}
   \item[Metatype Service] as described in OSGi section 105 ``Metatype Service
-  Specification'', this service defines the \class{MetaTypeProvider} class used
+  Specification,'' this service defines the \class{MetaTypeProvider} class used
   for specifying user interfaces in CIShell. In addition, it provides an XML 
   format for automatically generating \class{MetaTypeProvider}s and a service,
  \class{MetaTypeService}, for harvesting them for use by bundles.
   \item[Log Service] as described in OSGi section 101 ``Log Service 
-  Specification'', this service is used as a universal logging system for 
+  Specification,'' this service is used as a universal logging system for 
   algorithms and services. See chapter \ref{logService} for more details.   
   \item[Preferences Service] as described in OSGi section 106 ``Preferences
-  Service Specification'', this service is used as a universal preference storage
-  system for algorithms and services. See chapter \ref{preferencesService} for
+  Service Specification,'' this service is used as a universal preference
+  storage system for algorithms and services. See chapter \ref{preferencesService} for
   more details.
   \item[Configuration Admin Service] \comments{More details when the expanded
   prefs spec is done\ldots}
@@ -28,6 +29,6 @@
 \begin{description}
   
   \item[Declarative Services] as described in OSGi section 112 ``Declarative
-  Services Specification'', this service can b...
 
[truncated message content]