Tcl/Tk man pages comments page

started by Theo Verelst

Manual page discussions are (temporarily ?) stored here, at least by me for the moment, maybe this can be a transient page, or at least one which gets emptied with the next release.

binary

Large number of options, I didn't go over all the option examples, even though they're important. Bottom example:

 EXAMPLES
       This  is  a procedure write a Tcl string to a binary-encoded channel as
       UTF-8 data preceded by a length word: proc writeString {channel string}
       {
           set data [encoding convertto utf-8 $string]
           puts -nonewline [binary format Ia* \
                   [string length $data] $data] }

       This  procedure  reads  a string from a channel that was written by the
       previously presented writeString procedure: proc readString {channel} {
           if {![binary scan [read $channel 4] I length]} {
               error "missing length"
           }
           set data [read $channel $length]
           return [encoding convertfrom utf-8 $data] }

Formatting issue.

Interesting.

Mind that a non-blocking read of 4 can stall your whole program in case of error...

dict

oops a command I don't know about.

Mm, I'd need to know about the concept of a dict, I can't really find a neutral explanation for that on the page.

LV Will the docs for dict be improved to the point that someone can learn to use the command, before 8.5 is released?

I'd guess this is the format that could appear in the example, in my MAN they are all messed up:

 EXAMPLE
       A localizable version of string toupper: 
       # Set up the  basic  C  locale
       set  capital  [dict  create  C  [dict  create]]
       foreach  c {abcdefghijklmnopqrstuvwxyz} {
           dict set capital C $c [string toupper $c] 
       }

       # English locales can luckily share the "C" locale
       dict set capital  en [dict get $capital C]
       dict set capital en_US [dict get $capital C]
       dict set capital en_GB [dict get $capital C]

       # ... and so on for other supported languages ...

       # Now get the mapping for the current locale and use  it.
       set  upperCaseMap  [dict  get  $capital  $env(LANG)]
       set  upperCase  [string map $upperCaseMap $string]

Lars H: I don't really understand the purpose of this example. Is string toupper not Unicode-aware? (Checking.) Seems to work perfectly fine! Without an example of how the above maps are supposed to be used it is hard to say for sure, but it seems to me as though the main effect would be that the en, en_US, en_GB, etc. "locales" would fail to case-convert all non-ASCII letters, which is very wrong.

A correct localised (to handle the unusual mappings in e.g. Turkish) case converter should probably only have a string map for the nonstandard mappings, and then apply string toupper to convert all other letters.

Also, I suspect it is a bad idea to make much use of the C language locale concept in Tcl. Tcl is waaaay better than C at almost all things text-related, so what is a solution designed for C need not be a good solution for Tcl.

Tcl_GetEncoding(3)

Veeery long argument list.

examples in my (cygwin) man appear as:

       typedef   struct  Tcl_EncodingType  {       CONST  char  *encodingName;
            Tcl_EncodingConvertProc  *toUtfProc;       Tcl_EncodingConvertProc
       *fromUtfProc;        Tcl_EncodingFreeProc   *freeProc;       ClientData
       clientData;      int nullSize; } Tcl_EncodingType;

...

eof

ok, understandable, -recordsize I didn't know. First line of example source code isn't on a new line.

tclsh

I didn't see the environment variables mentioned which are used for instance to find index.tcl.

Lars H: One thing I dislike with the Tk man pages is that their tables of contents are far too detailed. Most of them do for example contain a large chunk of "standard options"; since these aren't explained in that page anyway, they should rather be placed as a section in the body of the page. Many of the other long enumerations of things don't belong in a table of contents either.

The man pages (especially the long ones) should however begin with (contain in the first screen) a short abstract that explains what the command is all about. In the Tcl man pages, there are one-liners after the Name heading which serve well as abstracts, e.g.

after

Execute a command after a time delay

but their conterparts in the Tk man pages are generally less informative

canvas

Create and manipulate canvas widgets

This is entirely true, but anyone who understands the explanation probably knew this already. An abstract would have to say something on the lines of

Canvas widgets implement structured graphics. A canvas displays any number of items, which may be things like rectangles, circles, lines, and text. Items may be manipulated (e.g. moved or re-colored) and commands may be associated with items in much the same way that the bind command allows commands to be bound to widgets.

-- information that can be found in that page, but only quite a long way down.