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).
Here is the current state of things:
Files with examples:
after.n exec.n http.n llength.n lset.n* return.n array.n fcopy.n lappend.n lrange.n lsort.n socket.n bgerror.n fileevent.n lassign.n lrepeat.n open.n subst.n catch.n foreach.n lindex.n lreplace.n puts.n switch.n encoding.n gets.n linsert.n lsearch.n read.n
Files without examples:
Tcl.n eof.n glob.n msgcat.n rename.n trace.n append.n error.n global.n namespace.n safe.n unknown.n binary.n eval.n history.n package.n scan.n unload.n break.n exit.n if.n packagens.n seek.n unset.n case.n expr.n incr.n pid.n set.n update.n cd.n fblocked.n info.n pkgMkIndex.n source.n uplevel.n clock.n fconfigure.n interp.n proc.n split.n upvar.n close.n file.n join.n pwd.n string.n variable.n concat.n filename.n library.n re_syntax.n tcltest.n vwait.n continue.n flush.n list.n regexp.n tclvars.n while.n dde.n for.n load.n registry.n tell.n dict.n format.n memory.n regsub.n time.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: binary.n msgcat.n tcltest.n.
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
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"