examples needed

davidw: It would be nice to see at least a simple example included for all Tcl man pages (or at the very least point to another page including an example).

DKF 30 May 2004: I now consider this project effectively over w.r.t Tcl. Here is an analysis of the files not listed below as having examples:

Tcl.n: Does not need them IMHO.
case.n: This feature is likely to be deleted in a future release of Tcl.
filename.n: Does not document a Tcl command.
history.n: Only really useful interactively. Best way for people to use it is to just try it out!
library.n: Assorted misc. features.
memory.n: Feature for advanced users only (requires non-standard build of Tcl.)
msgcat.n: Full of examples to the extent that an EXAMPLES section would not do it justice.
packagens.n: Does not document a Tcl command.
pkgMkIndex.n: For package creators only.
re_syntax.n: This is second-level documentation for other manual pages.
safe.n: This is really second-level documentation for the interp.n page.
tcltest.n: Full of examples to the extent that an EXAMPLES section would not do it justice.
tclvars.n: Assorted misc. features.

Of course, if someone wants to prove me wrong by filling in examples for the above files, they should feel free. :^D

Here is the current state of things for Tcl:

Files with examples:

 after.n     eof.n         gets.n     load.n       regexp.n    time.n
 append.n    error.n       glob.n     lrange.n     registry.n  trace.n
 array.n     eval.n        global.n   lrepeat.n    regsub.n    unknown.n
 bgerror.n   exec.n        http.n     lreplace.n   rename.n    unload.n
 binary.n    exit.n        if.n       lsearch.n    return.n    unset.n
 break.n     expr.n        incr.n     lset.n*      scan.n      update.n
 catch.n     fblocked.n    info.n     lsort.n      seek.n      uplevel.n
 cd.n        fconfigure.n  interp.n   namespace.n  set.n       upvar.n
 clock.n     fcopy.n       join.n     open.n       socket.n    variable.n
 close.n     file.n        lappend.n  package.n    source.n    vwait.n
 concat.n    fileevent.n   lassign.n  pid.n        split.n     while.n
 continue.n  flush.n       lindex.n   proc.n       string.n
 dde.n       for.n         linsert.n  puts.n       subst.n
 dict.n      foreach.n     list.n     pwd.n        switch.n
 encoding.n  format.n      llength.n  read.n       tell.n

Files without examples:

 Tcl.n   filename.n  library.n  msgcat.n     pkgMkIndex.n  safe.n     tclvars.n
 case.n  history.n   memory.n   packagens.n  re_syntax.n   tcltest.n

These are automatically generated (script below). Some of these do have examples, such as msgcat and tcltest. Others sort of do, but a functional bit of code that runs and demonstrates the command is always welcome.

Exception List: The list of files that really do have (good) examples: msgcat.n tcltest.n.

The above is really confusing - msgcat.n and tcltest.n are listed as files that really do have ... examples as well as in the list of files without examples. Shouldn't someone remove them from one of the two lists?

and the list of files that describe commands that are too simple to really need examples (or that have them elsewhere): cd.n close.n

The following files probably don't need an example: Tcl.n, case.n, filename.n, library.n, packagens.n, re_syntax.n, tclvars.n (and perhaps safe.n too)

Tk examples

Firstly, currently Tk widgets are excluded from the list, as they are demonstrated through the widget demo instead. There are also several files that do not have proper code content.

Files with examples

 bind.n             console.n  font.n         option.n      popup.n      wm.n
 bindtags.n         destroy.n  getOpenFile.n  optionMenu.n  raise.n
 chooseColor.n      dialog.n   grab.n         pack.n        selection.n
 chooseDirectory.n  event.n    grid.n         photo.n       send.n
 clipboard.n        focus.n    messageBox.n   place.n       winfo.n

Files without examples

 bell.n         entry.n       listbox.n     options.n      spinbox.n
 bitmap.n       focusNext.n   loadTk.n      pack-old.n     text.n
 button.n       frame.n       lower.n       palette.n      tk.n
 canvas.n       image.n       menu.n        panedwindow.n  tkerror.n
 checkbutton.n  keysyms.n     menubar.n     radiobutton.n  tkvars.n
 colors.n       label.n       menubutton.n  scale.n        tkwait.n
 cursors.n      labelframe.n  message.n     scrollbar.n    toplevel.n

Estimated to do... bell,bitmap,focusNext,image,loadTk,lower,palette,tk,tkerror,tkvars,tkwait

Adding an example doesn't take much time, and lots are already available on the wiki. All you have to do is submit a patch to sourceforge. The man page markup looks like this:

 .SH "EXAMPLES"

 A time server:

 .CS
 proc Server { channel clientaddr clientport } {
     puts "Connection from $clientaddr registered"
     puts $channel [clock format [clock seconds]]
     close $channel
 }

 socket -server Server 9900
 vwait forever
 .CE

I used this code to check:

 package require fileutil
 package require struct

 foreach res [fileutil::grep ".SH.*EXAMPLE" [glob *.n]] {
     lappend examplefiles [lindex [split $res :] 0]
 }
 set examplefiles [lsort $examplefiles]

 set allfiles [lsort [glob *.n]]
 set noexamplefiles [lsort [struct::set difference $allfiles $examplefiles]]

 puts "Files with examples: $examplefiles"
 puts ""
 puts "Files without examples: $noexamplefiles"

DKF: Remember that some Tk docs need examples as well, though I'd tend to say not the widgets, as they're better demonstrated as part of the general widget demo.

AM What about Wiki pages that show a particular package in action? I mention it here because it seems a nice starting place for it ... For instance:

the http package is nicely illustrated with the page on the wiki-reaper
A little Unicode editor might serve as an illustration for dealing with Unicode

DKF: I'm trying to keep examples very short. Both of those pages are several times too long for my current limit.

Category Documentation

Category Example