Kirill Simonov avatar Kirill Simonov committed 5564232

Updated README files for source packages.

Comments (0)

Files changed (6)

tool/data/pkg/source/README-CORE

 **************************************
 
 HTSQL is a comprehensive navigational query language for relational
-databases.
+databases.  HTSQL is designed for data analysts and other *accidental
+programmers* who have complex business inquiries to solve and need a
+productive tool to write and share database queries.  HTSQL is *free
+and open source* software.  For more information, please see
+http://htsql.org/.
 
-HTSQL is designed for data analysts and other *accidental programmers*
-who have complex business inquiries to solve and need a productive tool
-to write and share database queries.
+This package provides HTSQL core and *SQLite* backend.
+
+
+Installation Instructions
+=========================
 
 To install HTSQL using ``pip`` package manager, run::
 
     # pip install HTSQL
 
-To install additional database backends, run::
+HTSQL works out of the box with SQLite databases.  To run HTSQL
+on top of other database servers, you need to install additional
+database backends.
+
+To install a PostgreSQL backend, run::
 
     # pip install HTSQL-PGSQL
+
+To install a MySQL backend, run::
+
     # pip install HTSQL-MYSQL
+
+To install an Oracle backend, run::
+
     # pip install HTSQL-ORACLE
+
+To install a backend for Microsoft SQL Server, run::
+
     # pip install HTSQL-MSSQL
 
-For more information, see:
+Alternatively, you may download binary packages for various
+Linux distributions from http://htsql.org/download/.
 
-    http://htsql.org/
-        The HTSQL homepage
 
-    http://htsql.org/doc/overview.html
-        Gentle introduction to HTSQL
+Quick Start
+===========
 
-    http://htsql.org/doc/tutorial.html
-        The HTSQL tutorial
+To verify that HTSQL is installed correctly, run::
 
-    http://htsql.org/doc/embed.html
-        Using HTSQL in Python
+    $ htsql-ctl --version
 
-    http://bitbucket.org/prometheus/htsql
-        HTSQL source code
+You can use HTSQL on top of any relational database.  In our examples,
+we use the HTSQL Demo database, which can be downloaded from
+http://htsql.org/dist/htsql_demo.sqlite.
 
-    irc://irc.freenode.net#htsql
-        IRC chat in #htsql on freenode
+To start a command-line shell where you can type and execute HTSQL
+queries, run::
 
-    http://lists.htsql.org/mailman/listinfo/htsql-users
-        The mailing list for users of HTSQL
+    $ htsql-ctl shell sqlite:htsql_demo.sqlite
+    Type 'help' for more information, 'exit' to quit the shell.
+
+The parameter ``sqlite:htsql_demo.sqlite`` is a database connection
+URI, which has the general form::
+
+    <engine>://<user>:<pass>@<host>:<port>/<database>
+
+For example, the following are valid connection URI::
+
+    sqlite:htsql_demo.sqlite
+    pgsql://localhost/htsql_demo
+    mysql://root@localhost:3306/htsql_demo
+
+Use option ``--password`` to make ``htsql-ctl`` ask you to type
+the password.
+
+In the shell, you can type and execute HTSQL queries::
+
+    htsql_demo$ /school
+     | school                                        |
+     +-----------------------------------------------+
+     | code | name                          | campus |
+    -+------+-------------------------------+--------+-
+     | art  | School of Art & Design        | old    |
+     | bus  | School of Business            | south  |
+     | edu  | College of Education          | old    |
+    ...
+
+The ``htsql-ctl`` script also provides a built-in web server.  It could
+be started as follows::
+
+    $ htsql-ctl serve sqlite:htsql_demo.sqlite
+    Starting an HTSQL server on localhost:8080 over htsql_demo.sqlite
+
+You could then access HTSQL using your browser or any other HTTP user
+agent.
+
+For more information on using and configuring HTSQL, see
+http://htsql.org/doc/handbook.html.
+
+
+Using HTSQL from Python
+=======================
+
+Create an HTSQL instance::
+
+    >>> from htsql import HTSQL
+    >>> demo = HTSQL("pgsql:htsql_demo")
+
+Use the instance to execute HTSQL queries.  For example, to
+find all school records matching the given pattern, write::
+
+    >>> query = "/school?name~$pattern"
+    >>> for row in demo.produce(query, pattern='art'):
+    ...     print row
+    ...
+    school(code=u'art', name=u'School of Art & Design', campus=u'old')
+    school(code=u'la', name=u'School of Arts and Humanities', campus=u'old')
+
+In the next example, for all schools in the old campus, we get the
+number of associated programs and departments::
+
+    >>> query = "/school{name, count(program), count(department)}?campus='old'"
+    >>> for row in demo.produce(query):
+    ...     print "%s: %d programs, %d departments" % row
+    ...
+    School of Art & Design: 3 programs, 2 departments
+    College of Education: 7 programs, 2 departments
+    School of Arts and Humanities: 9 programs, 5 departments
+    School of Natural Sciences: 6 programs, 4 departments
+
+For detailed instructions on use of HTSQL with Python, see
+http://htsql.org/doc/embed.html.
+
+
+Acknowledgements
+================
 
 HTSQL is copyright by Prometheus Research, LLC.  HTSQL is written by
 Clark C. Evans <cce@clarkevans.com> and Kirill Simonov <xi@resolvent.net>.

tool/data/pkg/source/README-MSSQL

+*********************************************************
+  HTSQL-MSSQL -- HTSQL backend for Microsoft SQL Server
+*********************************************************
+
+HTSQL is a comprehensive navigational query language for relational
+databases.  This package provides HTSQL backend for *Microsoft SQL
+Server*.
+
+To install this package, run::
+
+    # pip install HTSQL-MSSQL
+
+For more information, please see:
+
+    http://htsql.org/
+        The HTSQL homepage
+
+    http://pypi.python.org/pypi/HTSQL/
+        The source package for HTSQL
+

tool/data/pkg/source/README-MYSQL

+******************************************
+  HTSQL-MYSQL -- HTSQL backend for MySQL
+******************************************
+
+HTSQL is a comprehensive navigational query language for relational
+databases.  This package provides HTSQL backend for *MySQL*.
+
+To install this package, run::
+
+    # pip install HTSQL-MYSQL
+
+For more information, please see:
+
+    http://htsql.org/
+        The HTSQL homepage
+
+    http://pypi.python.org/pypi/HTSQL/
+        The source package for HTSQL
+

tool/data/pkg/source/README-ORACLE

+********************************************
+  HTSQL-ORACLE -- HTSQL backend for Oracle
+********************************************
+
+HTSQL is a comprehensive navigational query language for relational
+databases.  This package provides HTSQL backend for *Oracle*.
+
+To install this package, run::
+
+    # pip install HTSQL-ORACLE
+
+For more information, please see:
+
+    http://htsql.org/
+        The HTSQL homepage
+
+    http://pypi.python.org/pypi/HTSQL/
+        The source package for HTSQL
+

tool/data/pkg/source/README-PGSQL

+***********************************************
+  HTSQL-PGSQL -- HTSQL backend for PostgreSQL
+***********************************************
+
+HTSQL is a comprehensive navigational query language for relational
+databases.  This package provides HTSQL backend for *PostgreSQL*.
+
+To install this package, run::
+
+    # pip install HTSQL-PGSQL
+
+For more information, please see:
+
+    http://htsql.org/
+        The HTSQL homepage
+
+    http://pypi.python.org/pypi/HTSQL/
+        The source package for HTSQL
+

tool/data/pkg/source/setup.yaml

 name: HTSQL-PGSQL
 description: A Database Query Language (PostgreSQL backend)
 packages: ['htsql_pgsql']
-install-requires: ['psycopg2']
+install-requires: ['HTSQL', 'psycopg2']
+readme-file: [README-PGSQL]
 
 ---
 name: HTSQL-MYSQL
 description: A Database Query Language (MySQL backend)
 packages: ['htsql_mysql']
-install-requires: ['MySQL-python']
+install-requires: ['HTSQL', 'MySQL-python']
+readme-file: [README-MYSQL]
 
 ---
 name: HTSQL-ORACLE
 description: A Database Query Language (Oracle backend)
 license: Evaluation
 packages: ['htsql_oracle']
-install-requires: ['cx_Oracle']
+install-requires: ['HTSQL', 'cx_Oracle']
 license-file: [LICENSE-EVALUATION]
+readme-file: [README-ORACLE]
 
 ---
 name: HTSQL-MSSQL
 description: A Database Query Language (Microsoft SQL Server backend)
 license: Evaluation
 packages: ['htsql_mssql']
-install-requires: ['pymssql']
+install-requires: ['HTSQL', 'pymssql']
 license-file: [LICENSE-EVALUATION]
+readme-file: [README-MSSQL]
 
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.