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