+2007-06-21 Jeff Hobbs <jeffh@ActiveState.com>
+
+ * docs/tkcon.1.man, docs/tkcon.n.man, docs/tkconrc.5.man (new):
+ * docs/dump.n.man, docs/observe.n.man, docs/idebug.n.man (new):
+ * index.html, docs/demopic.gif (removed), docs/demopic.png (new):
+ * docs/plugin.html, docs/start.html, docs/tkcon.html:
+ Updated docs and added doctools equivalents courtesy Sergei Golovan
+ * docs/style.css: updated stylesheet
+
2007-04-04 Jeff Hobbs <jeffh@ActiveState.com>
*** BUMPED TO VERSION 2.5 ***
--- /dev/null
+[comment {-*- tcl -*- dump manpage}]
+[manpage_begin dump n 2.5]
+[copyright {Jeffrey Hobbs <jeff at hobbs.org>}]
+[moddesc {TkCon}]
+[titledesc {Dump information about Tcl interpreter in TkCon}]
+
+[description]
+[para]
+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.
+It takes the general form:
+
+[list_begin definitions]
+
+[call [cmd dump] [arg method]\
+ [opt [arg -nocomplain]]\
+ [opt [arg "-filter pattern"]]\
+ [opt [cmd --]]\
+ [arg pattern]\
+ [opt [arg "pattern ..."]]]
+
+[list_end]
+
+[para]
+The patterns represent glob-style patterns (as in [cmd string] [arg {match pattern $str}]).
+[arg -nocomplain] will prevent dump from throwing an error if no items
+matched the pattern.
+[arg -filter] is interpreted as appropriate for the method.
+The various methods are:
+
+[list_begin definitions]
+
+[lst_item "[cmd dump] [arg command] [arg args]"]
+Outputs one or more commands.
+
+[lst_item "[cmd dump] [arg procedure] [arg args]"]
+Outputs one or more procs in sourceable form.
+
+[lst_item "[cmd dump] [arg variable] [arg args]"]
+Outputs the values of variables in sourceable form.
+Recognizes nested arrays.
+The -filter pattern is used as to filter array element
+names and is interepreted as a glob pattern (defaults to {*}).
+It is passed down for nested arrays.
+
+[lst_item "[cmd dump] [arg widget] [arg args]"]
+Outputs one or more widgets by giving their configuration options.
+The -filter pattern is used as to filter the config options and
+is interpreted as a case insensitive regexp pattern (defaults to {.*}).
+
+[list_end]
+
+[see_also [cmd tkcon](1)]
+[see_also [cmd tkconrc](5) [cmd tkcon](n) [cmd idebug](n)]
+[see_also [cmd observe](n)]
+[keywords Tk console dump]
+
+[manpage_end]
+
--- /dev/null
+[comment {-*- tcl -*- idebug manpage}]
+[manpage_begin idebug n 2.5]
+[copyright {Jeffrey Hobbs <jeff at hobbs.org>}]
+[moddesc {TkCon}]
+[titledesc {Interactive debugging environment in TkCon}]
+
+[description]
+[para]
+The idebug command provides an interactive debugging
+environment for procedures via TkCon.
+You can place idebug break commands into your procedure
+to create breakpoints.
+It will pop up the TkCon console and put you into a
+"debugging" mode.
+The [arg body], [arg show] & [arg trace] methods are
+intended for internal use only.
+
+This procedure works for minimal debugging sessions.
+Comments are encouraged.
+
+[list_begin definitions]
+
+[call [cmd idebug] [arg body] [opt [arg level]]]
+Prints out the body of the command (if it is a procedure)
+at the specified level.
+level defaults to the current level.
+
+[call [cmd idebug] [arg break] [opt [arg id]]]
+Creates a breakpoint within a procedure.
+This will only trigger if idebug is on and the [arg id] matches the pattern.
+If so, TkCon will pop to the front with the prompt changed
+to an idebug prompt.
+You are given the basic ability to observe the call stack
+an query/set variables or execute Tcl commands at any level.
+A separate history is maintained in debugging mode.
+To see the special commands available at the debug prompt,
+type ? and hit return.
+
+[call [cmd idebug] \{[arg "[arg echo] [opt [arg id]]"]\} [opt [arg args]]]
+Behaves just like [cmd echo], but only triggers when idebug is on.
+You can specify an optional [arg id] to further restrict triggering.
+If no id is specified, it defaults to the name of the command
+in which the call was made.
+
+[call [cmd idebug] [arg id] [opt [arg id]]]
+Query or set the idebug id.
+This id is used by other idebug methods to determine if
+they should trigger or not.
+The idebug id can be a glob pattern and defaults to *.
+
+[call [cmd idebug] [arg off]]
+Turns idebug off.
+
+[call [cmd idebug] [arg on] [opt [arg id]]]
+Turns idebug on.
+If [arg id] is specified, it sets the id to it.
+
+[call [cmd idebug] \{[arg "[arg puts] [opt [arg id]]"]\} [arg args]]
+Behaves just like [cmd puts], but only triggers when idebug is on.
+You can specify an optional [arg id] to further restrict triggering.
+If no id is specified, it defaults to the name of the
+command in which the call was made.
+
+[call [cmd idebug] [arg show] [arg type] [opt [arg level]] [opt [arg VERBOSE]]]
+type must be one of vars, locals or globals.
+This method will output the variables/locals/globals present
+in a particular level.
+If [arg VERBOSE] is added, then it actually [cmd dump]s out the values as well.
+level defaults to the level in which this method was called.
+
+[call [cmd idebug] [arg trace] [opt [arg level]]]
+Prints out the stack trace from the specified level up to the top level.
+level defaults to the current level.
+
+[list_end]
+
+[see_also [cmd tkcon](1)]
+[see_also [cmd tkconrc](5) [cmd tkcon](n) [cmd dump](n)]
+[see_also [cmd observe](n)]
+[keywords Tk console debug]
+
+[manpage_end]
+
--- /dev/null
+[comment {-*- tcl -*- observe manpage}]
+[manpage_begin observe n 2.5]
+[copyright {Jeffrey Hobbs <jeff at hobbs.org>}]
+[moddesc {TkCon}]
+[titledesc {Runtime debugging output in TkCon}]
+
+[description]
+[para]
+This command provides runtime debugging output for variables
+and commands without the need to edit your code.
+For variables, the underlying mechanism uses [cmd trace] and [cmd dump] var.
+For commands, it renames the observed procedure and uses a
+special wrapper procedure.
+WARNING: using this procedure after checkpointing state will
+result in major problems if you clean state because the
+renamed (true) commands will be lost.
+
+[para]
+This procedure is experimental.
+Comments are encouraged.
+
+[list_begin definitions]
+
+[call [cmd observe] [arg command] [arg cmdname] [opt [arg maxlevel]]]
+This will create a wrapper command which prints out (using [cmd dump])
+the call stack to the console.
+maxlevel represents the maximum number of levels of the call
+stack which will be printed (defaults to 4).
+
+[call [cmd observe] [arg cdelete] [arg cmdname]]
+Removes the wrapper around an observed command.
+
+[call [cmd observe] [arg cinfo] [arg cmdname]]
+Prints out useless info.
+
+[call [cmd observe] [arg variable] [arg varname] [arg operation] [opt [arg args]]]
+Currently a wrapper around trace that uses [cmd dump] to print out
+the value of the named variable whenever the specified
+operation on that variable occurs (must be [arg read], [arg write] or [arg unset]).
+
+[call [cmd observe] [arg vdelete] [arg varname] [arg operation]]
+Deletes the trace wrapper around the named variable.
+
+[call [cmd observe] [arg vinfo] [arg varname]]
+Prints out trace info about the named variable.
+
+[list_end]
+
+[see_also [cmd tkcon](1)]
+[see_also [cmd tkconrc](5) [cmd tkcon](n) [cmd dump](n)]
+[see_also [cmd idebug](n)]
+[keywords Tk console debug]
+
+[manpage_end]
+
</P>
Have a look at some of the features: (culled from the
-<A HREF="./">tkcon documentation</A>)
+<A HREF="index.html">tkcon documentation</A>)
<UL>
<LI> <B>Variable / Path / Procedure Name Expansion.</B> Type in
<CODE>set tc</CODE> at the prompt. Hit <I><Control-Shift-V></I>.
<DD> A tcl script to execute in the main interpreter after the slave
interpreter is created and the user interface is initialized.
+<DT> <CODE>::tkcon::OPT(maxlinelen)</CODE>
+<DD> A number that specifies the limit of long result lines.
+True result is still captured in $_ (and 'puts $_' works).
+Defaults to 0 (unlimited).
+
<DT> <CODE>::tkcon::OPT(maxmenu)</CODE>
<DD> A number that specifies the maximum number of packages to show
vertically in the Interp->Packages menu before breaking into
<style type="text/css">
-/* default formatting
- *
- * we should be able to combine these as body,td,... but IE 5 isn't
- * isn't standard compliant... (sigh)
- */
-body {
+body, div, p, th, td, li, dd, ul, ol, dl, dt, blockquote {
font-family: Arial, Helvetica, sans-serif;
- font-size: 10pt;
}
-td {
- font-family: Arial, Helvetica, sans-serif;
- font-size: 10pt;
+body {
+ background-color: #FFFFFF;
+ font-size: 12px;
+ line-height: 1.25;
+ letter-spacing: .2px;
}
th {
- font-family: Arial, Helvetica, sans-serif;
- font-size: 10pt;
font-style: bold;
text-align: left;
}
-p {
- font-family: Arial, Helvetica, sans-serif;
- font-size: 10pt;
-}
-ul {
- font-family: Arial, Helvetica, sans-serif;
- font-size: 10pt;
-}
a { text-decoration: none }
-.hi {
+.hi, .hi2 {
font-weight: bold;
color: #B82619;
background: #FFFFCC;
text-decoration: none;
}
-.hi2 {
- font-weight: bold;
- color: #B82619;
- background: #CCFFCC;
- text-decoration: none;
-}
+.hi2 { background: #CCFFCC; }
.indent { margin: 3px; }
/* general styles */
.heading {
- font-family: Arial, Helvetica, sans-serif;
- font-size: 14pt;
+ font-size: 14px;
font-weight: bold;
color: #B82619;
}
.subheading {
- font-family: Arial, Helvetica, sans-serif;
- font-size: 10pt;
font-weight: bold;
color: #B82619;
}
--- /dev/null
+[comment {-*- tcl -*- tkcon manpage}]
+[manpage_begin tkcon 1 2.5]
+[copyright {Jeffrey Hobbs (jeff at hobbs.org)}]
+[moddesc {TkCon}]
+[titledesc {Tk console replacement}]
+
+[description]
+[para]
+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.
+
+[list_begin definitions]
+[call [cmd tkcon] [lb]\{[arg option] [arg value] | [arg tcl_script]\} ...[rb]]
+[list_end]
+
+[section OPTIONS]
+[para]
+Except for [cmd -rcfile], command line arguments are handled after
+the TkCon resource file is sourced, but before the slave
+interpreter or the TkCon user interface is initialized.
+
+[para]
+[cmd -rcfile] 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
+
+[example_begin]
+tkcon main set argv {}; tkcon main set argc 0
+[example_end]
+
+[para]
+For these options, any unique substring is allowed.
+
+[list_begin definitions]
+[lst_item "[cmd -argv] (also [cmd --])"]
+Causes TkCon to stop evaluating arguments and set the remaining
+args to be argv/argc (with [cmd --] prepended).
+This carries over for any further consoles.
+This is meant only for wrapping TkCon
+around programs that require their own arguments.
+
+[lst_item "[cmd -color-<color>] [arg color]"]
+Sets the requested color type to the specified color for tkcon.
+See [cmd tkconrc](5) for the recognized [cmd <color>] names.
+
+[lst_item "[cmd -eval] [arg tcl_script] (also [cmd -main] or [cmd -e])"]
+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 [cmd -eval] switches will be recognized (in order).
+
+[lst_item "[cmd -exec] [arg slavename]"]
+Sets the named slave that tkcon operates in.
+In general, this is only useful to set to [arg {""}] (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.
+
+[lst_item "[cmd -font] [arg font]"]
+Sets the font that tkcon uses for its text windows.
+If this isn't a fixed width font, tkcon will override it.
+
+[lst_item "[cmd -nontcl] [arg TCL_BOOLEAN]"]
+Sets [cmd ::tkcon::OPT(nontcl)] to [arg TCL_BOOLEAN] (see
+[cmd tkconrc](5)).
+Needed when attaching to non-Tcl interpreters.
+
+[lst_item "[cmd -package] [arg package_name] (also [cmd -load])"]
+Packages to automatically load into the slave interpreters (i.e. "Tk").
+
+[lst_item "[cmd -rcfile] [arg filename]"]
+Specify an alternate tkcon resource file name.
+
+[lst_item "[cmd -root] [arg widgetname]"]
+Makes the named widget the root name of all consoles (i.e. .tkcon).
+
+[lst_item "[cmd -slave] [arg tcl_script]"]
+A Tcl script to eval in each slave interpreter.
+This will append the one specified in the tkcon resource file, if any.
+
+[list_end]
+
+[section {KEY BINDINGS}]
+[para]
+Most of the bindings are the same as for the [cmd text] 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.
+
+[list_begin definitions]
+
+[lst_item "[cmd Control-x] or [cmd Cut] (on Sparc5 keyboards)"]
+Cut.
+
+[lst_item "[cmd Control-c] or [cmd Copy] (on Sparc5 keyboards)"]
+Copy.
+
+[lst_item "[cmd Control-v] or [cmd Paste] (on Sparc5 keyboards)"]
+Paste.
+
+[lst_item [cmd Insert]]
+Insert (duh).
+
+[lst_item [cmd Up]]
+Goes up one level in the commands line history when cursor is on
+the prompt line, otherwise it moves through the buffer.
+
+[lst_item [cmd Down]]
+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.
+
+[lst_item [cmd Control-p]]
+Goes up one level in the commands line history.
+
+[lst_item [cmd Control-n]]
+Goes down one level in the commands line history.
+
+[lst_item [cmd Tab]]
+Tries to expand file path names, then variable names, then proc names.
+
+[lst_item [cmd Escape]]
+Tries to expand file path names.
+
+[lst_item [cmd Control-P]]
+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).
+
+[lst_item [cmd Control-V]]
+Tries to expand variable names (those returned by [lb]info vars[rb]).
+It's search behavior is like that for procedure names.
+
+[lst_item "[cmd Return] or [cmd Enter]"]
+Evaluates the current command line if it is a complete command,
+otherwise it just goes to a new line.
+
+[lst_item [cmd Control-a]]
+Go to the beginning of the current command line.
+
+[lst_item [cmd Control-l]]
+Clear the entire console buffer.
+
+[lst_item [cmd Control-r]]
+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.
+
+[lst_item [cmd Control-s]]
+As above, but searches forward (only useful if you searched too far back).
+
+[lst_item [cmd Control-t]]
+Transposes characters.
+
+[lst_item [cmd Control-u]]
+Clears the current command line.
+
+[lst_item [cmd Control-z]]
+Saves current command line in a buffer that can be retrieved
+with another [cmd Control-z].
+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.
+
+[lst_item [cmd Control-Key-1]]
+Attaches console to the console's slave interpreter.
+
+[lst_item [cmd Control-Key-2]]
+Attaches console to the console's master interpreter.
+
+[lst_item [cmd Control-Key-3]]
+Attaches console to main TkCon interpreter.
+
+[lst_item [cmd Control-A]]
+Pops up the "About" dialog.
+
+[lst_item [cmd Control-N]]
+Creates a new console. Each console has separate state, including
+it's own widget hierarchy (it's a slave interpreter).
+
+[lst_item [cmd Control-q]]
+Close the current console OR Quit the program (depends on the
+value of [cmd ::tkcon::TKCON(slaveexit)]).
+
+[lst_item [cmd Control-w]]
+Closes the current console.
+Closing the main console will exit the program (something has
+to control all the slaves...).
+
+[list_end]
+
+[para]
+TkCon also has electric bracing (similar to that in emacs).
+It will highlight matching pairs of {}'s, [lb][rb]'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?).
+
+[section COMMANDS]
+[para]
+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:
+
+[list_begin definitions]
+
+[lst_item "[cmd alias] ?[arg sourceCmd] [arg targetCmd] ?[arg arg] [arg arg] ...??"]
+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.
+
+[lst_item "[cmd clear] ?[arg percentage]?"]
+Clears the text widget.
+Same as the <[cmd Control-l]> binding, except this will accept a
+percentage of the buffer to clear (1-100, 100 default).
+
+[lst_item "[cmd dir] ?[arg -all]? ?[arg -full]? ?[arg -long]?\
+ ?[arg pattern] [arg pattern] ...?"]
+Cheap way to get directory listings.
+Uses glob style pattern matching.
+
+[lst_item "[cmd dump] [arg type] ?[arg -nocomplain]? ?[arg {-filter pattern}]?\
+ ?[cmd --]? [arg pattern] ?[arg pattern] ...?"]
+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 [cmd dump](n) for details.
+
+[lst_item "[cmd echo] ?[arg arg] [arg arg] ...?"]
+Concatenates the args and spits the result to the console (stdout).
+
+[lst_item "[cmd edit] ?[arg {-type type}]? ?[arg {-find str}]?\
+ ?[arg {-attach interp}]? [arg arg]"]
+Opens an editor with the data from arg.
+The optional type argument can be one of: [arg proc], [arg var] or [arg file].
+For proc or var, the arg may be a pattern.
+
+[lst_item "[cmd idebug] [arg command] ?[arg args]?"]
+Interactive debugging command.
+See [cmd idebug](n) for details.
+
+[lst_item "[cmd lremove] ?[arg -all]? ?[arg -regexp] [arg -glob]?\
+ [arg list] [arg items]"]
+Removes one or more items from a list and returns the new list.
+If [arg -all] is specified, it removes all instances of each item
+in the list.
+If [arg -regexp] or [arg -glob] is specified, it interprets each item in
+the items list as a regexp or glob pattern to match against.
+
+[lst_item [cmd less]]
+Aliased to [cmd edit].
+
+[lst_item [cmd ls]]
+Aliased to [cmd dir] [arg -full].
+
+[lst_item [cmd more]]
+Aliased to [cmd edit].
+
+[lst_item "[cmd observe] [arg type] ?[arg args]?"]
+This command provides passive runtime debugging output for
+variables and commands.
+See [cmd observe](n) for details.
+
+[lst_item "[cmd puts] (same options as always)"]
+Redefined to put the output into TkCon.
+
+[lst_item "[cmd tkcon] [arg method] ?[arg args]?"]
+Multi-purpose command.
+See [cmd tkcon](n) for details.
+
+[lst_item "[cmd tclindex] [arg {?-extensions patternlist? ?-index TCL_BOOLEAN?\
+ ?-package TCL_BOOLEAN? ?dir1 dir2 ...?}]"]
+Convenience proc to update the [file tclIndex] (controlled by [arg -index] switch)
+and/or [file pkgIndex.tcl] (controlled by [arg -package] switch) file in the named
+directories based on the given pattern for files.
+It defaults to creating the [file tclIndex] but not the [file pkgIndex.tcl] file,
+with the directory defaulting to [lb]pwd[rb].
+The extension defaults to *.tcl, with *.[lb]info sharelibextension[rb]
+added when [arg -package] is true.
+
+[lst_item "[cmd unalias] [arg cmd]"]
+unaliases command.
+
+[lst_item "[cmd what] [arg string]"]
+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.
+
+[lst_item "[cmd which] [arg command]"]
+Like the [syscmd which] 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 [cmd auto_index] for it,
+it tells you the file that [cmd auto_index] 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.
+
+[list_end]
+
+[para]
+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).
+
+[section EXAMLPES]
+[para]
+Some examples of tkcon command line startup situations:
+
+[example_begin]
+[cmd megawish] /usr/bin/tkcon [cmd -exec] "" [cmd -root] .tkcon [arg mainfile.tcl]
+[example_end]
+
+Use tkcon as a console for your [cmd megawish] application.
+You can avoid starting the line with megawish if that is the
+default [cmd wish] that TkCon would use.
+The [cmd -root] ensures that tkcon will not conflict with the
+application root window.
+
+[example_begin]
+[cmd tkcon] [cmd -font] "Courier 12" [cmd -load] Tk
+[example_end]
+
+Use the courier font for TkCon and always load Tk in slave
+interpreters at startup.
+
+[example_begin]
+[cmd tkcon] [cmd -rcfile] ~/.wishrc [cmd -color-bg] white
+[example_end]
+
+Use the ~/.wishrc file as the resource file, and a white
+background for TkCon's text widgets.
+
+[section FILES]
+TkCon will search for a resource file in [file ~/.tkconrc].
+TkCon never sources the [file ~/.wishrc] file.
+The resource file is sourced by each new instance of the console.
+An example resource file is provided in [cmd tkconrc](5).
+
+[see_also [cmd tkconrc](5)]
+[see_also [cmd dump](n) [cmd tkcon](n) [cmd idebug](n)]
+[see_also [cmd observe](n) [cmd text](n)]
+[keywords Tk console]
+
+[manpage_end]
+
<DT> <CODE>tkcon <b>iconify</b></CODE>
<DD> Iconifies the tkcon display.
+<DT> <CODE>tkcon <b>linelength</b></CODE> ?<i>value</i>?
+<DD> Sets or displays the number that specifies the limit of long result lines.
+True result is still captured in $_ (and 'puts $_' works).
+
<DT> <CODE>tkcon <b>load</b></CODE> <I>filename</I>
<DD> Sources named file into the slave interpreter. If no filename is
given, it will attempt to call <CODE>tk_getOpenFile</CODE> to pop up the
--- /dev/null
+[comment {-*- tcl -*- tkcon manpage}]
+[manpage_begin tkcon n 2.5]
+[copyright {Jeffrey Hobbs <jeff at hobbs.org>}]
+[moddesc {TkCon}]
+[titledesc {Controlling TkCon console}]
+
+[description]
+[para]
+This provides lots of useful control over a console:
+
+[list_begin definitions]
+
+[call [cmd tkcon] [arg attach] [arg interpreter]]
+Attaches tkcon to the named interpreter.
+The name must be that returned by [lb][cmd tk] [arg appname][rb] or a valid
+path to a slave interpreter.
+It's best to use this via the [arg {Console->Attach Console}] menu.
+
+[call [cmd tkcon] [arg buffer] [opt [arg size]]]
+Sets or queries the allowed size of the console text widget in lines.
+The text widget will automatically delete leading lines once this
+number has been exceeded (read: this is the scroll buffer size).
+
+[call [cmd tkcon] [arg bgerror] [opt "[arg msg] [arg errorInfo]"]]
+Does bgerror stuff in the tkcon master interpreter.
+
+[call [cmd tkcon] [arg close] or [cmd tkcon] [arg destroy]]
+Destroys this tkcon widget.
+
+[call [cmd tkcon] [arg congets]]
+Behaves like the traditional Tcl gets, but instead of using stdin,
+it uses the tkcon console window.
+By default, tkcon replaces the standard gets with this command.
+This behavior can be controlled by altering the [cmd ::tkcon::OPT(gets)]
+parameter at startup.
+This should not be called directly - instead rely on the overloaded
+gets, which has support for the optional varName parameter.
+
+[call [cmd tkcon] [arg console] [arg args]]
+Passes the args to the tkcon text widget (the console).
+
+[call [cmd tkcon] [arg error]]
+Pops up a dialog that gives the user a full trace of the
+last error received in the tkcon console.
+
+[call [cmd tkcon] [arg find] [arg string]\
+ [opt "[arg -case] [arg TCL_BOOLEAN] [arg -regexp] [arg TCL_BOOLEAN]"]]
+Highlights all instances of string in the console.
+If the string is empty, it clears any previous highlighting.
+
+[call [cmd tkcon] [arg font] [opt [arg fontname]]]
+Sets or returns the font used by tkcon text widgets.
+
+[call [cmd tkcon] [arg gets]]
+Behaves like the traditional Tcl gets, but instead of needing
+stdin, it pops a dialog box up for the user.
+The overloaded gets has support for the optional varName parameter.
+
+[call [cmd tkcon] [arg getcommand]]
+A variation of the congets method that requires a full
+command to be input before returning.
+
+[call [cmd tkcon] [arg hide]]
+Withdraw the tkcon display from the screen (make sure you
+have a way to get it back).
+
+[call [cmd tkcon] [arg history] [opt [arg -newline]]]
+Displays the tkcon history in sourceable form.
+If [arg -newline] is specified, it separates each command by
+an extra newline.
+
+[call [cmd tkcon] [arg iconify]]
+Iconifies the tkcon display.
+
+[call [cmd tkcon] [arg linelength] [opt [arg value]]]
+Sets or displays the number that specifies the limit of long result lines.
+True result is still captured in $_ (and 'puts $_' works).
+
+[call [cmd tkcon] [arg load] [arg filename]]
+Sources named file into the slave interpreter.
+If no filename is given, it will attempt to call
+[cmd tk_getOpenFile] to pop up the file select box.
+
+[call [cmd tkcon] [arg main] [opt "[arg arg] [arg arg] [arg ...]"]]
+Passes the args to the main tkcon interpreter to be
+evaluated and returns the result.
+
+[call [cmd tkcon] [arg master] [arg args]]
+Passes the args to the master interpreter to be evaluated
+and returns the result.
+
+[call [cmd tkcon] [arg new]]
+Creates a new tkcon widget.
+
+[call [cmd tkcon] [arg save] [opt "[arg filename] [opt [arg type]]"]]
+Saves the console buffer to the given filename.
+If no filename is given, it will attempt to call
+[cmd tk_getSaveFile] to pop up the file select box.
+If no type is given, a dialog will ask you to specify
+what portion of the text you want to save.
+
+[call [cmd tkcon] [arg set] [arg var] [opt [arg value]]]
+Queries or sets a master interpreter variable.
+
+[call [cmd tkcon] [arg append] [arg var] [opt [arg value]]]
+Like set, but uses append on the variable.
+
+[call [cmd tkcon] [arg lappend] [arg var] [opt [arg value]]]
+Like set, but uses lappend on the variable.
+
+[call [cmd tkcon] [arg show] or [cmd tkcon] [arg deiconify]]
+Redisplays tkcon on the screen.
+
+[call [cmd tkcon] [arg slave] [opt "[arg slavename] [opt [arg {arg arg ...}]]"]]
+If called with no args, it returns the name of all the tkcon interpreters.
+Otherwise given an interp name it passes the args to the named interpreter
+to be evaluated and returns the result.
+If no args are passed, then it returns the [lb][cmd tk] [arg appname][rb] of that
+interpreter.
+
+[call [cmd tkcon] [arg title] [opt [arg title]]]
+Sets or returns the title for tkcon.
+
+[call [cmd tkcon] [arg version]]
+Returns of version of tkcon.
+
+[list_end]
+
+[see_also [cmd tkcon](1)]
+[see_also [cmd tkconrc](5) [cmd tkcon](n) [cmd dump](n)]
+[see_also [cmd observe](n)]
+[keywords Tk console debug]
+
+[manpage_end]
+
--- /dev/null
+[comment {-*- tcl -*- tkconrc manpage}]
+[manpage_begin tkconrc 5 2.5]
+[copyright {Jeffrey Hobbs <jeff at hobbs.org>}]
+[moddesc {TkCon}]
+[titledesc {TkCon resource file}]
+
+[description]
+[para]
+TkCon will search for a resource file in [file ~/.tkconrc].
+TkCon never sources the [file ~/.wishrc] file.
+The resource file is sourced by each new instance of the console.
+An example resource file is provided below.
+
+[para]
+The file itself is a Tcl script, so it is required that the
+file conforms to Tcl script conventions.
+
+[section VARIABLES]
+[para]
+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 [arg Prefs] menu).
+All these are part of the master interpreter's [cmd ::tkcon]
+namespace.
+The modifiable array variables are [cmd ::tkcon::COLOR] and
+[cmd ::tkcon::OPT].
+You can call
+
+[example_begin]
+tkcon set ::tkcon::COLOR
+[example_end]
+
+when the program is running to check its state.
+Here is an explanation of certain variables you
+might change or use:
+
+[list_begin definitions]
+
+[lst_item [cmd ::tkcon::COLOR(bg)]]
+The background color for tkcon text widgets.
+Defaults to the operating system default (determined at startup).
+
+[lst_item [cmd ::tkcon::COLOR(blink)]]
+The background color of the electric brace highlighting, if on.
+Defaults to yellow.
+
+[lst_item [cmd ::tkcon::COLOR(cursor)]]
+The background color for the insertion cursor in tkcon.
+Defaults to black.
+
+[lst_item [cmd ::tkcon::COLOR(disabled)]]
+The foreground color for disabled menu items.
+Defaults to dark grey.
+
+[lst_item [cmd ::tkcon::COLOR(proc)]]
+The foreground color of a recognized proc, if command highlighting is on.
+Defaults to dark green.
+
+[lst_item [cmd ::tkcon::COLOR(var)]]
+The background color of a recognized var, if command highlighting is on.
+Defaults to pink.
+
+[lst_item [cmd ::tkcon::COLOR(prompt)]]
+The foreground color of the prompt as output in the console.
+Defaults to brown.
+
+[lst_item [cmd ::tkcon::COLOR(stdin)]]
+The foreground color of the stdin for the console.
+Defaults to black.
+
+[lst_item [cmd ::tkcon::COLOR(stdout)]]
+The foreground color of the stdout as output in the console.
+Defaults to blue.
+
+[lst_item [cmd ::tkcon::COLOR(stderr)]]
+The foreground color of stderr as output in the console.
+Defaults to red.
+
+[lst_item [cmd ::tkcon::OPT(autoload)]]
+Packages to automatically load into the slave interpreter (i.e. 'Tk').
+This is a list.
+Defaults to {} (none).
+
+[lst_item [cmd ::tkcon::OPT(blinktime)]]
+The amount of time (in millisecs) that braced sections should blink for.
+Defaults to 500 (0.5 secs), must be at least 100.
+
+[lst_item [cmd ::tkcon::OPT(blinkrange)]]
+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).
+
+[lst_item [cmd ::tkcon::OPT(buffer)]]
+The size of the console scroll buffer (in lines).
+Defaults to 512.
+
+[lst_item [cmd ::tkcon::OPT(calcmode)]]
+Whether to allow expr commands to be run at the command line
+without prefixing them with expr (just a convenience).
+
+[lst_item [cmd ::tkcon::OPT(cols)]]
+Number of columns for the console to start out with.
+Defaults to 80.
+
+[lst_item [cmd ::tkcon::OPT(dead)]]
+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.
+
+[lst_item [cmd ::tkcon::OPT(exec)]]
+This corresponds to the [cmd -exec] tkcon option (see [cmd tkcon](1)).
+
+[lst_item [cmd ::tkcon::OPT(font)]]
+Font to use for tkcon text widgets (also specified with [cmd -font] option).
+Defaults to the system default, or a fixed width equivalent.
+
+[lst_item [cmd ::tkcon::OPT(gets)]]
+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.
+
+[lst_item [cmd ::tkcon::OPT(history)]]
+The size of the history list to keep.
+Defaults to 48.
+
+[lst_item [cmd ::tkcon::OPT(hoterrors)]]
+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.
+
+[lst_item [cmd ::tkcon::OPT(library)]]
+The path to any tcl library directories (these are appended
+to the [cmd auto_path] when the after the resource file is loaded in).
+
+[lst_item [cmd ::tkcon::OPT(lightbrace)]]
+Whether to use the brace highlighting feature or not
+(respectively 1 or 0, defaults to 1).
+
+[lst_item [cmd ::tkcon::OPT(lightcmd)]]
+Whether to use the command highlighting feature or not
+(respectively 1 or 0, defaults to 1).
+
+[lst_item [cmd ::tkcon::OPT(maineval)]]
+A tcl script to execute in the main interpreter after the
+slave interpreter is created and the user interface is initialized.
+
+[lst_item [cmd ::tkcon::OPT(maxlinelen)]]
+A number that specifies the limit of long result lines.
+True result is still captured in $_ (and 'puts $_' works).
+Defaults to 0 (unlimited).
+
+[lst_item [cmd ::tkcon::OPT(maxmenu)]]
+A number that specifies the maximum number of packages to
+show vertically in the [arg Interp->Packages] menu before breaking
+into another column.
+Defaults to 15.
+
+[lst_item [cmd ::tkcon::OPT(nontcl)]]
+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.
+
+[lst_item [cmd ::tkcon::OPT(prompt1)]]
+Like [cmd tcl_prompt1], except it doesn't require you use [cmd puts].
+No equivalent for [cmd tcl_prompt2] is available (it's unnecessary IMHO).
+Defaults to {([lb]file tail [lb]pwd[rb][rb]) [lb]history nextid[rb] % }.
+
+[lst_item [cmd ::tkcon::OPT(rows)]]
+Number of rows for the console to start out with.
+Defaults to 20.
+
+[lst_item [cmd ::tkcon::OPT(scollypos)]]
+Y scrollbar position.
+Valid values are left or right.
+Defaults to right.
+
+[lst_item [cmd ::tkcon::OPT(showmenu)]]
+Show the menubar on startup (1 or 0, defaults to 1).
+
+[lst_item [cmd ::tkcon::OPT(showmultiple)]]
+Show multiple matches for path/proc/var name expansion (1 or 0,
+defaults to 1).
+
+[lst_item [cmd ::tkcon::OPT(slaveeval)]]
+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.
+
+[nl]
+Example:
+
+[example_begin]
+set ::tkcon::OPT(slaveeval) {
+ proc foo args { puts $args }
+ lappend auto_path .
+}
+[example_end]
+
+[lst_item [cmd ::tkcon::OPT(slaveexit)]]
+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.
+
+[lst_item [cmd ::tkcon::OPT(subhistory)]]
+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.
+
+[list_end]
+
+[section EXAMPLES]
+[para]
+An example TkCon resource file might look like:
+
+[example_begin]
+######################################################
+## 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
+######################################################
+[example_end]
+
+[see_also [cmd tkcon](1)]
+[see_also [cmd dump](n) [cmd tkcon](n) [cmd idebug](n)]
+[see_also [cmd observe](n)]
+[keywords Tk console]
+
+[manpage_end]
+
<TR>
<TH><A HREF="docs/index.html">Documentation</A></TH>
-<TH><A HREF="docs/demopic.gif">Screenshot</A></TH>
+<TH><A HREF="docs/demopic.png">Screenshot</A></TH>
<TH><A HREF="docs/plugin.html">Online Demo!</A> (requires
<A HREF="http://www.tcl.tk/software/plugin/">Tk plugin</A>)</TH>
<TH><A HREF="docs/license.terms">License</A> </TH>
</TR><TR>
<TD COLSPAN=4>
-<!-- <A HREF="ftp://tkcon.sourceforge.net/pub/tkcon/"><B>Release Archives</B>
-(ftp)</A><BR> -->
<A
HREF="http://sourceforge.net/project/showfiles.php?group_id=11462"><B>Release
Archives</B> (high speed server)</A>
</P>
<P>
You can grab the <A
-HREF="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tkcon/tkcon/tkcon.tcl?rev=HEAD">latest sources</A> from the
-<A HREF="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tkcon/tkcon/"><B>tkcon CVS repository</B></A>.
+HREF="http://tkcon.cvs.sourceforge.net/tkcon/tkcon/tkcon.tcl?rev=HEAD">latest sources</A> from the
+<A HREF="http://tkcon.cvs.sourceforge.net/tkcon/tkcon/"><B>tkcon CVS repository</B></A>.
</P>
</TD>
</TD></TR></TABLE>
-<P STYLE="font-family: arial, sans-serif">
+<P>
tkcon is a replacement for the standard console that comes with Tk (on
Windows/Mac, but also works on Unix). The console itself provides
<i>many</i> more features than the standard console. tkcon works on all
</P>
<HR NOSHADE SIZE=1>
-<ADDRESS><FONT SIZE=2>©
-<A HREF="mailto:jeff@hobbs.org">Jeffrey Hobbs</A></FONT></ADDRESS>
+<ADDRESS><FONT SIZE=2>© Jeffrey Hobbs (jeff at hobbs dot org)</FONT></ADDRESS>
</BODY>
</HTML>
projects / tkcon / commitdiff
