| Ticket UUID: | 7be97a685975ec271a02518a0d88c6bc121f8df6 | |||
| Title: | Reviewing chan.n changes | |||
| Type: | Bug | Version: | 8.7 | |
| Submitter: | jan.nijtmans | Created on: | 2024-06-19 12:02:42 | |
| Subsystem: | - New Builtin Commands | Assigned To: | jan.nijtmans | |
| Priority: | 5 Medium | Severity: | Minor | |
| Status: | Closed | Last Modified: | 2024-06-20 02:20:36 | |
| Resolution: | Fixed | Closed By: | apnadkarni | |
| Closed on: | 2024-06-20 02:20:36 | |||
| Description: |
In [eb627bda27|this] commit, an extensive rewrite was done on the chan.n manpage. The most important problem in this commit is that "channelId" was renamed to "channelName". However, "channelName" isn't used in any other man-page, "channelId" is. So, if this is a good change, it should be done in all related man-pages too. Otherwise consistancy is lost. My second critisism is that doc-changes which are not made due to a new feature should have a good commit message, describing why the commit was done. For example: [d664748a86b7b8b5|this] is a good example. "Rewrite of documentation for [chan]" is not a good commit message. Third, why was the rewrite not backported to 8.6? Since 8.6 is the current release, documentation improvements are valueable there too. However, I agree that "channelId" is not the best name what we are refering too. It suggests forms like "file1234" or "sock4321", which - indeed - look like id's. But "stderr" and "stdout" look more like channel names. In Tcl scripts, channels can have both forms, there is no need to distinguis betwen them. So, I propose to resolve this possible confusion by using simply "channel" everywhere. Since in Tcl, 'everything is a string', "channel" is an appropriate name for what we are dealing with here. See: here for the implementation of this proposed change. | |||
| User Comments: |
apnadkarni added on 2024-06-20 02:20:36:
I understood this is about script level, but the analogy still holds. Whether in C, or Tcl or any other language, there is a distinction between a name and the "object" that it identifies. A process "object" is identified by its PID, a file is identified by its name/path, and a stream returned by open by its file descriptor. My view is the same is true of Tcl channels. The channel itself is a programming construct for I/O built on top of files, sockets, pipes or whatever. What the open or socket commands return is a reference to this construct in the form of an identifier or name. If we were to have a Now an opposite view might be, that the word "channel" is in fact the reference to the I/O construct and not the construct itself. Perhaps that is your position. Plausible but would not really fit when we talk about "pushing a transform on to a channel". In any case, as I said in most cases the distinction is immaterial as semantics are clear from context but if we ever get around to clearly documenting the nouns and verbs as Don suggested, that distinction should be maintained. jan.nijtmans added on 2024-06-19 19:55:21: I hope I made it sufficiently clear that this ticket is only about the documentation at *script* level, not the lower-level file-descriptor or whatever the actual implementation is. That's the context. apnadkarni added on 2024-06-19 17:37:35: As an editorial comment, if something is proposed and opinions sought, it would behoove waiting at least 24 hours before committing :-) Particularly for matters that are not urgent. apnadkarni added on 2024-06-19 17:33:29: While I agree with the rest of dgp's comments, I do think it is important to distinguish between the channel and a "token" that identifies it, whether we call it a channel name or channel id. This is analogous to files and file descriptors, or perhaps more appropriately, Sys V streams, which might be the closest functionally to channels. A Sys V stream or a Tcl channel is a programming construct that transports data (some hand waving here) and supports operations like read/write and transforms. The channel name/id is something used to identify an instance of such a construct. The two are not the same, and there need not even be a 1-1 relation between them. Consider if we had the equivalent of dup() in Tcl. We would then still have a single channel, as our data transfer construct, but now we have two identifiers/names for it. Calling close on the channel name would not terminate the channel, but the identifier would no longer reference it. In Windows terms, what we are currently calling a channel id/name would be a channel handle. In Unix terms, it would be akin to a file descriptor. In any case the point is the channel is distinct from whatever is used to identify it, whether that is id, name, handle or descriptor. Having said that I think when the context is obvious it would be all right to use "channel" as a synonym for the identifier if it reads better. jan.nijtmans added on 2024-06-19 16:40:55: Thanks! Committed to core-8-branch and trunk now. Ready for Tcl 9.0b3! oehhar added on 2024-06-19 16:29:24: Don Porter commented on the core list: Agree that “channel” is the best choice. I think that in general, identifiers that indicate a category are best, without anything additional to indicate implementation details. Anti-Hungarian, so to speak. Simple, plain nouns preferred, though that’s got some judgment and taste to it. Getting a good set of nouns in the interface and documentation helps a lot as a foundation for other writing about the interface and its use. As already said, consistency helps build a larger coherent body of descriptions of the language command set. In time, some of these nouns might gain their own man pages, where important matters that cross over many interfaces can be gathered. As an example, several commands and public routines take or return a return code. Soon return codes will have documented reserved ranges, and it would be good to have one place to present that information. Tcl documentation is big, and it may take a while to turn the whole ship in an improved direction. That’s ok. oehhar added on 2024-06-19 13:19:08: I like the "channel" solution. It is IMHO conformant to the style of the manual. A string parameter is typically flagged as "string". Thank you for all, Harald | |||
Home
Timeline
Branches
Tags
Tickets
Download
Wiki