Tcl Source Code

Proposed changes to the Tcl/Tk manual pages
Login
☰Core Home Timeline Branches Tags Forum Tickets Download Wiki
Help

This page proposes some changes to the content of the Tcl (and Tk) manual pages, as follow-up to TIP 700.

General changes

Overall structure/outline of manual pages

The sections (first level of the outline) of the manual pages should be the same in all cases and follow this order:

Example code

Each manual page should have at least one example for the basic usage of a command

The code examples use different ways of showing resulting values (sometimes after the code line in italics, sometimes in a new line with an arrow in front). This should be unified and made visually pleasing.

Representing optional arguments

Unify the way of representing optional repeating arguments; we have e.g.

The proposal is to only have one instance an let the "..." always mean to repeat the previous argument inside the pair of "?". When there are more than one argument, they all need to be repeated.

History section

Each page could have a HISTORY section which tells the reader 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!).

Common overall structure

Some pages refer to packages (oo and msgcat are two examples). These pages have different outlines:

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.). A proposal for a common outline of the pages is not ready yet.

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 (the author (TB) tends to prefer the extended case). When using the simple case, the usage of 'subcommand' or 'option' should be consistent (the author 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 (is this a command or a subcommand?). Other commands such as unload use the term 'switch' instead. Also this needs unification (the author 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.

The proposal is to 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.

In any case, it is also proposed to have a separate page actually explaining these terms and how to read the syntax (i.e. what does it mean when a term is printed in bold, italic, inside a pair of "?" and what the function of the "..." is.

Inconsistent use of command syntax in the SYNOPSIS

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

Capitalization of syntax elements

The Tcl commands are presented by sometimes giving the arguments names. The after manual page is on example. The command after ms is presented with the named argument "ms". This is fine and makes it easy for readers to know what the argument is supposed to mean. However, when used in the normal text these names are using upper case letters when they are at the beginning of the text of the beginning of a sentence. Example

Ms must be an integer giving a time in milliseconds.

... that was previously scheduled. Id indicates which command ...

In a technical documentation such as the manual pages, consistency and accuracy are more important than traditional capitalization rules. If an argument is defined as ms or id, capitalizing it to Ms or Id at the start of a sentence could suggest it's a different argument, confuse readers who are looking for exact matches, break the mental model that technical identifiers are case-sensitive. Most technical documentation follows this practice. We should do so too.

If this seems odd to some people, it may help to know that these terms will be rendered differently anyway and should be written using the semantic markdown outlined in TIP 700. This mean, the above sentences would turn into markdown like this:

[ms]{.arg} must be an integer giving a time in milliseconds.

... that was previously scheduled. [id]{.arg} indicates which command ...

Imagine these arguments are rendered with a different font and colour (possibly with another background colour) consistent with how they look like in the command line definition itself, then capitalization does not make sense at all and the rendering makes sure that no-one really would expect this anymore.

In general, arguments that are variable names should be marked as such (e.g. we now have listVar, variableList, varName). A uniform naming scheme is recommended here, using camelCase to avoid misunderstandings. camelCase is good for the names of longer arguments. It makes them easier to read (as a replacement of the space that otherwise would separate words) and avoids odd readings (e.g. adict vs aDict). However, abbreviation should be used sparsely (the current dictionary manual pages use "dictionaryValue" and "dictionaryVariable"). Although a long word, using these full versions avoids misunderstandings and no glossary is needed to explain that "var..." means variables and "a..." means the value inside a variable.

Changes 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". Unclear what to do about it here. Maybe, this page is a special case.

Tcl → chan

  1. Under chan configure, the page contains a reference to channel options that are not supported for all channel types ("In addition, each channel type may add options that only it supports"). However, it remains unclear whether the commands named as examples (socket, open) are the only ones and which options these are. It could help to give a complete list of commands here and just list their options. With this, readers looking for a specific option will at least have it mentioned here and then know where to look further as this page serves as a hub to chan configure.

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.

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?
  2. file normalize does not resolve symbolic links. This is not explicitly stated but can be learned from the context of the description. It should be made explicit: "The command does not resolve symbolic links contained in the last path component. This one exception is necessary, because Tcl or the user may wish to operate ..." (see also the discussion in TIP 738).

Tcl → info

  1. info script is documented to return a path name. However, it is not documented that this pathname is returned just as it was specified, either as a relative or an absolute path. This should be added after the first sentence: "The returned pathname is an absolute or relative path, depending on how the path was specified when the script was called". The rationale is that using the path from info script after using cd to form a file name will lead to a different path than one might think when implicitly thinking that info script will always return the absolute path (see also the discussion in TIP 738).

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 → namespace

In the "Importing commands" section, BLT is takes for the examples. This should perhaps be changed as BLT is no longer maintained and does not run with Tcl 9. Maybe an example packge from tcllib woudl be better.

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 or the rationale be explained.

Tcl → package

  1. The manual page describes what to do in order to produce a 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)
  5. The package forget command can be called without a package name ... but the manual does not say what then happens.

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) but prints using puts to stdout.

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 {} {}
  3. The page mentions the "options dictionary of the interpreter" which can be retrieved when an error occurs. The page does, however, not explain how this dictionary look like. A link to the [return] and [catch] manual pages should be inserted here where the dictionary is explained.

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 sentences for the canvasx and canvasy commands 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 → clipboard

  1. The manual page reads as if different types of data can be read from the clipboard using clipboard get. It should be documented that Windows and macOS gan only handle -type STRING and all others lead to an error while on Linux you can do more, such as fetch binary/image data: image create photo img -data [binary format c* [clipboard get -type image/png]]

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 says, 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 options 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 manual pages.

tcltest

  1. The normalizeMsg command is only documented to remove "extra" newlines. However, it also removed uppercase letter in the msg. This should be documented.

Other considerations

This page was generated in about 0.003s by Fossil 2.29 [2d6bfabc9e] 2026-10-06 18:57:29