Updated 2016-08-04 20:12:54 by bll

Tcl Documentation on Stackoverflow edit

This page is for discussion and planning of the Stackoverflow documentation. Stackoverflow Tcl Documentation

Even if you don't use Stackoverflow, please feel free to add your comments.

bll 2016-7-29: Stackoverflow has added a documentation section that be associated with a tag on Stackoverflow. It is organized as a series of topics with a multitude of examples within each topic. The examples can include both text and code.

There are also syntax, parameters and remarks sections. The remarks section is free-form, so anything can go there. The parameters section expects some particular format, so it doesn't seem to be useful. The syntax section expects a list of one-liners.

Plan

Our audience is likely to be varied: 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. We need to help the first kind get started, and the second kind to "get" Tcl.

The Introduction Topic

Unless people are following a link to a certain example, this topic is likely to be the first one they look at. It should be a well-written topic that arouses interest in the language. There should be a list that enumerates the language's strengths. Each point should be brief, but could link to somewhere where the feature is described in more depth.

Topics and examples

We don't want too many examples. Stackoverflow Documentation's layout is optimized for small numbers of examples.

  • Introduction to Tcl Needs a complete rewrite (todo)
    • Applications using Tcl (todo)
      • Any applications listed here should be current and supported.
    • Companies using Tcl (todo)
      • EDI companies, NBC NOC, who else?
  • Procedure Arguments
  • Expressions
    • integer and real operations and how they mix (todo)
  • Dictionaries (started, could use some more examples)
  • String Operations (todo)
    • string useful/common string manipulation
    • format
    • scan
    • file tail
    • file rootname (and the other useful file operations that are specialized string commands)
  • Regular Expressions
  • File Operations (todo)
    • file
    • chan
    • fconfigure
    • zlib
  • Lists Lists are very useful things. Need good examples on why. (todo)
  • Variables
  • Tcl Language Constructs Various parts of the Tcl Language (started)
    • explain why and when the $ should be used in commands (e.g. lappend mylist ... vs. llength $mylist). (todo)
    • explain why array is an exception to the above, explain its rules (todo)
    • Best Practices (todo)
      • use of global variables - multiple globals vs. a single array with good index names.
  • Control Structures

Make sure all topics and examples have links to the manual pages and cross reference links to other relevant stackoverflow documentation.

For manual page links, remove the version number from the link so that it points at the current version:

Before: http://tcl.tk/man/tcl8.6/TclCmd/lrepeat.htm

After: http://tcl.tk/man/tcl/TclCmd/lrepeat.htm

Links

Tcl tag on Stackoverflow

Tk tag on Stackoverflow

Stackoverflow Tcl Documentation

Tcl Documentation Chat room on Stackoverflow

Discussion edit

bll 2016-7-29: Obviously we don't want to re-create the manual pages, but we can add discussion and examples of common usage, common questions and common problems.

At this time, there are five or six people who have signed up to work on the Stackoverflow documentation. Not enough people have signed up to start the Tk documentation on Stackoverflow.

It just got started so don't expect too much :-). The introduction topic sucks.

bll 2016-7-29: I don't know if it's better to put the links to manual pages in the topic level (remarks section), example level, or both.

2016-07-30: A warning: people contributing to this Stackoverflow documentation project should keep in mind that the published material (including the code) is released under the CC-BY-SA license. This means that the code cannot directly be used in a proprietary-licensed software.

Peter Lewerin 2016-07-31: Thank you for pointing that out. For my part, I somehow assumed that any license that applied would be some kind of documentation license that actually allowed people to use the information without too much hassle, but I'm a fool for not looking it up. Here are the basic terms of the license: [1] (the full license is linked to). Can anyone confirm or deny that the snippets we post in the documentation are are "works" in the sense of the license?

[same Anon]: 2016-7-31: Yes, you'd imagined that the license would allow any kind of use (BSD-like or even MIT). There have been discussions on changing the license for code snippets on StackOverflow (you can find a number of them on meta), and at some point it was even announced that all code posted after March 1st, 2016 would be under MIT license. Unfortunately, the date came and passed, there was no change and nowadays not even a discussion is happening any more. I am not sure what you expect to your question for confirmation or denial; but I can offer the single data point that in my company of tens of thousands of developers it is definitely not allowed to introduce code from StackOverflow into our products -- and I know because Open Source Compliance is my day job...

bll 2016-7-31: I guess we could bypass their licensing by explicitly putting everything on stackoverflow in the public domain. A little one-liner license above every code snippet.

DKF 2016-Aug-01: For the samples I'm putting up (when I have time), they're written explicitly for the purpose; I'm utterly unbothered about the licensing issues. (My day job is more about Java anyway, with irritatingly little Tcl.)

 Control Structures / New (resolved)


Peter Lewerin 2016-07-30: alternative code suggestion for the Control Structures do command:
proc do {body keyword expression} {
    uplevel 1 $body
    switch $keyword {
        while {tailcall while $expression $body}
        until {tailcall while !($expression) $body}
        default {
            return -code error "unknown keyword \"$keyword\": must be until or while"
        }
    }
}

bll 2016-7-30: I don't understand why $expression works w/o the uplevel here. I tried this code w/a local variable and it works. This is much harder to understand.
DKF: It's all about context of evaluation. $expression itself is being evaluated in the context of the do, but the contents of it are evaluated in the caller's context.
bll 2016-7-31: Read the tailcall page. I understand better. Now I want to draw a picture (and I'm not a visual thinker) of how this works.

Digression However, I'd be tempted to use this for the until clause:
tailcall while !\[[list expr $expression]\] $body

This is because of the differences when someone uses a (malformed!) expression like 1+2)*(3+4; by not relying on simple wrapping, such unpleasantness becomes guaranteed to generate an error. Indeed, the wrapping I propose has no weaknesses to any such approach. Though I probably wouldn't do tailcall while in the first place.

Second attempt: is it more readable with uplevel than with tailcall? Point about malformed expressions noted, but it's possibly too subtle for this example.
proc do {body keyword expression} {
    uplevel 1 $body
    switch $keyword {
        while {uplevel 1 [list while $expression $body]}
        until {uplevel 1 [list while !($expression) $body]}
        default {
            return -code error "unknown keyword \"$keyword\": must be until or while"
        }
    }
}