Updated docs

README.md

@@ -4,17 +4,23 @@ Quill is a build tool for Tcl/Tk projects, inspired by
 [Leiningen](http://leiningen.org).  It is intended to:
 
 * Create new skeleton project trees.
+* Run test suites
+* Format HTML documentation
 * Manage dependencies
   * External and internal
-* Run tests
+* Execute your project
+* Execute arbitrary scripts in the context of your project's code base
 * Build deployment targets:
   * Standalone executables ("starpacks")
   * Lightweight executables ("starkits")
-  * Reusable packages (teapot modules, .tm or .zip)
+  * Reusable packages (teapot .zip modules)
 * Make it easy to build and deploy Tcl applications and libraries.
-* Support formatted HTML documentation
 * Run cross-platform (Windows, OS X, Linux)
 
+As such, it is intended to reduce the ancillary costs of defining and
+deploying a Tcl package or executable to as close to zero as possible, by
+automating everything but the actual writing of the code and documentation. 
+
 ## Building and Installation
 
 To install Quill, see [docs/INSTALL.md](./docs/INSTALL.md).
@@ -24,10 +30,10 @@ To build Quill from scratch, see [docs/BUILD.md](./docs/BUILD.md).
 
 ## Basic Use Case
 
-Assuming you have ActiveTcl 8.6.1 or later installed, with the installation's
+Assuming you have ActiveTcl 8.5 or later installed, with the installation's
 `tclsh` on your path, you should be able to do the following:
 
-**Download and install `quill.kit` in your ~/bin directory (or wherever).**
+**Download and install `quill.exe` in your ~/bin directory (or wherever).**
 See [docs/INSTALL.md](./docs/INSTALL.md).
 
 **Create a new skeleton project tree:**
@@ -82,6 +88,13 @@ $ quill shell
 ... (Invokes Tkcon; does not run the application's "main" proc)
 ```
 
+** Install your application and libraries for local use:**
+
+```
+$ quill install
+... (Copies the executable to your ~/bin, and libraries to your teapot)
+```
+
 ## Other Features
 
 Quill can also build library packages and install them into your local
@@ -94,27 +107,37 @@ Then, you can add `require` statements to your `project.quill` file
 the required packages into your local teapot when you execute 
 `quill deps update`.
 
+Finally, if you define a distribution in `project.quill`, Quill will build
+distribution .zip file for you.
+
 See the [quill(5)](./docs/man5/quill.manpage) man page for information about
 the contents of the `project.quill` file, and enter `quill help` at the
 command line for help on Quill and its subcommands.
 
-## Assumptions
+## Dependencies
 
-At present, Quill relies heavily on ActiveState's package repository
-tool-chain, and particularly on "teacup" (delivered with ActiveTcl)
-and "tclapp" (delivered as part of TclDevKit).  In particular, Quill
-assumes the following:
+How much Quill can do for you depends on what ancillary tools you have 
+installed.  You will need a Tcl interpreter at the very least.
 
-* ActiveTcl 8.6.1 or later is installed on the system.
-* ActiveTcl is on the path, and can be run as "tclsh" at the
-  command line
-* For building executables, TclDevKit 5.0 or later is installed on
-  the system, and the "tclapp" tool can be run as "tclapp" at the
-  command line.
-* For Unix-based systems, including Mac OS X, it is assumed for
-  certain operations that either ActiveTcl is installed in the
-  user's home directory or the user has access to the "sudo"
-  command.
+With just an arbitrary Tcl interpreter, Quill can:
+
+* Create new project trees for you.
+* Run your tests
+* Format your documentation
+* Make it easier to run your code, either from the system command line or 
+  from an interactive Tcl shell.
+* Create distribution .zip files.
+
+With [ActiveTcl](http://www.activestate.com/activetcl), Quill can:
+
+* Manage external dependencies, pulling packages from ActiveState's
+  teapot repository and keeping them up to date in your environment.
+
+With [TclDevKit 5.0](http://www.activestate.com/tcl-dev-kit), Quill can:
+
+* Build standalone executables for Linux, OS X, and Windows
+* Build libraries as teapot packages, for installation into a local
+  teapot repository. 
 
 ## Ways to Help
 
@@ -139,6 +162,8 @@ with that is also welcome.
 ## Acknowledgements
 
 Thanks to the following people who have contributed bug reports, patches,
-or ideas to Quill:
+or ideas to Quill, or helped in other ways:
 
 * Stephan Effelsberg
+* Andreas Kupries
+

TODO.md

@@ -4,6 +4,7 @@ This is the official list of work to be done.
 
 # Next
 
+* Fix the distributions in project.quill; they contain different things.
 * quill new lib
 * Update release docs.
 * Building exes:

docs/BUILD.md

@@ -33,10 +33,14 @@ Next, verify that it has the tools it needs.  It should be able to find
 `tclsh`, `teacup`, `tclapp`:
 
 ```
-$ ./bin/quill.tcl version
-... (Displays version and helper tools)
+$ ./bin/quill.tcl env
+... (Displays its view of the environment, including the locations of all
+ and helper tools)
 ```
 
+If necessary, you can use the `quill config` tool to point Quill at the 
+required tools.
+
 Next, verify that your local teapot is set up properly.  It needs to be
 writable by the user.  To find out, use `quill.tcl teapot`.
 
@@ -57,8 +61,10 @@ or
 $ sudo teacup update-self
 ```
 
-Next, you will need Snit 2.3 and texutil::expander 1.3.1 in your local
-teapot (they might already be there).  To find out, execute:
+Next, you will need to have several packages present in your local
+teapot--Snit 2.3 and texutil::expander 1.3.1 to begin with, and you
+can see the whole list in `~/github/tcl-quill/project.kite`.  
+(Some of them might already be there).  To find out, execute:
 
 ```
 $ ./bin/quill.tcl deps
@@ -70,8 +76,16 @@ If necessary, you can acquire the required packages as follows:
 $ ./bin/quill.tcl deps update
 ```
 
+Next, you can build Quill's documentation:
+
+```
+$ ./bin/quill.tcl docs
+```
+
 Next, you are ready to build Quill as a standalone executable for your 
-platform
+platform.  This also builds Quill's infrastructure library as a reusable 
+package; see the `docs/` directory for the man pages.
+
 
 ```
 $ ./bin/quill.tcl build
@@ -83,6 +97,7 @@ And then, it can be installed for use on your system:
 $ ./bin/quill install
 ```
 
-This copies `./bin/quill` (or `./bin/quill.exe`) to `~/bin/quill`, which 
-it assumes is on the PATH.
+This copies `./bin/quill-{platform}` (or `./bin/quill-{platform}.exe`) 
+to `~/bin/`, which is assumed to be on the path.  It also installs Quill's
+infrastructure library into your local teapot for your use.
 

docs/INSTALL.md

@@ -1,45 +1,36 @@
 # Installing Quill
 
-## Dependencies
+To use Quill for your own projects, you can build Quill from scratch 
+(see [BUILD.md]) or you can download the distribution file for your
+platform from the 
+[Quill Release Page at GitHub](https://github.com/wduquette/tcl-quill/releases).
+This file explains how to install the distribution.
 
-In principle, Quill could be used with any installation of Tcl 8.4 or later.
-At present, however, Quill requires some version of ActiveTcl, because of
-ActiveTcl's support for "teapot" repositories).
-
-Further, in order to build executables and libraries for deployment 
-Quill currently relies on TclDevKit 5.
-
-These requirements may be relaxed over time; for example, Quill could
-in principle support FreeWrap.
-
-## Installation
-
-1. Install ActiveTcl 8.4 or later on your development machine.  Make
-   sure that `tclsh` at your command shell of choice invokes
-   this version of Tcl.
-
-2. To build executables and libraries for deployment, install 
-   TclDevKit 5.1 so that the `tclapp` and `teapot-pkg` executables 
-   are on your PATH.  (Note: Quill can do quite a lot for you even
-   without TDK installed.)
-
-3. Download the Quill distribution for your platform.  It contains the 
-   following:
+1. Download the Quill distribution for your platform, and unzip it.  It
+   contains the following:
 
    * `README.md`
-   * `bin\quill` of `bin\quill.exe`
+   * `bin\quill-{platform}` or `bin\quill-windows.exe`
    * `docs\index.html`
    * `docs\...`
+   * package-quill-{version}-tcl.zip
+
+2. Copy the executable from `bin/` to your `~/bin` directory (or wherever
+   you prefer), renaming it to `quill` or `quill.exe`.
+
+3. Put the documentation somewhere you can find it, and bookmark 
+   `docs/index.html`.
+
+4. If desired, install the [quill(n) package](mann/index.html) into your
+   local teapot.
 
-4. Copy `bin\quill` to your ~/bin directory (or wherever), and make sure it
-   is marked executable.
+    $ teacup install package-quill-{version}-tcl.zip
 
-5. Put the documentation somewhere where you can find it.
+5. You should now be able to enter these commands:
 
-6. You should now be able to enter the command
+    $ quill help
+    $ quill env
 
-    `$ quill version`
+   etc.
 
-   This will tell you which version of Quill you are running, and what
-   helper commands (e.g., `tclsh`, `teacup`, etc.) it has found and will
-   use.
+See the README.md file for more on Quill's capabilities.