path: root/development/tkcon/man/man5/tkconrc.5

'\"
'\" Generated from file 'tkconrc\&.5\&.man' by tcllib/doctools with format 'nroff'
'\" Copyright (c) Jeffrey Hobbs <jeff at hobbs\&.org>
'\"
.TH "tkconrc" 5 2\&.5 tkconrc\&.5 "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
tkconrc \- TkCon resource file
.SH DESCRIPTION
.PP
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 below\&.
.PP
The file itself is a Tcl script, so it is required that the
file conforms to Tcl script conventions\&.
.SH VARIABLES
.PP
Certain variables in TkCon can be modified to suit your needs\&.
It's easiest to do this in the resource file, but you can do
it when time the program is running (and some can be changed
via the \fIPrefs\fR menu)\&.
All these are part of the master interpreter's \fB::tkcon\fR
namespace\&.
The modifiable array variables are \fB::tkcon::COLOR\fR and
\fB::tkcon::OPT\fR\&.
You can call
.CS


tkcon set ::tkcon::COLOR

.CE
when the program is running to check its state\&.
Here is an explanation of certain variables you
might change or use:
.TP
\fB::tkcon::COLOR(bg)\fR
The background color for tkcon text widgets\&.
Defaults to the operating system default (determined at startup)\&.
.TP
\fB::tkcon::COLOR(blink)\fR
The background color of the electric brace highlighting, if on\&.
Defaults to yellow\&.
.TP
\fB::tkcon::COLOR(cursor)\fR
The background color for the insertion cursor in tkcon\&.
Defaults to black\&.
.TP
\fB::tkcon::COLOR(disabled)\fR
The foreground color for disabled menu items\&.
Defaults to dark grey\&.
.TP
\fB::tkcon::COLOR(proc)\fR
The foreground color of a recognized proc, if command highlighting is on\&.
Defaults to dark green\&.
.TP
\fB::tkcon::COLOR(var)\fR
The background color of a recognized var, if command highlighting is on\&.
Defaults to pink\&.
.TP
\fB::tkcon::COLOR(prompt)\fR
The foreground color of the prompt as output in the console\&.
Defaults to brown\&.
.TP
\fB::tkcon::COLOR(stdin)\fR
The foreground color of the stdin for the console\&.
Defaults to black\&.
.TP
\fB::tkcon::COLOR(stdout)\fR
The foreground color of the stdout as output in the console\&.
Defaults to blue\&.
.TP
\fB::tkcon::COLOR(stderr)\fR
The foreground color of stderr as output in the console\&.
Defaults to red\&.
.TP
\fB::tkcon::OPT(autoload)\fR
Packages to automatically load into the slave interpreter (i\&.e\&. 'Tk')\&.
This is a list\&.
Defaults to {} (none)\&.
.TP
\fB::tkcon::OPT(blinktime)\fR
The amount of time (in millisecs) that braced sections should blink for\&.
Defaults to 500 (0\&.5 secs), must be at least 100\&.
.TP
\fB::tkcon::OPT(blinkrange)\fR
Whether to blink the entire range for electric brace matching
or to just blink the actual matching braces (respectively 1 or 0,
defaults to 1)\&.
.TP
\fB::tkcon::OPT(buffer)\fR
The size of the console scroll buffer (in lines)\&.
Defaults to 512\&.
.TP
\fB::tkcon::OPT(calcmode)\fR
Whether to allow expr commands to be run at the command line
without prefixing them with expr (just a convenience)\&.
.TP
\fB::tkcon::OPT(cols)\fR
Number of columns for the console to start out with\&.
Defaults to 80\&.
.TP
\fB::tkcon::OPT(dead)\fR
What to do with dead connected interpreters\&.
If dead is leave, TkCon automatically exits the dead interpreter\&.
If dead is ignore then it remains attached waiting for the
interpreter to reappear\&.
Otherwise TkCon will prompt you\&.
.TP
\fB::tkcon::OPT(exec)\fR
This corresponds to the \fB-exec\fR tkcon option (see \fBtkcon\fR(1))\&.
.TP
\fB::tkcon::OPT(font)\fR
Font to use for tkcon text widgets (also specified with \fB-font\fR option)\&.
Defaults to the system default, or a fixed width equivalent\&.
.TP
\fB::tkcon::OPT(gets)\fR
Controls whether tkcon will overload the gets command to work with tkcon\&.
The valid values are: congets (the default), which will redirect
stdin requests to the tkcon window; gets, which will pop up a dialog to
get input; and {} (empty string) which tells tkcon not to overload gets\&.
This value must be set at startup to alter tkcon's behavior\&.
.TP
\fB::tkcon::OPT(history)\fR
The size of the history list to keep\&.
Defaults to 48\&.
.TP
\fB::tkcon::OPT(hoterrors)\fR
Whether hot errors are enabled or not\&.
When enabled, errors that are returned to the console are marked
with a link to the error info that will pop up in an minimal editor\&.
This requires more memory because each error that occurs will
maintain bindings for this feature, as long as the error
is in the text widget\&.
Defaults to on\&.
.TP
\fB::tkcon::OPT(library)\fR
The path to any tcl library directories (these are appended
to the \fBauto_path\fR when the after the resource file is loaded in)\&.
.TP
\fB::tkcon::OPT(lightbrace)\fR
Whether to use the brace highlighting feature or not
(respectively 1 or 0, defaults to 1)\&.
.TP
\fB::tkcon::OPT(lightcmd)\fR
Whether to use the command highlighting feature or not
(respectively 1 or 0, defaults to 1)\&.
.TP
\fB::tkcon::OPT(maineval)\fR
A tcl script to execute in the main interpreter after the
slave interpreter is created and the user interface is initialized\&.
.TP
\fB::tkcon::OPT(maxlinelen)\fR
A number that specifies the limit of long result lines\&.
True result is still captured in $_ (and 'puts $_' works)\&.
Defaults to 0 (unlimited)\&.
.TP
\fB::tkcon::OPT(maxmenu)\fR
A number that specifies the maximum number of packages to
show vertically in the \fIInterp->Packages\fR menu before breaking
into another column\&.
Defaults to 15\&.
.TP
\fB::tkcon::OPT(nontcl)\fR
For those who might be using non-Tcl based Tk attachments, set this to 1\&.
It prevents TkCon from trying to evaluate its own Tcl
code in an attached interpreter\&.
Also see my notes for non-Tcl based Tk interpreters\&.
.TP
\fB::tkcon::OPT(prompt1)\fR
Like \fBtcl_prompt1\fR, except it doesn't require you use \fBputs\fR\&.
No equivalent for \fBtcl_prompt2\fR is available (it's unnecessary IMHO)\&.
Defaults to {([file tail [pwd]]) [history nextid] % }\&.
.TP
\fB::tkcon::OPT(rows)\fR
Number of rows for the console to start out with\&.
Defaults to 20\&.
.TP
\fB::tkcon::OPT(scollypos)\fR
Y scrollbar position\&.
Valid values are left or right\&.
Defaults to right\&.
.TP
\fB::tkcon::OPT(showmenu)\fR
Show the menubar on startup (1 or 0, defaults to 1)\&.
.TP
\fB::tkcon::OPT(showmultiple)\fR
Show multiple matches for path/proc/var name expansion (1 or 0,
defaults to 1)\&.
.TP
\fB::tkcon::OPT(slaveeval)\fR
A tcl script to execute in each slave interpreter right after it's created\&.
This allows the user to have user defined info always available in a slave\&.
.sp
Example:
.CS


set ::tkcon::OPT(slaveeval) {
    proc foo args { puts $args }
    lappend auto_path \&.
}

.CE
.TP
\fB::tkcon::OPT(slaveexit)\fR
Allows the prevention of exit in slaves from exitting the entire application\&.
If it is equal to exit, exit will exit as usual, otherwise it will just close
down that interpreter (and any children)\&.
Defaults to close\&.
.TP
\fB::tkcon::OPT(subhistory)\fR
Allow history substitution to occur (0 or 1, defaults to 1)\&.
The history list is maintained in a single interpreter per TkCon console
instance\&.
Thus you have history which can range over a series of attached interpreters\&.
.PP
.SH EXAMPLES
.PP
An example TkCon resource file might look like:
.CS


######################################################
## My TkCon Resource File

# Use a fixed default font
#tkcon font fixed; # valid on unix
#tkcon font systemfixed; # valid on win
tkcon font Courier 12; # valid everywhere

# Keep 50 commands in history
set ::tkcon::OPT(history) 50

# Use a pink prompt
set ::tkcon::COLOR(prompt) pink
######################################################

.CE
.SH "SEE ALSO"
\fBdump\fR(n), \fBidebug\fR(n), \fBobserve\fR(n), \fBtkcon\fR(1), \fBtkcon\fR(n)
.SH KEYWORDS
Tk, console
.SH COPYRIGHT
.nf
Copyright (c) Jeffrey Hobbs <jeff at hobbs\&.org>

.fi