**Tcl Documentation on Stackoverflow**

This page is for discussion and planning of the Stackoverflow documentation.
http://stackoverflow.com/documentation/tcl/topics%|%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.

   * '''Expressions'''
   * '''String Operations'''
   ** 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'''
   ** file
   ** chan
   ** fconfigure
   ** zlib
   * '''Lists'''   Lists are very useful things.  Need good examples on why.

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***

http://stackoverflow.com/questions/tagged/tcl%|%Tcl tag on Stackoverflow%|%

http://stackoverflow.com/questions/tagged/tk%|%Tk tag on Stackoverflow%|%

http://stackoverflow.com/documentation/tcl/topics%|%Stackoverflow Tcl Documentation%|%

http://chat.stackoverflow.com/rooms/118649/tcl-documentation-discussion%|%Tcl Documentation Chat room on Stackoverflow%|%

**Discussion**

[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.  

[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.
<<br>>
[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.

<<discussion>>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.
<<discussion>>

<<categories>>Documentation