Added some documentation for the console command.

2 files changed, 102 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index 1c467a4..c12cd13 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2001-05-15  Donal K. Fellows  <fellowsd@cs.man.ac.uk>
+
+	* doc/console.n: Created.  It seems very odd to me that the
+	console implementation is part of the Tcl distribution and not
+	part of Tk, but given the location of the source, the
+	documentation must obviously match up...
+
 2001-05-14  Donal K. Fellows  <fellowsd@cs.man.ac.uk>
 
 	* generic/tclCmdMZ.c (Tcl_StringObjCmd): 
diff --git a/doc/console.n b/doc/console.n
new file mode 100644
index 0000000..c6f64a1
--- /dev/null
+++ b/doc/console.n
@@ -0,0 +1,95 @@
+'\"
+'\" Copyright (c) 2001 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" RCS: @(#) $Id: console.n,v 1.1 2001/05/15 09:50:13 dkf Exp $
+'\"
+.so man.macros
+.TH console n "" Tcl "Tcl Built-In Commands"
+.BS
+'\" This command is documented here because the implementation is part
+'\" of Tcl, even though it is only able to function when Tk is also
+'\" available...
+'\"
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+console \- Control the console on systems without a real console
+.SH SYNOPSIS
+\fBconsole title \fR?\fIstring\fR?
+.sp
+\fBconsole hide\fR
+.sp
+\fBconsole show\fR
+.sp
+\fBconsole eval \fIscript\fR
+.BE
+
+.SH DESCRIPTION
+.PP
+The console window is a replacement for a real console to allow input
+and output on the standard I/O channels on platforms that do not have
+a real console.  It is implemented as a separate interpreter with the
+Tk toolkit loaded, and control over this interpreter is given through
+the \fBconsole\fR command.
+.PP
+.TP
+\fBconsole eval \fIscript\fR
+Evaluate the \fIscript\fR argument as a Tcl script in the console
+interpreter.  The normal interpreter is accessed through the
+\fBconsoleinterp\fR command in the console interpreter.
+.TP
+\fBconsole hide\fR
+Hide the console window from view.  Precisely equivalent to
+withdrawing the \fB.\fR window in the console interpreter.
+.TP
+\fBconsole show\fR
+Display the console window.  Precisely equivalent to deiconifying the
+\fB.\fR window in the console interpreter.
+.TP
+\fBconsole title \fR?\fIstring\fR?
+Query or modify the title of the console window.  If \fIstring\fR is
+not specified, queries the title of the console window, and sets the
+title of the console window to \fIstring\fR otherwise.  Precisely
+equivalent to using the \fBwm title\fI command in the console
+interpreter.
+
+.SH "ACCESS TO THE MAIN INTERPRETER"
+.PP
+The \fBconsoleinterp\fR command in the console interpreter allows
+scripts to be evaluated in the main interpreter.  It supports two
+subcommands: \fBeval\fR and \fBrecord\fR.
+.PP
+.TP
+\fBconsoleinterp eval \fIscript\fR
+Evaluates \fIscript\fR as a Tcl script at the global level in the main
+interpreter.
+.TP
+\fBconsoleinterp record \fIscript\fR
+Records and evaluates \fIscript\fR as a Tcl script at the global level
+in the main interpreter as if \fIscript\fR had been typed in at the
+console.
+
+.SH "ADDITIONAL TRAP CALLS"
+.PP
+There are several additional commands in the console interpreter that
+are called in response to activity in the main interpreter.
+.PP
+Output to the console from the main interpreter via the stdout and
+stderr channels is handled by invoking the \fBtkConsoleOutput\fR
+command in the console interpreter with two arguments.  The first
+argument is the name of the channel being written to, and the second
+argument is the string being written to the channel (after encoding
+and end-of-line translation processing has been performed.)
+.PP
+When the \fB.\fR window of the main interpreter is destroyed, the
+\fBtkConsoleExit\fR command in the console interpreter is called
+(assuming the console interpreter has not already been deleted itself,
+that is.)
+
+.SH KEYWORDS
+console, Tk, interpreter, window, interactive, output channels
+
+.SH "SEE ALSO"
+destroy(n), fconfigure(n), history(n), interp(n), puts(n), wm(n)