Re: typical TCL docu nonsens

At Fri, 21 Jun 2024 21:55:54 -0000 (UTC) Rich <rich@example.invalid> wrote:

 
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".

I suspect that the tcl_library manpage is replicated from the tclvars man
page.  A number of Tcl's (and Tk's) man pages are dups.  Which happen at build
or install time (links?) or possibly using an old UNIX trick where man pages
can implement a re-direct -- this is done because some man pages cover
multiple closely related topics (or groups commands that have common
documentation.

 
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.
 
          
 

--
Robert Heller             -- Cell: 413-658-7953 GV: 978-633-5364
Deepwoods Software        -- Custom Software Services
http://www.deepsoft.com/  -- Linux Administration Services
heller@deepsoft.com       -- Webhosting Services