diff options
| -rw-r--r-- | ChangeLog | 5 | ||||
| -rw-r--r-- | doc/chan.n | 10 | ||||
| -rw-r--r-- | doc/refchan.n | 68 |
3 files changed, 44 insertions, 39 deletions
@@ -1,3 +1,8 @@ +2006-05-23 Donal K. Fellows <donal.k.fellows@manchester.ac.uk> + + * doc/chan.n, doc/refchan.n: Tighten up the documentation to follow a + slightly more consistent style with regard to argument capitalization. + 2006-05-13 Don Porter <dgp@users.sourceforge.net> * generic/tclProc.c (ProcCompileProc): When a bump of the compile @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: chan.n,v 1.3 2006/03/17 17:24:10 andreas_kupries Exp $ +'\" RCS: @(#) $Id: chan.n,v 1.4 2006/05/23 15:35:02 dkf Exp $ .so man.macros .TH chan n 8.5 Tcl "Tcl Built-In Commands" .BS @@ -493,11 +493,11 @@ Produces a list of all channel names. If \fIpattern\fR is specified, only those channel names that match it (according to the rules of \fBstring match\fR) will be returned. .TP -\fBchan postevent \fIchannel eventspec\fR +\fBchan postevent \fIchannelId eventSpec\fR . This subcommand is used by command handlers specified with \fBchan create\fR. It notifies the channel represented by the handle -\fIchannel\fR that the event(s) listed in the \fIeventspec\fR have +\fIchannelId\fR that the event(s) listed in the \fIeventSpec\fR have occurred. The argument has to be a list containing any of the strings "\fBread\fR" and "\fBwrite\fR". The list must contain at least one element as it does not make sense to invoke the command if there are @@ -606,12 +606,12 @@ most serial ports are comparatively slow; it is entirely possible to get a \fBreadable\fR event for each character read from them. Care must be taken when using \fBchan read\fR on blocking serial ports: .TP -\fBchan read \fIchannelId numChars\fR +\fBchan read \fIchannelId numChars\fR . In this form \fBchan read\fR blocks until \fInumChars\fR have been received from the serial port. .TP -\fBchan read \fIchannelId\fR +\fBchan read \fIchannelId\fR . In this form \fBchan read\fR blocks until the reception of the end-of-file character, see \fBchan configure -eofchar\fR. If there no diff --git a/doc/refchan.n b/doc/refchan.n index 1f08d40..e39ed51 100644 --- a/doc/refchan.n +++ b/doc/refchan.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: refchan.n,v 1.2 2006/04/12 02:35:07 das Exp $ +'\" RCS: @(#) $Id: refchan.n,v 1.3 2006/05/23 15:35:02 dkf Exp $ .so man.macros .TH reflectedchan n 8.5 Tcl "Tcl Built-In Commands" .BS @@ -30,10 +30,10 @@ Of all the possible subcommands, the handler \fImust\fR support other subcommands is optional. .SS "MANDATORY SUBCOMMANDS" .TP -\fIcmdPrefix \fBinitialize \fIchannel mode\fR +\fIcmdPrefix \fBinitialize \fIchannelId mode\fR . An invokation of this subcommand will be the first call the -\fIcmdPrefix\fR will receive for the specified new \fBchannel\fR. It +\fIcmdPrefix\fR will receive for the specified new \fIchannelId\fR. It is the responsibility of this subcommand to set up any internal data structures required to keep track of the channel and its state. .RS @@ -60,13 +60,13 @@ The subcommand must throw an error if the chosen mode is not supported by the \fIcmdPrefix\fR. .RE .TP -\fIcmdPrefix \fBfinalize \fIchannel\fR +\fIcmdPrefix \fBfinalize \fIchannelId\fR . An invokation of this subcommand will be the last call the -\fIcmdPrefix\fR will receive for the specified \fIchannel\fR. It will +\fIcmdPrefix\fR will receive for the specified \fIchannelId\fR. It will be generated just before the destruction of the data structures of the channel held by the Tcl core. The command handler \fImust not\fR -access the \fIchannel\fR anymore in no way. Upon this subcommand being +access the \fIchannelId\fR anymore in no way. Upon this subcommand being called, any internal resources allocated to this channel must be cleaned up. .RS @@ -82,10 +82,10 @@ This subcommand is not invoked if the creation of the channel was aborted during \fBinitialize\fR (See above). .RE .TP -\fIcmdPrefix \fBwatch \fIchannel eventspec\fR +\fIcmdPrefix \fBwatch \fIchannelId eventspec\fR . This subcommand notifies the \fIcmdPrefix\fR that the specified -\fIchannel\fR is interested in the events listed in the +\fIchannelId\fR is interested in the events listed in the \fIeventspec\fR. This argument is a list containing any of "\fBread\fR" and "\fBwrite\fR". The list may be empty, which signals that the channel does not wish to be notified of any events. In that situation, @@ -102,12 +102,12 @@ event which was not listed in the last call to \fBwatch\fR will cause .RE .SS "OPTIONAL SUBCOMMANDS" .TP -\fIcmdPrefix \fBread \fIchannel count\fR +\fIcmdPrefix \fBread \fIchannelId count\fR . -This \fIoptional\fR subcommand is called when the user requests data -from a channel. \fIcount\fR specifies how many \fBbytes\fR have been -requested. If the subcommand is not supported then it is not possible -to read from the channel handled by the command. +This \fIoptional\fR subcommand is called when the user requests data from the +channel \fIchannelId\fR. \fIcount\fR specifies how many \fBbytes\fR have been +requested. If the subcommand is not supported then it is not possible to read +from the channel handled by the command. .RS .PP The return value of this subcommand is taken as the requested data @@ -122,10 +122,10 @@ thrown this error. Any exception beyond \fIerror\fR, (e.g. \fIbreak\fR, etc.) is treated as and converted to an error. .RE .TP -\fIcmdPrefix \fBwrite \fIchannel data\fR +\fIcmdPrefix \fBwrite \fIchannelId data\fR . This \fIoptional\fR subcommand is called when the user writes data to -the channel. The \fIdata\fR argument contains \fIbytes\fR, not +the channel \fIchannelId\fR. The \fIdata\fR argument contains \fIbytes\fR, not characters. Any type of transformation (EOL, encoding) configured for the channel has already been applied at this point. If this subcommand is not supported then it is not possible to write to the channel @@ -145,10 +145,10 @@ Any exception beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is treated as and converted to an error. .RE .TP -\fIcmdPrefix \fBseek \fIchannel offset base\fR +\fIcmdPrefix \fBseek \fIchannelId offset base\fR . This \fIoptional\fR subcommand is responsible for the handling of -\fBseek\fR and \fBtell\fR requests on the channel. If it is not +\fBseek\fR and \fBtell\fR requests on the channel \fIchannelId\fR. If it is not supported then seeking will not be possible for the channel. .RS .PP @@ -190,11 +190,11 @@ request, i.e. seek nothing relative to the current location, making the new location identical to the current one, which is then returned. .RE .TP -\fIcmdPrefix \fBconfigure \fIchannel option value\fR +\fIcmdPrefix \fBconfigure \fIchannelId option value\fR . -This \fIoptional\fR subcommand is for writing the type specific -options. The \fIoption\fR argument indicates the option to be written, -and the \fIvalue\fR argument indicates the value to set the option to. +This \fIoptional\fR subcommand is for setting the type-specific options of +channel \fIchannelId\fR. The \fIoption\fR argument indicates the option to be +written, and the \fIvalue\fR argument indicates the value to set the option to. .RS .PP This subcommand will never try to update more than one option at a @@ -209,11 +209,11 @@ beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is treated as and converted to an error. .RE .TP -\fIcmdPrefix \fBcget \fIchannel option\fR +\fIcmdPrefix \fBcget \fIchannelId option\fR . -This \fIoptional\fR subcommand is used when reading a single type -specific option. If this subcommand is supported then the subcommand -\fBcgetall\fR must be supported as well. +This \fIoptional\fR subcommand is used when reading a single type-specific +option of channel \fIchannelId\fR. If this subcommand is supported then the +subcommand \fBcgetall\fR must be supported as well. .RS .PP The subcommand should return the value of the specified \fIoption\fR. @@ -224,11 +224,11 @@ have thrown this error. Any exception beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is treated as and converted to an error. .RE .TP -\fIcmdPrefix \fBcgetall \fIchannel\fR +\fIcmdPrefix \fBcgetall \fIchannelId\fR . -This \fIoptional\fR subcommand is used for reading all type specific -options. If this subcommand is supported then the subcommand -\fBcget\fR has to be supported as well. +This \fIoptional\fR subcommand is used for reading all type-specific options +of channel \fIchannelId\fr. If this subcommand is supported then the +subcommand \fBcget\fR has to be supported as well. .RS .PP The subcommand should return a list of all options and their values. @@ -240,12 +240,12 @@ have thrown this error. Any exception beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is treated as and converted to an error. .RE .TP -\fIcmdPrefix \fBblocking \fIchannel mode\fR +\fIcmdPrefix \fBblocking \fIchannelId mode\fR . -This \fIoptional\fR subcommand handles changes to the blocking mode of -the channel. The \fImode\fR is a boolean flag. A true value means that -the channel has to be set to blocking, and a false value means that -the channel should be non-blocking. +This \fIoptional\fR subcommand handles changes to the blocking mode of the +channel \fIchannelId\fR. The \fImode\fR is a boolean flag. A true value means +that the channel has to be set to blocking, and a false value means that the +channel should be non-blocking. .RS .PP The return value of the subcommand is ignored. |