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