- 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.
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.nFiles 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.nThese 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.nThe 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 examplesFirstly, 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.nFiles 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.nEstimated 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
.CEI 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
