Note: this page is discontinued as of 2025-11-30. See here for the current version: https://core.tcl-lang.org/tcl/wiki?name=Proposed+changes+to+the+Tcl/Tk+manual+pages

In general

• Each manual page should have at least one example
• The code examples use different ways of showing resulting values (sometimes after the code line in italics, sometimes in a new row with an arrow in front); this should be unified and made visually pleasing
• Unify the way of representing optional repeating arguments; we have e.g. foreach varlist1 list1 ?varlist2 list2 ...? body (one instance of the repetitive option), linsert list index ?element element ...? (two instances), append varName ?value value value ...? (three instances)
• Each page could have a HISTORY section which tells the user in which version the command first appeared and which options and subcommands came in what version (perhaps as a kind of table for the more rich commands). The section could also document how to work around specific functional changes (even more important between Tcl8 and Tcl9!).
• Some pages refer to packages (oo and msgcat are two examples); these pages have different outlines: The oo::define page describes both commands (oo::define and oo::objdefine) directly in the DESCRIPTION section while the msgcat page only has a short text under DESCRIPTION and then describes the different msgcat commands in a separate COMMANDS section. The tcltest package has even more commands and here there are further sections on the same level besides the DESCRIPTION and the COMMANDS sections. A unification would be valuable. In general, it is a good idea to use a (sub)subsection for each (sub)command so that it can be handled nicely for inclusion into a TOC and can also take proper attributes (for class definition helping the HTML rendering e.g.).

Inconsistent use of terms

Many commands have 'subcommands'. They are also called 'options'. However, in the SYNOPSIS section of the manual pages, the usage is mixed. E.g., the namespace page calls it 'subcommand' while the string page calls it 'option' although they are the exact same thing, namely the second word of a command when it can have different meanings (as opposed to the usage in e.g. the fconfigure page where the second word always means the same and therefor has a specific name reflecting this specific meaning). Let us call this the simple case. Further, other pages such as the clock page don't use this way of writing the synopsis but list every subcommand individually. Let's call this the extended case. -> The way of presenting a command in the SYNOPSIS section should be consistent on all manual pages by using either the extended case on all pages or using the simple case (TB tends to prefer the extended case). When using the simple case, the usage of 'subcommand' or 'option' should be consistent (TB prefers the former, also because it is used in the output of the error messages inside the Tcl interpreter when using commands wrongly). In any case, when talking about the various subcommands/options in the text of the manual pages, the usage should be consistent there too.

The problem with the term 'option' is that it is also used for the real options, i.e. for the words in a command that are optional. As an example, the namespace manual page uses this term for the -force option of the namespace import command. Other commands such as the unload command use the term 'switch' instead. Also this needs unification (TB tends to call everything an 'option' can takes a value, and call everything that does not take a value a 'switch').

There is also an inconsistency with the term 'window'. For the commands [wm] and [winfo] the term often refers to a toplevel window (although not explicitly stated) whereas for the widget commands (label, ttk::label and the others), the term 'window' refers to the widget and is not a toplevel window. This may lead to misconception that the [wm] and [winfo] commands apply to any "window". This is the case especially as there are commands such as [winfo children] that can also operate on any widget, not just toplevels. The term is still the same. -> Use the term 'toplevel' where a toplevel is to be specified, and use 'window' where any widget (including toplevels) can be specified.

Another inconsistency is mentioned in this Tcl ticket on chan.n regarding the use of channelID vs channelName and how to call the "things" in a command in general.

Inconsistent use of command syntax

The syntax written in the "SYNOPSIS" section is also not consistent. E.g. some commands list the possible syntax with with one line for each variant (return). Others just use one line with the keyword "switches" and leave it to the DESCRIPTION to mention the possible forms (lsort). Thy way that the syntax of a command is described in the SYNOPSIS should be the same for all manual pages.

In specific manual pages

Tcl → Tcl.n

1. The Tcl.n page has a section "SYNOPSIS" but it contains nothing in terms of syntax compared to the other pages. It just says "Summary of Tcl language syntax".

Tcl → dict

1. dict map does not mention what happens with valueVariable. It should say: "... the result of the script is put into an accumulator dictionary using the key that is the current content of the keyVariable variable at that point and the return value of the script as the value for that key."
2. dict for could mention a bit clearer that it is an iterator just as foreach and others and works equivalently. IT also seems wrong that TCL_CONTINUE should be the same as TCL_OK.

Tcl → fconfigure

1. The text for the -encoding option does not specify how to spell the names of the encodings. As these are not the MIME/IANA names, a reference to encoding name will help to understand which encodings are available and how to spell them, also because they are case-sensitive ('UTF-8' is not recognized as it is not the same as 'utf-8').

Tcl → file

1. file tempfile doesn't tell where it puts the temporary files. Should it be documented that on Windows e.g. it is in the $env(TEMP) directory?

Tcl → interp

1. The section on interp create explains the -safe option but does not refer/link to the section where safe interpreters are explained in detail.
2. The description of interp create ?-safe? ... does not mention the safe command and how safe is different from interp create -safe (i.e. the so-called "Safe Base" as explained in Welsh's Practical Programming book). The same should be added to the manual page for safe

Tcl → lassign

1. The example usage of lassign for stepwise "digestion" of a long list should be more clear and have a second example for digesting option value pairs as in:

set options [list -value 1 -word one -translation uno]
while [llength $options] {
   lassign $options opt val
   # do something with 'opt' and 'val'
}

Tcl → lmap

1. There is no simple example of the first form of the command, operating on only one list

# note that you cannot use {return "$a=$b"} as the body: that would terminate the lmap loop after the first iteration
lmap {a b} [list a 1 b 2 c 3] {
   # return one element via the set command:
   set val "$a=$b"
}
# this returns a list with three elements: a=1 b=2 c=3

Tcl → msgcat

1. ::msgcat::mcpreferences. The explanation, especially in the second paragraph ("A set of locale preferences may be given to set the list of locale preferences. The current locale is also set, which is the first element of the locale preferences list") is not easy to understand. It should be rephrased.

Tcl → oo

1. The manual pages documenting the oo system use package require tcl::oo or package require TclOO in the synopsis. Although both seem to work, this is not consistent. In addition, the line is not even needed as the oo system is loaded by default. These lines should be removed.

Tcl → package

1. The manual page describes what to do in order to produce pkgIndex.tcl file for a package. However, there is no link to the manual page pkg::create which serves a similar (the same?) purpose
2. The manual page should at least mention the pkgIndex.tcl file used for packages. Better even give an example of how to create one using the package commands
3. Look here for further ideas to improve: comp.lang.tcl (by: Luc - Tue, 12 Mar 2024 18:57)
4. Also look here: comp.lang.tcl (by: aotto1968 – Fri, 21 Jun 2024 11:40)

Tcl → parray

1. It should be mentioned that the command returns an empty string (so you cannot easily capture the out into a variable inside a script)

Tcl → safe

1. see comment for the command interp

Tcl → string

1. There's a section on 'obsolete subcommands'. That's nice but there is no indication on what to choose instead of [string wordstart] and [string wordend]

Tcl → trace

1. When an execution trace is active on a procedure, the trace will be removed when redefining this procedure (overwriting it with [proc ...].) This seems not to be documented on the page.

Tcl → try

1. Mention that try {some script} will stop execution and report an error if there is one. It is not the same as catch {some script}. What happens when leaving out all optional arguments is currently only mentioned in this phrase: "(or the body if no handler matched) is allowed to continue to propagate", and this is is very difficult to decode and understand.
2. Mention that catch {some script} is equivalent to try {some script} on error {} {}

Tcl → update

1. As update is considered harmful, this warning and more info should be added to that manual page and an example should be given how to use it properly or what to use instead of update.

---

Tk → canvas

1. The sentence for the canvasx and canvasy command are not very understandable with respect to screenx/screeny (and in the first there is no comma while there is a comma in the latter)

Tk → photo

1. The -zoom option to the copy command does not mention that the zoom factors must be integers.

Tk → tk_optionMenu

1. The manual page is very thin. It should have more details (e.g. that the items created are "just" plain menu items of type 'radiobutton'
2. The example is too simple; enhance it with code showing how to manipulate the menu items after the creation
3. Add a link to the menu command which is used to manipulate the items
4. Add an example of how to loop over the items in a menu since a specific subcommand is missing here:

for {set index 0} {$index <= [.foo.menu index end]} {incr index} {
   puts "[.foo.menu entrycget $index -label] is a '[.foo.menu type $index]'"
}

Tk → ttk::button

1. The manual does not say that the -command is not invoked when the button state is not 'normal'. It may be self-explanatory but is not documented. (This may also be the case for other widgets and could be thus documented under the 'standard option' for-state
   

Tk → ttk::entry

1. The manual page describes how to do validation of the input. It mentions that a script template must be specified for -validatecommand. However, it does not explain what a script template is. In the section VALIDATION, the different substitutions are explained but not that this is what the 'script template' is about (just a reference to [bind] is made which means, users have to understand [bind] in order to understand this statement). It is suggested to just insert a sentence here saying that these substitutions can be used as arguments to the script template.

2. For the option -validatecommand, the manual says: "If set to the empty string (the default), validation is disabled". However, in the VALIDATION section below, the manual says: "If -validatecommand is empty (the default), validation always succeeds.". This is not consistent. Although the effect is the same (no change happens to the entered value), this is misleading. The text for the option should be changed to reflect what the section VALIDATION say, ie. that validation always succeeds when the script is empty.

3. The text of the section VALIDATION start with "The -validate, -validatecommand, and -invalidcommand options are used to enable entry widget validation". This is weird, three options to enable one feature. Wording should change. It is only the -validate option that en/disables validation. The other two option just configure in which way the validation is done when it is enabled.

4. The manual does not explain what the validation condition "forced" means (in the %V substitution).

Tk → ttk::style

1. For the command ttk::style configure it should be written that a style not already existing will automatically be created: "If style does not yet exist, it will be created".
2. The args argument in ttk::style element element create ... is undocumented.
3. The manual page for the API Ttk_RegisterElementFactory mentioned in ttk::style element element create ... does not exist.
4. All information in the linked Tcl'2004 conference presentation should be included here in the manual page if relevant for the understanding and documentation of the functioning of the command.

Tk → winfo

1. For the winfo children command, add a link to pack/place slaves for those who want a list of windows in packing order instead of stacking order (not easy to find if you don't know where to look; for grid this is different semantics)

---

thread

1. The thread page has a link in the "See also" section which is a URL to a page von www.tck.tk. That page is kind of a tutorial (and is interestingly not reachable when just browsing the site, no link leads here). It should not be listed in the "See also" section. Generally, such links not being internal to the manual pages, should be in a different section of the manual pages, preferrably in a section dedicated to tutorials so we can have a common place to link tutorials to man pages.