Clark C. Evans avatar Clark C. Evans committed 0a403d7

minor changes to some documentation files

Comments (0)

Files changed (5)

   HTSQL Handbook
 *******************
 
+.. highlight:: console
+
 .. contents:: Table of Contents
    :depth: 1
    :local:
 
-.. note:: 
+This handbook presumes you have finished :doc:`installing
+<admin/install>` HTSQL and have had a chance to skim our
+:doc:`overview <overview>` to get a taste of HTSQL.
 
-    This document will be linked from the front page and
-    provide initial bootstrap including installation, 
-    configuration, usage, and basic queries.
-
-    For now, you could start with our :doc:`admin/usage`.
-
-
    :depth: 1
    :local:
 
-HTSQL was created in 2005 to provide an XPath_-like HTTP interface to
-PostgreSQL_ for client-side XSLT_ screens and reports.  HTSQL found its
-audience when analysts and researchers bypassed the user interface and
-started to use URLs directly.  The language has evolved since then.
+HTSQL was created in 2005 to provide an *XPath*-like HTTP interface to
+*PostgreSQL* for client-side *XSLT* screens and reports.  HTSQL found 
+its audience when analysts and researchers bypassed the user interface
+and started to use URLs directly.  The language has evolved since then.
 
 What is HTSQL?
 ==============
 and an extensive macro inclusion system.  In particular, nested
 aggregations and projections are easy to understand and use.
 
-HTSQL is Human Parsable
------------------------
+HTSQL is a Communication Tool
+-----------------------------
 
 .. vsplit::
 
 
 *On the left is a business inquiry, on the right is the HTSQL translation.*
 
-
 HTSQL is first and formost designed for the *accidental programmer* and
 as such provides a direct mapping of common business inquiries onto a
 computer parsable and executable syntax.  Just because a query must be
 Projection
 ----------
 
-Projection operator returns distinct values.  This example returns
-distinct ``campus`` values from the ``school`` table:
+Projection (``^``) returns distinct values.  This example 
+returns distinct ``campus`` values from the ``school`` table:
 
 .. htsql:: /school^campus
 
 Linking
 -------
 
-Even though HTSQL provides automatic links inferred from foreign key
-constraints, arbitrary linking is also allowed:
+Links between tables are automatic and relative, inferred from foreign
+key constraints.  Unlink (``@``) permits arbitrary, non-relative linking.
 
 .. htsql::
    :cut: 4
    /school{name, count(department)}
           ?count(department)>avg(@school.count(department))
 
-This query returns schools with the number of departments above average
-among all schools.
-
+The query above returns schools with the number of departments above
+average among all schools. 
 
 Why not SQL?
 ============
             ?every(course.credits=3)
    :cut: 3
 
+Arbitrary Linking
+-----------------
+
+The unlink operator (``@``) permits arbitrary, non-relative links; it
+relates the current entity with all other records of another table.
+
+.. htsql:: /school?count(department)>avg(@school.count(department))
+   :cut: 3
+
+The query above returns schools that have above average number of
+departments.  This could also be written with the link function
+``fork()`` which generates the current graph node to itself:
+
+.. htsql:: /school?count(department)>avg(@school.count(department))
+   :cut: 3
+
 
 Compositional Navigation
 ------------------------

src/htsql/ctl/__init__.py

 # See `LICENSE` for license information, `AUTHORS` for the list of authors.
 #
 
-
 """
 :mod:`htsql.ctl`
 ================
 This package implements the ``htsql-ctl`` script.
 """
 
-
 from .script import Script
 from .default import DefaultRoutine
 from .help import HelpRoutine

src/htsql/ctl/version.py

 # See `LICENSE` for license information, `AUTHORS` for the list of authors.
 #
 
-
 """
 :mod:`htsql.ctl.version`
 ========================
 This module implements the `version` routine.
 """
 
-
 from .routine import Routine
 from ..core.util import trim_doc
 
-
 class VersionRoutine(Routine):
     """
     Implements the `version` routine.
     Run '%(executable)s version' to display the version of HTSQL.
     """
     message = """
-        This is ... %s
+        HTSQL %s
         %s
+
+        There is NO WARRANTY, to the extent permitted by law.
     """
 
     def run(self):
         import htsql
-        self.ctl.out(trim_doc(self.message) % (self.ctl.copyright, 
-                                               htsql.__version__))
+        self.ctl.out(trim_doc(self.message) % (htsql.__version__,
+                                               self.ctl.copyright))
 
+
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.