First stage of doing GOOBE improvements to documentation now that the html generation works

1 files changed, 86 insertions, 86 deletions

diff --git a/doc/DoWhenIdle.3 b/doc/DoWhenIdle.3
index 90a6aa7..239878e 100644
--- a/doc/DoWhenIdle.3
+++ b/doc/DoWhenIdle.3
@@ -1,86 +1,86 @@
-'\"
-'\" Copyright (c) 1990 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-'\" RCS: @(#) $Id: DoWhenIdle.3,v 1.2 1998/09/14 18:39:48 stanton Exp $
-'\" 
-.so man.macros
-.TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures"
-.BS
-.SH NAME
-Tcl_DoWhenIdle, Tcl_CancelIdleCall \- invoke a procedure when there are no pending events
-.SH SYNOPSIS
-.nf
-\fB#include <tcl.h>\fR
-.sp
-\fBTcl_DoWhenIdle\fR(\fIproc, clientData\fR)
-.sp
-\fBTcl_CancelIdleCall\fR(\fIproc, clientData\fR)
-.SH ARGUMENTS
-.AS Tcl_IdleProc clientData
-.AP Tcl_IdleProc *proc in
-Procedure to invoke.
-.AP ClientData clientData in
-Arbitrary one-word value to pass to \fIproc\fR.
-.BE
-
-.SH DESCRIPTION
-.PP
-\fBTcl_DoWhenIdle\fR arranges for \fIproc\fR to be invoked
-when the application becomes idle.  The application is
-considered to be idle when \fBTcl_DoOneEvent\fR has been
-called, couldn't find any events to handle, and is about
-to go to sleep waiting for an event to occur.  At this
-point all pending \fBTcl_DoWhenIdle\fR handlers are
-invoked.  For each call to \fBTcl_DoWhenIdle\fR there will
-be a single call to \fIproc\fR;  after \fIproc\fR is
-invoked the handler is automatically removed.
-\fBTcl_DoWhenIdle\fR is only usable in programs that
-use \fBTcl_DoOneEvent\fR to dispatch events.
-.PP
-\fIProc\fR should have arguments and result that match the
-type \fBTcl_IdleProc\fR:
-.CS
-typedef void Tcl_IdleProc(ClientData \fIclientData\fR);
-.CE
-The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR
-argument given to \fBTcl_DoWhenIdle\fR.  Typically, \fIclientData\fR
-points to a data structure containing application-specific information about
-what \fIproc\fR should do.
-.PP
-\fBTcl_CancelIdleCall\fR
-may be used to cancel one or more previous
-calls to \fBTcl_DoWhenIdle\fR:  if there is a \fBTcl_DoWhenIdle\fR
-handler registered for \fIproc\fR and \fIclientData\fR, then it
-is removed without invoking it.  If there is more than one
-handler on the idle list that refers to \fIproc\fR and \fIclientData\fR,
-all of the handlers are removed.  If no existing handlers match
-\fIproc\fR and \fIclientData\fR then nothing happens.
-.PP
-\fBTcl_DoWhenIdle\fR is most useful in situations where
-(a) a piece of work will have to be done but (b) it's
-possible that something will happen in the near future
-that will change what has to be done or require something
-different to be done.  \fBTcl_DoWhenIdle\fR allows the
-actual work to be deferred until all pending events have
-been processed.  At this point the exact work to be done
-will presumably be known and it can be done exactly once.
-.PP
-For example, \fBTcl_DoWhenIdle\fR might be used by an editor
-to defer display updates until all pending commands have
-been processed.  Without this feature, redundant redisplays
-might occur in some situations, such as the processing of
-a command file.
-.SH BUGS
-.PP
-At present it is not safe for an idle callback to reschedule itself
-continuously.  This will interact badly with certain features of Tk
-that attempt to wait for all idle callbacks to complete.  If you would
-like for an idle callback to reschedule itself continuously, it is
-better to use a timer handler with a zero timeout period.
-
-.SH KEYWORDS
-callback, defer, idle callback
+'\"

+'\" Copyright (c) 1990 The Regents of the University of California.

+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.

+'\"

+'\" See the file "license.terms" for information on usage and redistribution

+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.

+'\" 

+'\" RCS: @(#) $Id: DoWhenIdle.3,v 1.3 2007/10/28 14:17:38 dkf Exp $

+'\" 

+.so man.macros

+.TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures"

+.BS

+.SH NAME

+Tcl_DoWhenIdle, Tcl_CancelIdleCall \- invoke a procedure when there are no pending events

+.SH SYNOPSIS

+.nf

+\fB#include <tcl.h>\fR

+.sp

+\fBTcl_DoWhenIdle\fR(\fIproc, clientData\fR)

+.sp

+\fBTcl_CancelIdleCall\fR(\fIproc, clientData\fR)

+.SH ARGUMENTS

+.AS Tcl_IdleProc clientData

+.AP Tcl_IdleProc *proc in

+Procedure to invoke.

+.AP ClientData clientData in

+Arbitrary one-word value to pass to \fIproc\fR.

+.BE

+

+.SH DESCRIPTION

+.PP

+\fBTcl_DoWhenIdle\fR arranges for \fIproc\fR to be invoked

+when the application becomes idle.  The application is

+considered to be idle when \fBTcl_DoOneEvent\fR has been

+called, could not find any events to handle, and is about

+to go to sleep waiting for an event to occur.  At this

+point all pending \fBTcl_DoWhenIdle\fR handlers are

+invoked.  For each call to \fBTcl_DoWhenIdle\fR there will

+be a single call to \fIproc\fR;  after \fIproc\fR is

+invoked the handler is automatically removed.

+\fBTcl_DoWhenIdle\fR is only usable in programs that

+use \fBTcl_DoOneEvent\fR to dispatch events.

+.PP

+\fIProc\fR should have arguments and result that match the

+type \fBTcl_IdleProc\fR:

+.CS

+typedef void Tcl_IdleProc(ClientData \fIclientData\fR);

+.CE

+The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR

+argument given to \fBTcl_DoWhenIdle\fR.  Typically, \fIclientData\fR

+points to a data structure containing application-specific information about

+what \fIproc\fR should do.

+.PP

+\fBTcl_CancelIdleCall\fR

+may be used to cancel one or more previous

+calls to \fBTcl_DoWhenIdle\fR:  if there is a \fBTcl_DoWhenIdle\fR

+handler registered for \fIproc\fR and \fIclientData\fR, then it

+is removed without invoking it.  If there is more than one

+handler on the idle list that refers to \fIproc\fR and \fIclientData\fR,

+all of the handlers are removed.  If no existing handlers match

+\fIproc\fR and \fIclientData\fR then nothing happens.

+.PP

+\fBTcl_DoWhenIdle\fR is most useful in situations where

+(a) a piece of work will have to be done but (b) it is

+possible that something will happen in the near future

+that will change what has to be done or require something

+different to be done.  \fBTcl_DoWhenIdle\fR allows the

+actual work to be deferred until all pending events have

+been processed.  At this point the exact work to be done

+will presumably be known and it can be done exactly once.

+.PP

+For example, \fBTcl_DoWhenIdle\fR might be used by an editor

+to defer display updates until all pending commands have

+been processed.  Without this feature, redundant redisplays

+might occur in some situations, such as the processing of

+a command file.

+.SH BUGS

+.PP

+At present it is not safe for an idle callback to reschedule itself

+continuously.  This will interact badly with certain features of Tk

+that attempt to wait for all idle callbacks to complete.  If you would

+like for an idle callback to reschedule itself continuously, it is

+better to use a timer handler with a zero timeout period.

+

+.SH KEYWORDS

+callback, defer, idle callback