last day (49 days later) » 

3:48 PM
Ka-aw
 
4:20 PM
Chirp
Well, I guess it works.
 
Did you see Vasili's (?) comment on the introduction topic?
 
Yes. Actually, I do agree that the example (new command) didn't really fit in under the introduction.
 
I can understand that. I feel that the introduction should show off the strengths of the language. I've also run into so many language introductions that tell me nothing other than some very basic syntax, and that's just not useful.
I know my remarks section is too terse and is not very good at all. Sometimes I write well, other times not so good.
 
I understand your thinking, but if someone takes a first look and understands nothing of the code, the example doesn't really show off any strengths. Maybe there should be a point list of features instead, with a "see this example" or something. -- I'm hopeless at writing comments myself. I'm used to coding for my own eyes.
 
4:38 PM
A point list of features would be good with links to the other topics (if that's possible). Since stackoverflow's design is less than desirable, we could make it better by adding many links to the manual pages and to the other topics.
Also part of the problem is there are multiple audiences: beginners and the electronics design people who know next to nothing of the language. And other people who know computer languages and need to look into Tcl.
 
Yep. I suppose we need to write for the beginners and less knowing: others can simply ask questions.
How about we create a "Control Structures" topic and put the "Adding a new command to Tcl" to it? Maybe rename it "... new control structure..."?
 
That sounds like it would be the best plan. I think most of the topics so far work out pretty well. Have to think on what the problem areas people always run into. Probably need a section explaining why and when the $ should be used in commands (e.g. lappend mylist ... vs. llength $mylist). This can be confusing at first. array is confusing here as it has different rules.
--
Sounds good. Then we can also add examples on for/foreach/while/etc in that topic.
 
The name / $name rules trip up many beginners. It's wonderfully intuitive once you get it, but I remember struggling for a long time before I got it. I am currently looking through my list of answers for problems that seem to deserve documentation.
 
4:58 PM
The file * operations should be a topic. Everyone seems to miss those. Probably string operations also -- I don't know those well.
 
You're on Linux, right? Have you seen the way the commands are ordered into categories in the Windows help file?
 
No, I've never looked at the windows help file.
 
I'll copy the category "String Handling". My point is that a "Strings" topic could be for more than just the string ensemble.
String Handling
append - Append to variable
binary - Insert and extract fields from binary strings
encoding - Manipulate encodings
format - Format a string in the style of sprintf
prefix - facilities for prefix matching
re_syntax - Syntax of Tcl regular expressions
regexp - Match a regular expression against a string
regsub - Perform substitutions based on regular expression pattern matching
scan - Parse string using conversion specifiers in the style of sscanf
string - Manipulate strings
subst - Perform backslash, command, and variable substitutions
 
Yes, that would be good. I often wish the manual page "contents" would be set up the same way.
 
5:16 PM
Of course, we can't have examples for every command under a single topic, but we could start by putting examples that involve any of these commands under the Strings header (unless the example obviously belongs to another topic and incidentally involves string commands). If we get too many examples we could perhaps have "Strings 2" etc.
 
The regexp stuff can probably go into its own topic. We can move things around as we need to.
 
Well, regexp problems are very common and deserve their own topic as such, but it will be hard to find good examples. There are so many ways to fail, and so many different kinds of strings to match and extract from, so it's unlikely that the examples we provide will be generally useful.
 
I'm good at regular expressions. I can help with that. People nowadays make their regex's way too complicated.
 
5:37 PM
Yes, but even if we can answer questions well, the set of questions will be so diverse that only a few will be helped directly by examples. Still, there ARE age-old recurring problems that we can make examples of, such as the engine sticking to the first choice of greedy/non-greedy.
 
Yes, we can just come up with the classic examples. The greedy/non-greedy thing is funky. I don't understand why it was a problem, but Mr. Spencer said he tried to solve it and could not, so I suppose there's something there I'm missing.
 
So, Strings is one topic, and "Regular Expressions" is a separate topic, then?
 
I think so. And I think the file * commands, there are a lot of questions that file tail, file rootname, etc. solve. Of course this may go into some other topic.
 
In the Windows help file, the file ensemble is put together with the chan * commands and their non-ensemble counterparts, and also zlib and the docs for refchan and transchan. I think that category makes sense too.
 
6:06 PM
file tail / file rootname etc. could go into the strings topic, since they are specialized string manipulation. People might look there first. We can add "see also" links pointing to other parts of the documentation.
 
We should have a "plan" file with ideas and guidelines like we have been discussing now. It would be good to have the others' opinions too.
 
dkf reads c.l.t, don't know about the others. Need to get them in here.
 
6:22 PM
If we have a "plan" file, maybe it should go on the Tcl'ers Wiki. A list of guidelines and some links (to here, for instance), and space for discussions. I don't really like going back to the wiki, but this could be worth it.
 
Well, you only will need to the visit the one wiki page. Just don't get sucked into following other links. And it will be a discussion/plan/outline page, so you can set your expectations appropriately.
Urk...the wiki has a captcha now to create a new page and I can't get past the captcha.
 
6:46 PM
I haven't put anything on it yet, I thought you might like to have the first go.
 
Yeah..working on it.
 
7:08 PM
Ok, made a first pass.
 
7:21 PM
Looks good, but I'd put the links before the discussion: those discussion patches can get really long. I'll look at it again tomorrow and add some sentences of my own. Right now the bed is calling me.
 
7:32 PM
Right, thank you for a productive discussion. Take care. Night.
 

  last day (49 days later) »