#3746 trace documentation is confusing

obsolete: 8.4.14
closed-fixed
46. Traces (50)
9
2007-12-13
2007-07-18
legolas_a20
No

See discussion here:
http://groups.google.com/group/comp.lang.tcl/browse_thread/thread/e0a7179c3c55bab5/2ea134e0b6662b9b?hl=en#2ea134e0b6662b9b

This part of the documentation of 'trace' is confusing because it uses the word 'command' in several different meanings, in adjacent sentences. From the current text about trace, with pieces *marked*:

--------------------------
trace add execution name ops *command*

Arrange for *command* to be executed whenever *command* name is executed
[..]

enterstep

Invoke *command* for every Tcl *command* which is executed inside the
*procedure* name, just before the actual execution takes place. For
example if we have 'proc foo {} { puts "hello" }', then an enterstep
trace would be invoked just before puts "hello" is executed. Setting
an enterstep trace on a *command* will not result in an error and is
simply ignored.

leavestep

Invoke *command* for every Tcl *command* which is executed inside the
procedure name, just after the actual execution takes place. Setting
a leavestep trace on a *command* will not result in an error and is
simply ignored.
-------------------------

I propose changing it to something along these lines:

trace add execution name ops *script*

Arrange for *script* to be executed whenever *command* name is executed[..]

Invoke *script* for every Tcl *command* [..]

Setting an enterstep trace on a *command that is not a proc ("Tcl Build-
In commands" or a command provided by a compiled extension)* will not [..]

- Changing the first 'command' to script will reduce the uses of command in a different meaning from 4 to 3.
- The last use of command needs some form of qualification, since without it, the text basically says: "Run script whenever a command x is executed. It is ok to pass a command as x." and that seems to say the same thing twice.
- I still think having the overall text talk about the 'command name', then having the details like for enterstep talk about the 'procedure name' is confusing, however I cannot suggest anything better as I (now) understand that for enter and leave it really is any command, while for enterstep and leavestep it is only useful if command is a procedure.

Discussion

    • labels: 104246 --> 46. Traces
    • assigned_to: nobody --> dgp
     
  • Don Porter
    Don Porter
    2007-10-31

    • priority: 5 --> 9
     
    • assigned_to: dgp --> dkf
    • status: open --> closed-fixed
     
  • Logged In: YES
    user_id=79902
    Originator: NO

    They're not scripts, they're command prefixes (and the terms needed to be used consistently throughout the whole manpage).