Re: typical TCL docu nonsens

et99 <et99@rocketship1.me> wrote:

On 6/21/2024 1:17 PM, aotto1968 wrote:
snip

 
the core problem is *not* the "autopath" is wrong because at the
time I use it I does not know it was wrong.  The core problem is
that is was *very* difficult to figure out what was the "right"
name.  special the tcl_traceExec… does not help and more important
the package.n docu (package require…) does *not* spend a single word
on *how* to find a package.

 
I'm not sure if this would have helped in your case, but I've used
this with some success.  It outputs every package command issued and
by using a search pattern to limit the output to the ifneeded
commands, sometimes gets me what I need to know.

aotto1968's complaint is that the "package" man page does not mention
that the auto_path variable stores the search path list for finding
packages.  And, I looked, it does not make any mention of the
"specialness" of that variable.

On my Slack15 install, all of the Tcl special variables are documented
in a man page named "tcl_library" (although the page contents believes
it is named "tclvars").  So auto_path's specialness /is/ documented,
but unless one has discovered that it is documented in a different
manpage from 'package', one could very well spend a lot of time and not
find the proper docs.

So the least disruptive change to cover aotto1968's complaint would be
for aotto1968 to file a patch against the package man page adding a
"see tcl_library manpage for Tcl special variables related to package
handling".

That, or aotto1968 should file a patch against the package namespace to
add a brief paragraph to the package manpage detailing that the special
global auto_path contains a list of directories within which to search
for packages when doing a package require.

Either of the above would be a proactive step to eliminate the problem.

Grumbling on Usenet about the issue is not taking any direct steps to
proactively eliminate the issue.