Tcl Source Code

Logged In: YES 
user_id=75003

Committed to head.

File Added - 10616: doc.diff.5

Logged In: YES 
user_id=75003

Another update of the patch. Integrated feedback from 
Christopher Nelson.

Logged In: YES 
user_id=75003

See also BR #219250.

Logged In: YES 
user_id=75003

Ad 1) Yes, I guess so.
Ad 2) Maybe not. OTOH the whole content is specific to Tcl.
Ad 3) tclMacChan.c seems to initialize fairly normal
      standard channels.
Ad 4) Ok.
Fixed (1) and (4) locally now. Unsure about (2).

Logged In: YES 
user_id=79902

A few points with the new manual page:

1) Should the first argument to .TH be quoted?
2) There is no Tcl_StandardChannels() function, you know, so
   is putting a Tcl_ prefix on it a good idea..?
3) What happens on the Mac?  Is the behaviour of tclsh not
   an issue there (in the non-OSX world, of course.)
4) Capitalisation of tclsh and wish (toward end in .SH args)
   is inconsistent.

File Added - 10076: doc.diff.4

Logged In: YES 
user_id=75003

3rd revision. Should be final

File Added - 10064: doc.diff.3

Logged In: YES 
user_id=75003

2nd revision.

File Added - 10058: doc.diff.2

Logged In: YES 
user_id=75003

Added revised enhanced patch. Separate manpage for general 
explanations of behaviour + small docs in the individual 
pages and references to the new page.

Logged In: YES 
user_id=75003

"Tcl_SetStdChannel() also performs the initialization" ...
Right. I missed that.

"Every call to Tcl_RegisterChannel() in a non-safe
interp will call Tcl_GetStdChannel". Not quite 
true. "Tcl_RegisterChannel" calls "GetChannelTable" and 
that one does initialize the StdChannels, but only on the 
first call, if there is no channel table.

In the end it amounts to the same thing and there you are 
right. It is the Tcl library which does the initialization, 
if the application doesn't :)

Surprising ways of initialization: See
http://sourceforge.net/tracker/?
func=detail&aid=419685&group_id=10894&atid=110894

for a bug report about such. 'Fixing' this bug
influences the documentation too. Windows of
course. Not wish. Tclsh as a NT service.

With all this it might be easier to write a new manpage 
talking about standard channels and then to reference that 
from the various other manpages.

Logged In: YES 
user_id=80530

That covers the bases pretty well.  I had missed
the detail that Tcl_CreateChannel() only fills
NULL standard channels that have previously been
initialized.

A few places you say this initialization must be
done by a call to Tcl_GetStdChannel(), but
Tcl_SetStdChannel() also performs the initialization.

Another problem is that these changes suggest that
standard channel initialization with a
Tcl_{Get|Set}StdChannel() call can only be done
by the application.  The example is Tcl_Main's
initialization in tclsh.  But that is not true.
Every call to Tcl_RegisterChannel() in a non-safe
interp will call Tcl_GetStdChannel for all three
standard channels, so it you have any channel at
all registered in an interp, you will have the 
standard channels.  Also every use of the one of
the names std* where a channel name is expected
will cause a call to Tcl_GetStdChannel for that
channel, initializing it if needed.  There are
other places too.  The application can't prevent
it.  That's why the std* channels are a feature
of the Tcl library, not only the application tclsh.

Given that Tcl will initialize the std channels as
needed (in possibly surprising ways via Tcl_CreateChannel),
we need to advise application writers that
they need to initialize them themselves, or risk Tcl
making a bad choice for them.

A related matter in Tk is where to document
the mess that is standard channels for wish on
Windows.

File Added - 9955: doc.diff

Logged In: YES 
user_id=75003

Enclosed an updated patch (doc.diff) to the documentation.

Logged In: YES 
user_id=75003

"It is not tclsh that creates the standard channels.  The 
Tcl library itself creates them as needed, no matter what 
application the Tcl library has been linked into."

Notes about this: The part initializing the standard 
channels is "Tcl_Main" in TclMain.c. This is physically
part of the tcl library, but logically it is "tclsh",
because it also does all the interactive stuff. In that
respect it is tclsh which initializes the standard
channels.

And any application not using Tcl_Main will have to 
initialize the channels by itself, through a call 
to "Tcl_GetStdChannel". Note: If the application never
initializes the standard channels, "Tcl_CreateChannel"
won't fill these slots either.

So I will accept the patch as is and have a look at the
manpages for Tcl_CreateChannel and Tcl_GetStdChannel if
they need additional explanations too.

Logged In: YES 
user_id=80530

The attached patch contains only parts that
have not been committed to CVS, due to disagreement
about the proper place to document Tcl's
standard channel handles.

Logged In: YES 
user_id=75003

Don, is the attached patch the remaining patch
or the full patch, partially applied ?

If it is the full patch: Can you separate out the
parts which were not applied yet ?

Logged In: YES 
user_id=80530

Remaining patch deals with Tcl channels.  Changing Category.

File Deleted - 2329: 



File Added - 9306: tclsh.patch

Logged In: YES 
user_id=80530

Committed the non-controversial part of the patch.

Reworded summary to describe the rest.

If you only care to have the standard channels listed in some docs somewhere, then the C API docs have a few places that would be appropriate.  CrtChannel.3 really seems like the most appropriate place, because you could additionally note the fact that if one of the standard channels are closed, then the next opened (created) channel will become a standard channel.  This occurs in Tcl_CreateChannel, BTW.

I know, but I've wracked my brains and can't think of where else to put the added information (which is needed, somewhere.)  It doesn't belong in open(n),socket(n), fconfigure(n), puts(n), read(n), gets(n), etc. and not really in Tcl(n) either.  It is also way too short for its own manual page.  (All of which goes to explain why it has fallen between stools and ended up undocumented, to the deprivation of the Tcl docs as a whole.)  Putting it in tclsh(1) isn't perfect but at least it means that it is documented somewhere, and somewhere that is reasonably logical to someone coming to Tcl cold.

The version number comments are good, but I don't think
the standard channels belong here.  It is not tclsh that
creates the standard channels.  The Tcl library itself
creates them as needed, no matter what application the
Tcl library has been linked into.

Discusses fact that tclsh is usually installed with a version number, and what the standard channels are.  Also adds some xrefs.