- More documentation cleanup

- Index name instead of category column in LSST schema browser output

Author: smonkewitz

README

@@ -1,9 +1,15 @@
 Science Tools for MySQL
 =======================
 
-    Science-specific tools and extensions for SQL. Currently the project
-contains user defined functions (UDFs) for MySQL including spatial geometry,
-photometry, and statistics functions.
+    SciSQL provides science-specific tools and extensions for SQL. Currently,
+the project contains user defined functions (UDFs) and stored procedures for
+MySQL in the areas of spherical geometry, statistics, and photometry. It is
+distributed under the terms of the GNU Lesser General Public License,
+version 3.
+
+    Note that the doc/index.html file in the SciSQL distribution contains
+all the instructions below, as well as documentation for all the SciSQL UDFs
+and stored procedures.
 
 
 Installation prerequisites:
@@ -22,15 +28,15 @@ In order to install the UDFs, you need write permission to the MySQL server
 plug-in directory as well as a MySQL account with admin priviledges.
 
 
-WARNING:
---------
+Databases reserved for SciSQL use:
+----------------------------------
 
 The following database names are reserved for use by SciSQL:
 
 - scisql                  Contains SciSQL stored procedures.
 - scisql_test             Used by SciSQL unit tests.
 - scisql_demo             Contains sample data that can be used to
-                          excercise the SciSQL UDFs.
+                          exercise the SciSQL UDFs.
 
 The scisql and scisql_demo databases are dropped and re-created during
 installation. If you are using these databases for other things,
@@ -54,9 +60,9 @@ Connection details, including this password, are stored in
 build/c4che/.my.cnf in the MySQL options file format. This allows various
 build steps to connect to MySQL without constantly prompting for a password.
 
-Though the .my.cnf file permissions are set such that only the creator is
-allowed read/write access, for security reasons it is still recommended to
-run `make distclean` once SciSQL has been installed - this will remove the
+Even though the .my.cnf file permissions are set such that only its creator
+is allowed read/write access, for security reasons it is still recommended to
+run `make distclean` once SciSQL has been installed. This will remove the
 entire build directory and its contents.
 
 

doc/docs.css

@@ -112,7 +112,16 @@ ul {
 	padding: 0.1em 0.1em 0.1em 0.5em;
 }
 .section-docs {
-	margin-left: 2em;
+	margin-left: 50px;
+}
+.section-docs h3 {
+	margin-left: -50px;
+        padding-left: 1em;
+	border-top: 1px solid #99B;
+	background: #EEF;
+}
+.section-docs h3.warning {
+	background: #FEE;
 }
 
 .internal {

scripts/install.mysql

@@ -219,8 +219,8 @@ END //
 -- <proc name="scisqlGrant" section="misc">
 --     <desc>
 --         Gives a user connecting from the specified host permission to call
---         scisql stored procedures and the use the temporary tables they
---         generate. 
+--         SciSQL stored procedures and to create/use temporary tables in the
+--         scisql database.
 --     </desc>
 --     <args>
 --         <arg name="user" type="VARCHAR(255)">

tools/templates/lsst_schema_browser.mako

@@ -22,7 +22,7 @@ CREATE TABLE md_Udf (
 	name VARCHAR(255) NOT NULL UNIQUE,
 	category VARCHAR(255) NOT NULL,
 	htmlDocs TEXT,
-        INDEX md_Udf_category (category)
+        INDEX md_Udf_name (name)
 );
 
 CREATE TABLE md_Proc (
@@ -31,7 +31,7 @@ CREATE TABLE md_Proc (
 	dbName VARCHAR(255) NOT NULL,
         category VARCHAR(255) NOT NULL,
         htmlDocs TEXT,
-        INDEX md_Proc_category (category)
+        INDEX md_Proc_name (name)
 );
 
 

tools/templates/sections.xml

@@ -17,7 +17,7 @@
 	        <li><a href="https://answers.launchpad.net/scisql/+addquestion">Ask a question</a></li>
 	</ul>
 	<p>
-	The SciSQL documentation makes use of:
+	SciSQL is also distributed with a pair of Javascript libraries. These are:
 	</p>
 	<ul>
 		<li>
@@ -27,8 +27,8 @@
 		</li>
 		<li>
 			<a href="http://code.google.com/p/google-code-prettify/">Google prettify</a>,
-			distriuted under the <a href="http://www.apache.org/licenses/LICENSE-2.0">
-			Apache License, Version 2.0</a>
+			distributed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">
+			Apache License version 2.0</a>
 		</li>
 	</ul>
 	</div>
@@ -58,7 +58,7 @@
 	plug-in directory, as well as a MySQL account with admin priviledges.
 	</p>
 
-	<h3 class="warning">WARNING</h3>
+	<h3 class="warning">Databases reserved for SciSQL use</h3>
 	<p>
 	The following database names are reserved for use by SciSQL:
 	</p>
@@ -68,7 +68,7 @@
 		<dt>scisql_test</dt>
 		<dd>Used by SciSQL unit tests.</dd>
 		<dt>scisql_demo</dt>
-		<dd>Contains sample data that can be used to excercise the SciSQL UDFs.</dd>
+		<dd>Contains sample data that can be used to exercise the SciSQL UDFs.</dd>
 	</dl>
 	<p>
 	The scisql and scisql_demo databases are dropped and re-created during
@@ -98,9 +98,9 @@
 	build steps to connect to MySQL without constantly prompting for a password.
 	</p>
 	<p>
-	Though the <tt>.my.cnf</tt> file permissions are set such that only the creator is
-	allowed read/write access, for security reasons it is still recommended to
-	run <tt>`make distclean`</tt> once sciSQL has been installed - this will remove the
+	Even though the <tt>.my.cnf</tt> file permissions are set such that only its creator
+	is allowed read/write access, for security reasons it is still recommended to
+	run <tt>`make distclean`</tt> once sciSQL has been installed. This will remove the
 	entire build directory and its contents.
 	</p>
 
@@ -110,8 +110,24 @@
 	<tt>make install</tt>, and <tt>make uninstall</tt> commands.
 	</p>
 	<p>
-TODO TODO TODO
+        The <tt>install</tt> command will CREATE the SciSQL UDFs, stored procedures, and
+        databases (including the scisql_demo database). It will also automatically
+        run the SciSQL unit tests. You can re-run the tests anytime with <tt>`make test`</tt>.
 	</p>
+        <p>
+        The uninstall command DROP the SciSQL UDFs, stored procedures, and databases.
+        </p>
+
+        <h3>Reporting bugs and getting help</h3>
+        <p>
+        If you encounter test-case failures, or think you've identified a
+        bug in the SciSQL code, please file a report here:
+        </p>
+        <p><a href="https://bugs.launchpad.net/scisql/+filebug">https://bugs.launchpad.net/scisql/+filebug</a></p>
+        <p>
+        For other help or inquiries, submit your questions here:
+        </p>
+        <p><a href="https://answers.launchpad.net/scisql/+addquestion">https://answers.launchpad.net/scisql/+addquestion</a></p>
 	</div>
 </section>