Commits

Clark C. Evans  committed b753ec1

small edits on showcase

  • Participants
  • Parent commits 7b44cea

Comments (0)

Files changed (2)

File doc/showcase.rst

       :alt: output of /school query
       :target: http://demo.htsql.org/school
 
-HTSQL is a REST_ query language for the web.  Queries are URLs_ that can
-be directly typed into a browser.  The default output format of the
-HTTP_ request depends upon the user-agent and its Accept_ header.
+HTSQL is a query language for the web.  Queries are URLs_ that can be
+directly typed into a browser.
 
 .. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
 .. _HTTP: http://www.w3.org/Protocols/rfc2616/rfc2616.html
       FROM "ad"."school" AS "school"
       ORDER BY 1 ASC
 
-HTSQL wraps SQL databases.  On startup HTSQL introspects structure of
-the database.  At runtime, each request is then translated into SQL and
-executed.
-
-Throughout this document, the code blocks on the right represent the SQL
-equivalent of the HTSQL expression on the left.
+HTSQL wraps an existing relational database.  Queries are translated
+into SQL.
 
 HTSQL is an Advanced Query Language
 -----------------------------------
       ON ("school"."code" = "department"."school")
       ORDER BY "school"."code" ASC
 
-HTSQL is a high-level query language that compiles into SQL as if it
-were a database assembly language.
+HTSQL is a compact, high-level query language.  Often times,
+short HTSQL queries are equivalent to much more complex SQL.
+
+
+How do I use HTSQL?
+===================
+
+HTSQL can be used with any number of higher-level tools.
+
+HTSQL Makes Dashboarding Easy
+-----------------------------
+
+.. vsplit::
+
+   .. sourcecode:: html
+
+      <body>
+      <h3>Select a School</h3>
+      <select id="school" data-htsql="/school{code, name}"></select>
+      <div style="width: 500px; height: 350px;"
+          data-htsql="/program{title, count(student)}
+                      ?school=$school&count(student)>0"
+          data-type="pie"
+          data-widget="chart"
+          data-title="Percent of Students by Program"></div>
+      <h3>Departments</h3>
+      <p>Filter by name: <input id="department_name"/></p>
+      <table id="department" data-hide-column-0="yes"
+          data-htsql="/department{code, name, school.name}
+                      ?school=$school&name~$department_name">
+      </table>
+      <p>
+          The selected department:
+          <em data-htsql="/department{name}?code=$department"></em> <br/>
+          The number of courses in the selected department:
+          <strong data-htsql="/department{count(course)}?code=$department">
+          </strong>
+      </p>
+      <h3>Courses</h3>
+      <table id="course" data-htsql="/course?department=$department">
+      </table>
+      </body>
+
+   .. image:: img/htraf_screenshot.png
+      :alt: The HTRAF demo
+      :target: http://htraf.htsql.org/
+
+The dashboard above (using the JQuery-based HTRAF toolkit) shows a 3-level
+drill down (``school``, ``department`` and ``course``) for a university
+schema.  The live demo for this dashboard is at http://htraf.htsql.org/.
+
+HTSQL is a Communication Tool
+-----------------------------
+
+HTSQL reduces the number of meetings in your organization::
+
+   From: "Anne (data analyst)" <ann@example.com>
+   To: "Dave (product manager)" <dave@example.com>
+   Cc: jess@example.com, tim@example.com, jose@example.com
+   Subject: do we need to meet?
+
+   Does the HTSQL below return, for each school, the average
+   number of courses offered in its departments? If so, then
+   Tim and I don't need to meet with you tomorrow.
+
+   http://demo.htsql.org/school{name,avg(department.count(course))}
+
+   - A
+
+HTSQL is a common language usable by software developers, data analysts,
+database administrators, and even business users.
 
 
 Show me this HTSQL!
 
 HTSQL was designed from the ground up as a self-serve reporting tool
 for data analysts.  With HTSQL, the easy stuff is truly easy; and,
-well, complex stuff is easy too.
+the complex stuff is easy too.
 
 Database Introspection
 ----------------------
     \---<|   COURSE   |               |  PROGRAM   |>---/
          +------------+               +------------+
 
-This "university catalog" schema is used in the examples below.  The
-data model two top-level tables, ``school`` and ``department``, where
+This university schema is used in the examples below.  The data model
+has two top-level tables, ``school`` and ``department``, where
 ``department`` has an optional link to ``school``.  Subordinate tables,
-having mandatory foreign key references are ``course`` and ``program``.
+having mandatory foreign key references, are ``course`` and ``program``.
 
 Choosing a Table
 ----------------
 
-HTSQL queries typically start with the driving table.
+HTSQL queries typically start with a table.
 
 .. vsplit::
 
 
    .. sourcecode:: htsql
 
-      /department{school.name :as 'School',
-                  name :as 'Department'}
+      /department{school.name, name}
 
    .. sourcecode:: sql
 
-      SELECT "school"."name" AS "School",
-             "department"."name" AS "Department"
+      SELECT "school"."name",
+             "department"."name"
       FROM "ad"."department" AS "department"
       LEFT OUTER JOIN "ad"."school" AS "school"
       ON ("department"."school" = "school"."code")
 
 .. _Q2:
      http://demo.htsql.org
-     /department{school.name :as 'School', name :as 'Department'}
+     /department{school.name, name}
 
 Filtering Rows
 --------------
 Paging and Sorting
 ------------------
 
-Table operations such as sorting and paging are chainable.
+Table operations such as sorting and paging could be freely combined.
 
 .. vsplit::
 
 
 This query (Q5_) returns, for each school having a
 MS program, the average number of courses offered
-in its departments.
+across its departments.
 
 .. _Q5:
      http://demo.htsql.org
           exists(program.degree='ms')
 
 
-How do I use HTSQL?
-===================
-
-HTSQL can be used with any number of higher-level tools.
-
-HTSQL Makes Dashboarding Easy
------------------------------
-
-.. vsplit::
-
-   .. sourcecode:: html
-
-      <body>
-      <h3>Select a School</h3>
-      <select id="school" data-htsql="/school{code, name}"></select>
-      <div style="width: 500px; height: 350px;"
-          data-htsql="/program{title, count(student)}
-                      ?school=$school&count(student)>0"
-          data-type="pie"
-          data-widget="chart"
-          data-title="Percent of Students by Program"></div>
-      <h3>Departments</h3>
-      <p>Filter by name: <input id="department_name"/></p>
-      <table id="department" data-hide-column-0="yes"
-          data-htsql="/department{code, name, school.name}
-                      ?school=$school&name~$department_name">
-      </table>
-      <p>
-          The selected department:
-          <em data-htsql="/department{name}?code=$department"></em> <br/>
-          The number of courses in the selected department:
-          <strong data-htsql="/department{count(course)}?code=$department">
-          </strong>
-      </p>
-      <h3>Courses</h3>
-      <table id="course" data-htsql="/course?department=$department">
-      </table>
-      </body>
-
-   .. image:: img/htraf_screenshot.png
-      :alt: The HTRAF demo
-      :target: http://htraf.htsql.org/
-
-The dashboard above (using the JQuery-based HTRAF toolkit) shows a 3-level
-drill down (``school``, ``department`` and ``course``) for a university
-schema.  The live demo for this dashboard is at http://htraf.htsql.org/.
-
-HTSQL is a Communication Tool
------------------------------
-
-HTSQL reduces the number of meetings in your organization::
-
-   From: "Anne (data analyst)" <ann@example.com>
-   To: "Dave (product manager)" <dave@example.com>
-   Cc: jess@example.com, tim@example.com, jose@example.com
-   Subject: do we need to meet?
-
-   Does the HTSQL below return, for each school, the average
-   number of courses offered in its departments? If so, then
-   Tim and I don't need to meet with you tomorrow.
-
-   http://demo.htsql.org/school{name,avg(department.count(course))}
-
-   - A
-
-HTSQL is a common language usable by software developers, data analysts,
-database administrators, and even business users.
-
-
 What's up Next?
 ===============
 

File doc/tutorial.rst

 table; by *plural* we mean there is perhaps more than one correlated
 record.  To select a *plural* expression in a result set, an *aggregate*
 function, such as ``sum``, ``count``, or ``exists`` must be used.  In
-this way, what would be many values is converted into a single data cell
+this way, what would be many values are converted into a single data cell
 and integrated into a coherent result set.
 
 By requiring aggregates for plural expressions, HTSQL reduces query