Commits

Clark C. Evans committed 00b9ef5

incremental change to handbook

Comments (0)

Files changed (2)

doc/admin/usage.rst

 
     $ htsql-ctl help shell
 
-.. index:: htsql-ctl server
+.. index:: htsql-ctl serve
+.. _htsql-ctl serve:
 
 HTTP Server
 -----------
 
-To start a web server running HTSQL, run::
+To start a *demonstration* web server running HTSQL, run::
 
     $ htsql-ctl server <DBURI> [<HOST> [<PORT>]]
 
 
     Starting an HTSQL server on localhost:3128 over htsql_demo
 
+If database connection :ref:`configuration <configuration>` is provided
+by ``-C``, you could use ``-`` as a place holder for the mandatory
+database URI parameter so that you could provide a HOST and PORT.  For
+example, to run the server on ``localhost:80`` you would write::
+
+    # htsql-ctl serve -C demo-config.yaml - localhost 80
+
 For more details on the ``server`` routine, run::
 
     $ htsql-ctl help server
 
-
 .. index:: htsql-ctl extension
 
 Extension Mechanism
 
     $ htsql-ctl extension
 
-To find out more about an extension, such as ``tweak.autolimit``, write::
+To find out more about an extension, such as :ref:`tweak.autolimit`, write::
 
     $ htsql-ctl extension tweak.autolimit
 
 ----------------
 
 An extension can be enabled using ``-E`` parameter on the ``htsql-ctl``
-command line.  For example, to enable the ``tweak.meta`` addon on the
+command line.  For example, to enable the :ref:`tweak.meta` addon on the
 HTSQL demo database, you'd write::
 
     $ htsql-ctl shell -E tweak.meta pgsql:htsql_demo
     htsql_demo$ /meta(/table)
 
 Some addons have parameters which can be added to the command line.
-For example, the ``tweak.autolimit`` extension truncates output at
+For example, the :ref:`tweak.autolimit` extension truncates output at
 ``limit`` number of rows.  The default is 10k, but this value
 can be changed::
 
 
     $ htsql-ctl shell -E tweak.hello:repeat=3,address=home pgsql:htsql_demo
 
-Configuration File
-------------------
+HTSQL plugins are found using Python's entry point feature.  When a
+Python package is installed, it can register itself as an
+``htsql.addon`` extension so that it could be loaded in this manner.
 
-Addons and configuration parameters can also be provided by a
-configuration file in YAML_ (or JSON_) format and then included
-using ``-C`` on the command line.  Here is an example configuration
-file for a PostgreSQL database with some addons enabled.
+.. _configuration:
+
+Configuration Files
+-------------------
+
+Extension configuration can be provided with a YAML_ (or JSON_) file
+using ``-C`` on the command line.  The top level of this file is a
+dictionary listing the plugins that are enabled.  The second nesting
+level are plugin parameters, if any. 
 
 .. sourcecode:: yaml
 
         port: 5432
     tweak.autolimit:
       limit: 1000
-    tweak.cors:
-    tweak.meta:
-    tweak.shell:
-      server-root: http://demo.htsql.org
     tweak.shell.default:
-    tweak.timeout:
-      timeout: 600
 
-You can then start the built-in web server::
-
-  $ htsql-ctl serve -C demo-config.yaml
-
-For ``htsql-ctl serve`` command, the web server host and port are *not*
-provided via extension mechanism and must be provided via command line
-if something other than ``localhost:8080`` is desired.  For instance,
-to run the server on ``localhost:80``, use::
-
-    # htsql-ctl serve -C demo-config.yaml - localhost 80
-
-Here, we use ``-`` in place of the database address since the database
-connection parameters are already specified in the configuration file.
+In this example, there are three plugins enabled, ``htsql`` (which is a
+mandatory plugin), :ref:`tweak.autolimit` and ref:`tweak.shell.default`.
+The ``htsql`` plugin has one argument, ``db`` which has sub-structure
+providing connection information.  You could then use this
+configuration file using ``-C``::
+  
+    # htsql-ctl shell -C demo-config.yaml
 
 If both ``-E`` and ``-C`` are used, explicit command line options override
 values provided in the configuration file.  This permits a configuration
 
 .. index:: tweak.override
 
+.. _tweak.override:
+
 ``tweak.override``
 ------------------
 
 -----------
 
 Besides ``shell``, the ``htsql-ctl`` program provides a built-in
-*demonstration* webserver.  You could start it as follows::
+*demonstration* :ref:`webserver <htsql-ctl serve>`.  You could start it
+as follows::
 
    $ htsql-ctl serve sqlite:htsql_demo.sqlite
        Starting an HTSQL server on localhost:8080 over htsql_demo.sqlite
 formatter with our visual shell.  If you press ``CTRL+SPACE`` it should
 bring up a context sensitive menu item.
 
-
-Setting up HTSQL
+HTSQL Extensions
 ================
 
 Everything is an Extension
     $ htsql-ctl extension
         Available extensions:
         engine          :  provides implementations of HTSQL for specific servers
-        engine.mssql    : [BROKEN]
         engine.mysql    : implements HTSQL for MySQL
         engine.pgsql    : implements HTSQL for PostgreSQL
         engine.sqlite   : implements HTSQL for SQLite
 One handy extension is :ref:`tweak.autolimit` which limits the number of
 rows returned by default.  Using this plugin lets you explore tables
 with lots of rows without having to constantly add ``.limit(n)`` to each
-of your queries.  In this example, we set ``autolimit`` to 5 rows::
+of your queries.  In this example, we set the ``limit`` to 5 rows::
   
     $ htsql-ctl shell -E tweak.autolimit:limit=5 sqlite:htsql_demo.sqlite
     Type 'help' for more information, 'exit' to quit the shell.
     htsql_demo$ /count(department)
-        count(department)
-        -----------------
-                       27
-        (1 row)
+         | count(department) |
+        -+-------------------+-
+         |                27 |
+                   (1 row)
     htsql_demo$ /department
-        department
-        --------------------------------------
-        code   | name            | school_code
-        -------+-----------------+------------
-        acc    | Accounting      | bus        
-        arthis | Art History     | art        
-        astro  | Astronomy       | ns         
-        be     | Bioengineering  | eng        
-        bursar | Bursar's Office |            
-        (5 rows)
+         | department                             |
+         +----------------------------------------+
+         | code   | name            | school_code |
+        -+--------+-----------------+-------------+-
+         | acc    | Accounting      | bus         |
+         | arthis | Art History     | art         |
+         | astro  | Astronomy       | ns          |
+         | be     | Bioengineering  | eng         |
+         | bursar | Bursar's Office |             |
+                                           (5 rows)
 
 One of the more interesting plugins is :ref:`tweak.meta`.  This adds a
 in-memory SQLite database with table and link detail based upon the
     $ htsql-ctl shell -E tweak.meta sqlite:htsql_demo.sqlite
     Type 'help' for more information, 'exit' to quit the shell.
     htsql_demo$  /meta(/link{name, is_singular}?table_name='school')
-       link                    
-       ------------------------
-       name       | is_singular
-       -----------+------------
-       department | false      
-       program    | false      
-      (2 rows)
+         | link                     |
+         +--------------------------+
+         | name       | is_singular |
+        -+------------+-------------+-
+         | department | false       |
+         | program    | false       |
+                             (2 rows)
 
 The PostgreSQL specific :ref:`tweak.timeout` plugin provides a way to
 automatically kill expensive queries after a specified number of seconds
 would count 15K^3 rows.  Having a query like this auto killed after 3s
 is a great way to keep everyone happy.
 
-Basic Configuration
--------------------
+Extension Configuration
+-----------------------
 
-Typically, you'll want to put your connection information as well as
-other configuration options into a flat file.  For more information,
-please see :doc:`admin/usage`.
+Addons and :ref:`configuration <configuration>` parameters can also be
+provided by a configuration file in YAML_ (or JSON_) format and then
+included using ``-C`` on the command line.  Here is an example
+configuration file for a PostgreSQL database with some addons enabled.
 
+.. sourcecode:: yaml
+
+    # demo-config.yaml
+    htsql:
+      db:
+        engine: pgsql
+        database: htsql_demo
+        username: htsql_demo
+        password: secret
+        host: localhost
+        port: 5432
+    tweak.autolimit:
+      limit: 1000
+    tweak.cors:
+    tweak.meta:
+    tweak.shell:
+      server-root: http://demo.htsql.org
+    tweak.shell.default:
+    tweak.timeout:
+      timeout: 600
+
+You can then start the shell using these parameters::
+
+  $ htsql-ctl serve -C demo-config.yaml
+
+If both ``-E`` and ``-C`` are used, explicit command line options override
+values provided in the configuration file.  This permits a configuration
+file to be used as a default perhaps using a different database URI.
+
+.. _YAML: http://yaml.org/
+.. _JSON: http://json.org/
+
+
+MetaData Configuration
+======================
+
+The :ref:`tweak.override` plugin provides comprehensive control over the
+HTSQL system catalog.  
+
+
+.. note:: 
+   
+    For more information about configuring and using HTSQL, please
+    see our :doc:`admin/usage` guide.
+
+