Backport of documentation fixes

1 files changed, 28 insertions, 4 deletions

diff --git a/doc/focus.n b/doc/focus.n
index bcc11e1..b7107bb 100644
--- a/doc/focus.n
+++ b/doc/focus.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: focus.n,v 1.2 1998/09/14 18:22:56 stanton Exp $
+'\" RCS: @(#) $Id: focus.n,v 1.2.26.1 2004/10/28 10:19:29 dkf Exp $
 '\" 
 .so man.macros
 .TH focus n 4.0 Tk "Tk Built-In Commands"
@@ -14,11 +14,11 @@
 .SH NAME
 focus \- Manage the input focus
 .SH SYNOPSIS
+.nf
 \fBfocus\fR
-.sp
 \fBfocus \fIwindow\fR
-.sp
 \fBfocus \fIoption\fR ?\fIarg arg ...\fR?
+.fi
 .BE
 
 .SH DESCRIPTION
@@ -97,7 +97,6 @@ if the most recent focus window has been deleted, then the name
 of the top-level is returned.  The return value is the window that
 will receive the input focus the next time the window manager gives
 the focus to the top-level.
-
 .SH "QUIRKS"
 .PP
 When an internal window receives the input focus, Tk doesn't actually
@@ -108,6 +107,31 @@ focus were on the internal window.   This approach gets around a
 number of problems that would occur if the X focus were actually moved;
 the fact that the X focus is on the top-level is invisible unless
 you use C code to query the X server directly.
+.SH "EXAMPLE"
+To make a window that only participates in the focus traversal ring
+when a variable is set, add the following bindings to the widgets
+\fIbefore\fR and \fIafter\fR it in that focus ring:
+.CS
+button .before -text "Before"
+button .middle -text "Middle"
+button .after  -text "After"
+checkbutton .flag -variable traverseToMiddle -takefocus 0
+pack .flag -side left
+pack .before .middle .after
+bind .before <Tab> {
+   if {!$traverseToMiddle} {
+      \fBfocus\fR .after
+      break
+   }
+}
+bind .after <Shift-Tab> {
+   if {!$traverseToMiddle} {
+      \fBfocus\fR .before
+      break
+   }
+}
+\fBfocus\fR .before
+.CE
 
 .SH KEYWORDS
 events, focus, keyboard, top-level, window manager