			     INTRODUCTION
			     ============
				   
		      The Tcl/Tk Reference Guide

The Tcl/Tk Reference Guide is a typeset quick reference guide to John
Ousterhout's Tcl script language and Tk toolkit. The guide style is
based on Johan Vromans' guide for Perl.

It contains a concise description of (almost) all Tcl/Tk statements,
variables and lots of other useful information. The Guide is based on
Tcl version 7.4 and Tk 4.0.

The purpose of the Reference Guide is to aid in the use of Tcl/Tk, to
look up the syntax of specific commands, statements and the meaning
of built-in variables. It is *NOT* a self-contained user guide - basic
knowledge of the Tcl language is required. It is *NOT* complete -
some of the more obscure variants of tcl constructs have been left
out. But all commands and variables are mentioned in at least one way
they can be used.

The Reference Guide is designed and created by Johan Vromans using the
LaTex typesetting system. For best results, Tom Rockiki's dvips 5.47
should be used to generate the PostScript output. Your mileage may
vary when you use other ouput mechanisms.

A special formatting tool, written in Perl, makes it possible to
reformat this PostScript output for reproduction in a number of
formats. If you cannot run this tool, you do not need the information
either.

INSTALLATION
============

 1. Unload the distribution

    After unloading the distribution, you will have the following files:

	README.1st  - this file
	ChangeLog   - description of changes
	Makefile    - makefile
	parr.pl	    - reformat and rearrange tool
	Layout	    - description of the format
	MANIFEST    - a list of files
	refbase.tex - master LaTeX source for the Reference Guide
	reftcl.tex  - Tcl LaTeX source for the Reference Guide
	reftk.tex   - Tk LaTeX source for the Reference Guide
	refbase.sty - LaTeX style for the Reference Guide
	refbase.toc - The table of contents
	refbase.ps  - pre-generated PostScript base
	PROBLEMS    - known problems on certain printers

 2. Create the PostScript base file

    You can skip this step if you already have a pre-generated
    PostScript file.  This step requires the LaTeX typesetting system,
    and dvips version 5.47 or later. Unfortunately, the newest Latex
    (2e) does not seem to work with the included style files. If you
    can figure out what needs to be done to do this, please contact
    <raines@slac.stanford.edu>

    - Use "make refbase-ps" (a dash, not a dot) to create a new
      PostScript file from the LaTeX source. This step requires that
      you have the npsfont.sty style file installed at your site.


    NOTE: dvips must be instructed to use a4 format paper ('-t a4')
	  even if you intend to print on a different format!

    The refbase.ps file should be a multiple of 4 pages. If not,
    there must be something different between your TeX installation
    and mine. If refbase.ps is not a multiple of 4 pages, you will
    lose pages through the parr.pl filter program (from the front).

 3. Create the RefGuide from the PostScript base

    As distributed, the Makefile is configured to generate output for
    US Letter (8.5 x 11") paper format. Use "make PAPER= ..." to select
    A4 (21 x 29.7 cm) format.  Both formats should be printable on
    all industry-standard PostScript printers.

    You can use "make" to generate a new PostScript file for one of
    the following formats:

     - Use "make refguide.ps" to create a guide formatted in pages
       of 2-column text. It should be printed double-sided, stapled in
       the middle, folded, and cut to size to have a 24-page 4.25 x 8"
       booklet. See the "Layout" document.

     - Use "make 2pass" to create a set of odd and even pages for
       double sided printing. First print "guide-odd.ps". Then put the
       paper back in the tray, and print either "guide-even1.ps" or
       "guide-even2.ps", depending on the way your printer arranges
       the printed paper.
       "guide-even1.ps" is for printers with correct output stacking like
       Apple LaserWriter II. 
       "guide-even2.ps" is for printers with reverse output stacking,
       like old Apple LaserWriters. 
       In other words, after printing "guide-odd.ps", if the
       text of the front page is on top -- use "guide-even1.ps".
       But if you're looking at the text of the middle pages -- use
       "guide-even2.ps". 
       It is actually not always this simple so you should stand
       by your printer and make sure it comes out right.

    "make" without arguments will default to refguide.ps.

    If your printout is not correct, feel free to change the figures in
    subroutine 'twoup' of the 'parr.pl' program. The file Layout
    describes in more detail how the Guide should look like.

    On printers that support it, duplex printing is done.

    See also the file PROBLEMS.

Comments are welcome, send them to the author.

IF YOU DON'T HAVE A POSTSCRIPT PRINTER
======================================

Look in perlref.sty for comments with ">>>>" as a guide.  The output
will not be as perfect, but still very useful.

HISTORY
=======

The first version of the Reference Guide --"reference card" it was
called then-- appeared in 1989 with Perl version 2. It was created
using an Apple Macintosh and the RagTime DeskTop publishing tool. It
was 9 pages, if I remember well. The PostScript output was extracted
from the Mac and hacked for 'normal' use with the macps program.

With Perl version 3 came the next version. A 15-page card format, and
a 16-page reference guide. This time, the Guide was created using
MicroSoft Word, again on Macintosh. Tools were supplied to manipulate
the PostScript file to suit different printing formats. In a later
version, the card format was abandoned.

Next came the Camel version, with Perl version 4. Lots of measurements
had been taken to have the abundance of new functions fit on 16 pages.

After the book appeared, I decided to rework the Guide to use more
pages, and different styles and fonts for clarity. I reworked the
MS-Word version, to find out that the resultant PostScript file had
increased from 90Kb to 180Kb! 
So I decided to start again, from scratch (well, almost) using the
LaTeX typesetting system. The resultant PostScript file is now 80Kb,
while it prints out almost identical to the 180Kb MS-Word version.

When Perl 5 came out, the Guide was reworked to include the plethora
of new features while still trying to be concise. 
I also used a scan of the Camel to create a real cover page.
Tim O'Reilly (O'Reilly & Associates, Inc.) wrote me:

    You can do this, as long as you say somewhere in your text,
    "The camel as an image associated with perl is a trademark
    of O'Reilly & Associates, Inc. and is used with permission."

    Trademarks are funny. If you don't use due diligence to protect
    them, you lose them. We've applied to treat all our cover animals
    as trademarks, so they don't get abused by other publishers, and
    we need to acknowledge them as such if they are used elsewhere.

Thanks Tim, for the permission.

Paul Raines then borrowed the style file and other support files
to create a Reference Guide for Tk/Tcl.

CREDITS FOR PERL REFERENCE GUIDE
================================

The Perl Reference Guide is copyrighted by the author. It may be
reproduced, printed and distributed freely, as long as the original
author gets the credits, and the copyright notice is not removed from
the text. It may not be turned into a commercial product except with
written permission of the author.

---------------------------- author info -----------------------------
			    Johan Vromans
    Squirrel Design, Graskamp 10, 2771 KW Boskoop, the Netherlands
    also: NLnet, Kruislaan 419, 1098 VA Amsterdam, the Netherlands
	       tel. +31 20 6639366, fax. +31 20 6655311
			  email: <jv@NL.net>
----------------------------------------------------------------------

I like to thank everyone who has helped me (and encouraged me) to get
the job done, and to get the results to you. Especially Tom
Christiansen and JGreely (for "parr") And Larry Wall, of course,
without whom I would have spent lots of time annoying myself.

Roy Johnson <rjohnson@shell.com> sent me a scan of the Camel that I
used to make the cover page. The cover design is based on the design
that O'Reilly made for the Reference Guide that was published with the
book "Programming Perl" and is used with permission of O'Reilly &
Associates, Inc.

-- PostScript is a trademark of Adobe, I assume.
$Id: README,v 5.3 1995/01/19 14:23:20 jv Exp $

CREDITS FOR TCL/TK REFERENCE GUIDE
==================================

The Tcl/Tk Reference Guide is copyrighted by the author. It may be
reproduced, printed and distributed freely, as long as the original
author gets the credits, and the copyright notice is not removed from
the text. It may not be turned into a commercial product except with
written permission of the author.

---------------------------- author info -----------------------------
			    Paul Raines
	     MS 42 Stanford Linear Accelerator Center
		  Stanford, California 94309-4349
			tel. (415) 926 4378
		  email: <raines@slac.stanford.edu>
----------------------------------------------------------------------

Thanks to Jeff Tranter for Tcl reference parts and of course
John Ousterhout for creating Tcl and Tk.

