path: root/development/tkcon/man/man1/tkcon.1

'\"
'\" Generated from file 'tkcon\&.1\&.man' by tcllib/doctools with format 'nroff'
'\" Copyright (c) Jeffrey Hobbs (jeff at hobbs\&.org)
'\"
.TH "tkcon" 1 2\&.5 tkcon\&.1 "TkCon"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive
.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"
.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..
.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
tkcon \- Tk console replacement
.SH SYNOPSIS
\fBtkcon\fR [{\fIoption\fR \fIvalue\fR | \fItcl_script\fR} \&.\&.\&.]
.sp
.BE
.SH DESCRIPTION
.PP
TkCon is a replacement for the standard console that comes with Tk
(on Windows/Mac, but also works on Unix)\&.
The console itself provides many more features than the standard
console\&.
TkCon works on all platforms where Tcl/Tk is available\&.
It is meant primarily to aid one when working with the little
details inside Tcl and Tk, giving Unix users the GUI console
provided by default in the Mac and Windows Tk\&.
.TP
\fBtkcon\fR [{\fIoption\fR \fIvalue\fR | \fItcl_script\fR} \&.\&.\&.]
.PP
.SH OPTIONS
.PP
Except for \fB-rcfile\fR, command line arguments are handled after
the TkCon resource file is sourced, but before the slave
interpreter or the TkCon user interface is initialized\&.
.PP
\fB-rcfile\fR is handled right before it would be sourced,
allowing you to specify any alternate file\&.
Command line arguments are passed to each new console and
will be evaluated by each\&.
To prevent this from happening, you have to say
.CS


tkcon main set argv {}; tkcon main set argc 0

.CE
.PP
For these options, any unique substring is allowed\&.
.TP
\fB-argv\fR (also \fB--\fR)
Causes TkCon to stop evaluating arguments and set the remaining
args to be argv/argc (with \fB--\fR prepended)\&.
This carries over for any further consoles\&.
This is meant only for wrapping TkCon
around programs that require their own arguments\&.
.TP
\fB-color-<color>\fR \fIcolor\fR
Sets the requested color type to the specified color for tkcon\&.
See \fBtkconrc\fR(5) for the recognized \fB<color>\fR names\&.
.TP
\fB-eval\fR \fItcl_script\fR (also \fB-main\fR or \fB-e\fR)
A Tcl script to eval in each main interpreter\&.
This is evaluated after the resource file is loaded and the
slave interpreter is created\&.
Multiple \fB-eval\fR switches will be recognized (in order)\&.
.TP
\fB-exec\fR \fIslavename\fR
Sets the named slave that tkcon operates in\&.
In general, this is only useful to set to \fI""\fR (empty),
indicating to tkcon to avoid the multi-interpreter model and
operate in the main environment\&.
When this is empty, any further arguments will be only used
in the first tkcon console and not passed onto further new consoles\&.
This is useful when using tkcon as a console for extended wish
executables that don't load there commands into slave interpreters\&.
.TP
\fB-font\fR \fIfont\fR
Sets the font that tkcon uses for its text windows\&.
If this isn't a fixed width font, tkcon will override it\&.
.TP
\fB-nontcl\fR \fITCL_BOOLEAN\fR
Sets \fB::tkcon::OPT(nontcl)\fR to \fITCL_BOOLEAN\fR (see
\fBtkconrc\fR(5))\&.
Needed when attaching to non-Tcl interpreters\&.
.TP
\fB-package\fR \fIpackage_name\fR (also \fB-load\fR)
Packages to automatically load into the slave interpreters (i\&.e\&. "Tk")\&.
.TP
\fB-rcfile\fR \fIfilename\fR
Specify an alternate tkcon resource file name\&.
.TP
\fB-root\fR \fIwidgetname\fR
Makes the named widget the root name of all consoles (i\&.e\&. \&.tkcon)\&.
.TP
\fB-slave\fR \fItcl_script\fR
A Tcl script to eval in each slave interpreter\&.
This will append the one specified in the tkcon resource file, if any\&.
.PP
.SH "KEY BINDINGS"
.PP
Most of the bindings are the same as for the \fBtext\fR widget\&.
Some have been modified to make sure that the integrity of the
console is maintained\&.
Others have been added to enhance the usefulness of the console\&.
Only the modified or new bindings are listed here\&.
.TP
\fBControl-x\fR or \fBCut\fR (on Sparc5 keyboards)
Cut\&.
.TP
\fBControl-c\fR or \fBCopy\fR (on Sparc5 keyboards)
Copy\&.
.TP
\fBControl-v\fR or \fBPaste\fR (on Sparc5 keyboards)
Paste\&.
.TP
\fBInsert\fR
Insert (duh)\&.
.TP
\fBUp\fR
Goes up one level in the commands line history when cursor is on
the prompt line, otherwise it moves through the buffer\&.
.TP
\fBDown\fR
Goes down one level in the commands line history when cursor
is on the last line of the buffer, otherwise it moves through the buffer\&.
.TP
\fBControl-p\fR
Goes up one level in the commands line history\&.
.TP
\fBControl-n\fR
Goes down one level in the commands line history\&.
.TP
\fBTab\fR
Tries to expand file path names, then variable names, then proc names\&.
.TP
\fBEscape\fR
Tries to expand file path names\&.
.TP
\fBControl-P\fR
Tries to expand procedure names\&.
The procedure names will be those that are actually in the attached
interpreter (unless nontcl is specified, in which case it always
does the lookup in the default slave interpreter)\&.
.TP
\fBControl-V\fR
Tries to expand variable names (those returned by [info vars])\&.
It's search behavior is like that for procedure names\&.
.TP
\fBReturn\fR or \fBEnter\fR
Evaluates the current command line if it is a complete command,
otherwise it just goes to a new line\&.
.TP
\fBControl-a\fR
Go to the beginning of the current command line\&.
.TP
\fBControl-l\fR
Clear the entire console buffer\&.
.TP
\fBControl-r\fR
Searches backwards in the history for any command that contains
the string in the current command line\&.
Repeatable to search farther back\&.
The matching substring off the found command will blink\&.
.TP
\fBControl-s\fR
As above, but searches forward (only useful if you searched too far back)\&.
.TP
\fBControl-t\fR
Transposes characters\&.
.TP
\fBControl-u\fR
Clears the current command line\&.
.TP
\fBControl-z\fR
Saves current command line in a buffer that can be retrieved
with another \fBControl-z\fR\&.
If the current command line is empty, then any saved command
is retrieved without being overwritten, otherwise the current
contents get swapped with what's in the saved command buffer\&.
.TP
\fBControl-Key-1\fR
Attaches console to the console's slave interpreter\&.
.TP
\fBControl-Key-2\fR
Attaches console to the console's master interpreter\&.
.TP
\fBControl-Key-3\fR
Attaches console to main TkCon interpreter\&.
.TP
\fBControl-A\fR
Pops up the "About" dialog\&.
.TP
\fBControl-N\fR
Creates a new console\&. Each console has separate state, including
it's own widget hierarchy (it's a slave interpreter)\&.
.TP
\fBControl-q\fR
Close the current console OR Quit the program (depends on the
value of \fB::tkcon::TKCON(slaveexit)\fR)\&.
.TP
\fBControl-w\fR
Closes the current console\&.
Closing the main console will exit the program (something has
to control all the slaves\&.\&.\&.)\&.
.PP
.PP
TkCon also has electric bracing (similar to that in emacs)\&.
It will highlight matching pairs of {}'s, []'s, ()'s and ""'s\&.
For the first three, if there is no matching left element for the right,
then it blinks the entire current command line\&.
For the double quote, if there is no proper match then it just blinks
the current double quote character\&.
It does properly recognize most escaping (except escaped escapes),
but does not look for commenting (why would you interactively
put comments in?)\&.
.SH COMMANDS
.PP
There are several new procedures introduced in TkCon to improve
productivity and/or account for lost functionality in the Tcl
environment that users are used to in native environments\&.
There are also some redefined procedures\&.
Here is a non-comprehensive list:
.TP
\fBalias\fR ?\fIsourceCmd\fR \fItargetCmd\fR ?\fIarg\fR \fIarg\fR \&.\&.\&.??
Simple alias mechanism\&.
It will overwrite existing commands\&.
When called without args, it returns current aliases\&.
Note that TkCon makes some aliases for you (in slaves)\&.
Don't delete those\&.
.TP
\fBclear\fR ?\fIpercentage\fR?
Clears the text widget\&.
Same as the <\fBControl-l\fR> binding, except this will accept a
percentage of the buffer to clear (1-100, 100 default)\&.
.TP
\fBdir\fR ?\fI-all\fR? ?\fI-full\fR? ?\fI-long\fR? ?\fIpattern\fR \fIpattern\fR \&.\&.\&.?
Cheap way to get directory listings\&.
Uses glob style pattern matching\&.
.TP
\fBdump\fR \fItype\fR ?\fI-nocomplain\fR? ?\fI-filter pattern\fR? ?\fB--\fR? \fIpattern\fR ?\fIpattern\fR \&.\&.\&.?
The dump command provides a way for the user to spit out state
information about the interpreter in a Tcl readable (and
human readable) form\&.
See \fBdump\fR(n) for details\&.
.TP
\fBecho\fR ?\fIarg\fR \fIarg\fR \&.\&.\&.?
Concatenates the args and spits the result to the console (stdout)\&.
.TP
\fBedit\fR ?\fI-type type\fR? ?\fI-find str\fR? ?\fI-attach interp\fR? \fIarg\fR
Opens an editor with the data from arg\&.
The optional type argument can be one of: \fIproc\fR, \fIvar\fR or \fIfile\fR\&.
For proc or var, the arg may be a pattern\&.
.TP
\fBidebug\fR \fIcommand\fR ?\fIargs\fR?
Interactive debugging command\&.
See \fBidebug\fR(n) for details\&.
.TP
\fBlremove\fR ?\fI-all\fR? ?\fI-regexp\fR \fI-glob\fR? \fIlist\fR \fIitems\fR
Removes one or more items from a list and returns the new list\&.
If \fI-all\fR is specified, it removes all instances of each item
in the list\&.
If \fI-regexp\fR or \fI-glob\fR is specified, it interprets each item in
the items list as a regexp or glob pattern to match against\&.
.TP
\fBless\fR
Aliased to \fBedit\fR\&.
.TP
\fBls\fR
Aliased to \fBdir\fR \fI-full\fR\&.
.TP
\fBmore\fR
Aliased to \fBedit\fR\&.
.TP
\fBobserve\fR \fItype\fR ?\fIargs\fR?
This command provides passive runtime debugging output for
variables and commands\&.
See \fBobserve\fR(n) for details\&.
.TP
\fBputs\fR (same options as always)
Redefined to put the output into TkCon\&.
.TP
\fBtkcon\fR \fImethod\fR ?\fIargs\fR?
Multi-purpose command\&.
See \fBtkcon\fR(n) for details\&.
.TP
\fBtclindex\fR \fI?-extensions patternlist? ?-index TCL_BOOLEAN? ?-package TCL_BOOLEAN? ?dir1 dir2 \&.\&.\&.?\fR
Convenience proc to update the "\fItclIndex\fR" (controlled by \fI-index\fR switch)
and/or "\fIpkgIndex\&.tcl\fR" (controlled by \fI-package\fR switch) file in the named
directories based on the given pattern for files\&.
It defaults to creating the "\fItclIndex\fR" but not the "\fIpkgIndex\&.tcl\fR" file,
with the directory defaulting to [pwd]\&.
The extension defaults to *\&.tcl, with *\&.[info sharelibextension]
added when \fI-package\fR is true\&.
.TP
\fBunalias\fR \fIcmd\fR
unaliases command\&.
.TP
\fBwhat\fR \fIstring\fR
The what command will identify the word given in string in
the Tcl environment and return a list of types that it was recognized as\&.
Possible types are: alias, procedure, command, array variable,
scalar variable, directory, file, widget, and executable\&.
Used by procedures dump and which\&.
.TP
\fBwhich\fR \fIcommand\fR
Like the \fBwhich\fR command of Unix shells, this will tell you if a
particular command is known, and if so, whether it is internal or
external to the interpreter\&.
If it is an internal command and there is a slot in \fBauto_index\fR for it,
it tells you the file that \fBauto_index\fR would load\&.
This does not necessarily mean that that is where the file came from,
but if it were not in the interpreter previously, then that
is where the command was found\&.
.PP
.PP
There are several procedures that I use as helpers that some may find
helpful in there coding (i\&.e\&. expanding pathnames)\&. Feel free to lift
them from the code (but do assign proper attribution)\&.
.SH EXAMLPES
.PP
Some examples of tkcon command line startup situations:
.CS


\fBmegawish\fR /usr/bin/tkcon \fB-exec\fR "" \fB-root\fR \&.tkcon \fImainfile\&.tcl\fR

.CE
Use tkcon as a console for your \fBmegawish\fR application\&.
You can avoid starting the line with megawish if that is the
default \fBwish\fR that TkCon would use\&.
The \fB-root\fR ensures that tkcon will not conflict with the
application root window\&.
.CS


\fBtkcon\fR \fB-font\fR "Courier 12" \fB-load\fR Tk

.CE
Use the courier font for TkCon and always load Tk in slave
interpreters at startup\&.
.CS


\fBtkcon\fR \fB-rcfile\fR ~/\&.wishrc \fB-color-bg\fR white

.CE
Use the ~/\&.wishrc file as the resource file, and a white
background for TkCon's text widgets\&.
.SH FILES
TkCon will search for a resource file in "\fI~/\&.tkconrc\fR"\&.
TkCon never sources the "\fI~/\&.wishrc\fR" file\&.
The resource file is sourced by each new instance of the console\&.
An example resource file is provided in \fBtkconrc\fR(5)\&.
.SH "SEE ALSO"
\fBdump\fR(n), \fBidebug\fR(n), \fBobserve\fR(n), \fBtext\fR(n), \fBtkcon\fR(n), \fBtkconrc\fR(5)
.SH KEYWORDS
Tk, console
.SH COPYRIGHT
.nf
Copyright (c) Jeffrey Hobbs (jeff at hobbs\&.org)

.fi