# The `tcl' Mode

## Introduction

The `tcl` mode of `jedit` is intended for editing Tcl code. Among its major features are a `Procs' menu that lets you quickly jump to a particular procedure definition and rudimentary support for automatic indentation.

This document describes the `tcl` mode available with version 4.1/4.4 of `jedit`.

## Preferences

In `tcl` mode, by default, the Space and Return keys do not do abbreviation expansion (although you can do it by hand with the commands on the `Abbrev' menu), lines do not have newlines inserted automatically as you approach the right margin, and when you type a closing parenthesis, bracket or brace, the corresponding opening character briefly flashes (assuming it's visible on the screen). Also, new lines start with the same indentation as the preceeding line, except as modified by `tcl` mode's automatic indentation, described below. Of course, you can change any of these settings on the ModeSpecific Preferences panel.

## The `Tcl' Menu and the Buttonbar

The `tcl` mode provides a `Tcl' menu with commands for manipulating comments.

### Comment with #

`Comment with #' prepends a hash mark and a space to each line of the selected text. It's useful for commenting out sections of code.

### Comment with ###

`Comment with ###' functions identically to `Comment with #', except that it uses three hash marks instead of one. I use this to comment out sections of code that I want to call my attention to later.

### Uncomment

`Uncomment' removes any number of hash marks followed by a space from the beginning of the selected lines. (Tip: You can reformat commented prose by selecting it, choosing `Uncomment', choosing `Format lines with ``fmt''' from the `Format' menu, and choosing `Comment with #'.)

### Make Border

`Make Border' inserts a line consisting of 70 hash marks, followed by a newline. I use this as part of my block comments before procedure definitions, and sometimes as a separator.

### The Buttonbar

The `tcl`mode buttonbar has buttons which duplicate the functions of the commands on the `Tcl' menu, and also a `Save' button which duplicates the `Save' command on the `File' menu.

## The `Procs' Menu

The `Procs' menu provides a dynamic list of all the procedure definitions in the current file. You can choose a procedure name from the `Procs' menu to jump quickly to the specified procedure definition.

The `Procs' menu is generated by searching the text for lines starting with the characters ``proc`' followed by a space or a tab, so it may not list procedures defined in an unusual coding style. (On the other hand, Tcl's `auto_mkindex` procedure probably wouldn't find them either.)

## Automatic Indentation

Normally, as you type in `tcl` mode, each line gets the same indentation as the previous line had. However, `tcl` mode has a little understanding of Tcl syntax, and will adjust the indentation of lines in some circumstances. The intention is that you should be able to type Tcl code without having to worry about indentation, and the code should be automatically indented for you.

In particular, when a line ends with an opening brace (possibly followed by a comment), the indentation of the following line is increased, and when a line starts with a closing brace, it's indentation is decreased when you hit Return. Also, when a line ends with a backslash, the indentation of a following line is increased. (Indentation is restored following the next line that does not end in a backslash.

It may be a little clearer to see some examples of Tcl code whose indentation `tcl` mode handles well:
`frame .foo \
-width 10 -height 20 \
-background blue
proc foo {} {
global bar
if $bar { ; # comment
baz
} else { }
}
format {
%d dollars,
%d cents.
} $dollars $cents
`
However, `tcl` mode's parsing is not very elaborate. In particular, it has trouble with the following constructions:
`set foo {
bar
baz} ;# close brace not at beginning of line
catch {
$t tag configure comment -foreground grey50 \
-font -*-lucida-medium-r-normal-sans-10-100-*
} ;# last line before close brace is a continuation
`
Also, use of braces to delimit strings may confuse it, and use of double quotation marks spanning multiline stretches of Tcl code will confuse it.

Furthermore, the automatic indentation of each line relies on the assumption that the indentation of the preceding line is already correct, and there's no mechanism (as there is in GNU Emacs, for instance) to automatically reindent a stretch of existing code.

## See Also

The `code' Mode

## Comment Highlighting

There's some code in the file that implements `tcl` mode (normally installed as /usr/local/lib/jstools/jeditmodes/tcl-mode.tcl) for automatic highlighting of comments, but that code is currently disabled, because it's very slow. If you want to experiment with it, you can copy that file to your ~/.tk/jeditmodes directory and reenable it.

## Evolution

### Bugs and Limitations

* In addition to the limitations mentioned above under Automatic Indentation, the main problem with `tcl` mode is that indentation is hardwired to two per level of nesting.

### Future Directions

* Perhaps `tcl` mode can do some syntaxdependent highlighting along the lines of the disabled commentfinding code. This should be much more efficient in Tk 4.

* There should be a set of preferences for things like indentation depth and whether to highlight keywords or comments. This will require changes to `jedit`'s mode and preferencehandling mechanisms.
`
`