From 2fbb36cdb77e640aa7cd11eddf6d19a7ac5c4490 Mon Sep 17 00:00:00 2001 From: dgp Date: Fri, 18 Jul 2003 16:56:41 +0000 Subject: * doc/AddErrInfo.3: Improved consistency of documentation * doc/CrtTrace.3: by using "null" everywhere to refer to * doc/Encoding.3: the character '\0', and using "NULL" * doc/Eval.3: everywhere to refer to the value of a * doc/GetIndex.3: pointer that points to nowhere. * doc/Hash.3: Also dropped references to ASCII that * doc/LinkVar.3: are no longer true, and standardized on * doc/Macintosh.3: the hyphenated spelling of "null-terminated". * doc/OpenFileChnl.3: * doc/SetVar.3: * doc/StringObj.3: * doc/Utf.3: --- ChangeLog | 13 +++++++++++++ doc/AddErrInfo.3 | 4 ++-- doc/CrtTrace.3 | 4 ++-- doc/Encoding.3 | 6 +++--- doc/Eval.3 | 4 ++-- doc/GetIndex.3 | 6 +++--- doc/Hash.3 | 4 ++-- doc/LinkVar.3 | 6 +++--- doc/Macintosh.3 | 4 ++-- doc/OpenFileChnl.3 | 8 ++++---- doc/SetVar.3 | 4 ++-- doc/StringObj.3 | 4 ++-- doc/Utf.3 | 24 ++++++++++++------------ 13 files changed, 52 insertions(+), 39 deletions(-) diff --git a/ChangeLog b/ChangeLog index 9ea6018..9cc80b8 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,18 @@ 2003-07-18 Don Porter + * doc/AddErrInfo.3: Improved consistency of documentation + * doc/CrtTrace.3: by using "null" everywhere to refer to + * doc/Encoding.3: the character '\0', and using "NULL" + * doc/Eval.3: everywhere to refer to the value of a + * doc/GetIndex.3: pointer that points to nowhere. + * doc/Hash.3: Also dropped references to ASCII that + * doc/LinkVar.3: are no longer true, and standardized on + * doc/Macintosh.3: the hyphenated spelling of "null-terminated". + * doc/OpenFileChnl.3: + * doc/SetVar.3: + * doc/StringObj.3: + * doc/Utf.3: + * doc/CrtSlave.3 (Tcl_MakeSafe): Removed warning about possible deprecation (no TIP on that). diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 index 06fe195..e1a05b7 100644 --- a/doc/AddErrInfo.3 +++ b/doc/AddErrInfo.3 @@ -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: AddErrInfo.3,v 1.8 2002/07/01 18:24:38 jenglish Exp $ +'\" RCS: @(#) $Id: AddErrInfo.3,v 1.9 2003/07/18 16:56:41 dgp Exp $ '\" .so man.macros .TH Tcl_AddErrorInfo 3 8.0 Tcl "Tcl Library Procedures" @@ -60,7 +60,7 @@ Pointer to first character in script containing command (must be <= command) .AP "CONST char" *command in Pointer to first character in command that generated the error .AP int commandLength in -Number of bytes in command; -1 means use all bytes up to first NULL byte +Number of bytes in command; -1 means use all bytes up to first null byte .BE .SH DESCRIPTION diff --git a/doc/CrtTrace.3 b/doc/CrtTrace.3 index 17a688d..7495682 100644 --- a/doc/CrtTrace.3 +++ b/doc/CrtTrace.3 @@ -6,7 +6,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: CrtTrace.3,v 1.6 2002/08/05 03:24:39 dgp Exp $ +'\" RCS: @(#) $Id: CrtTrace.3,v 1.7 2003/07/18 16:56:41 dgp Exp $ '\" .so man.macros .TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures" @@ -47,7 +47,7 @@ details on the calling sequence. Arbitrary one-word value to pass to \fIobjProc\fR or \fIproc\fR. .AP Tcl_CmdObjTraceDeleteProc *deleteProc Procedure to call when the trace is deleted. See below for details of -the calling sequence. A null pointer is permissible and results in no +the calling sequence. A NULL pointer is permissible and results in no callback when the trace is deleted. .AP Tcl_Trace trace in Token for trace to be removed (return value from previous call diff --git a/doc/Encoding.3 b/doc/Encoding.3 index a4fc94f..7d505aa 100644 --- a/doc/Encoding.3 +++ b/doc/Encoding.3 @@ -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: Encoding.3,v 1.12 2003/05/23 00:35:29 patthoyts Exp $ +'\" RCS: @(#) $Id: Encoding.3,v 1.13 2003/07/18 16:56:41 dgp Exp $ '\" .so man.macros .TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures" @@ -174,7 +174,7 @@ and delete it from the database. .PP \fBTcl_ExternalToUtfDString\fR converts a source buffer \fIsrc\fR from the specified \fIencoding\fR into UTF-8. The converted bytes are stored in -\fIdstPtr\fR, which is then NULL terminated. The caller should eventually +\fIdstPtr\fR, which is then null-terminated. The caller should eventually call \fBTcl_DStringFree\fR to free any information stored in \fIdstPtr\fR. When converting, if any of the characters in the source buffer cannot be represented in the target encoding, a default fallback character will be @@ -212,7 +212,7 @@ the target encoding and TCL_ENCODING_STOPONERROR was specified. \fBTcl_UtfToExternalDString\fR converts a source buffer \fIsrc\fR from UTF-8 into the specified \fIencoding\fR. The converted bytes are stored in \fIdstPtr\fR, which is then terminated with the appropriate encoding-specific -NULL. The caller should eventually call \fBTcl_DStringFree\fR to free any +null. The caller should eventually call \fBTcl_DStringFree\fR to free any information stored in \fIdstPtr\fR. When converting, if any of the characters in the source buffer cannot be represented in the target encoding, a default fallback character will be used. The return value is diff --git a/doc/Eval.3 b/doc/Eval.3 index 82b96b9..60ce66c 100644 --- a/doc/Eval.3 +++ b/doc/Eval.3 @@ -6,7 +6,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Eval.3,v 1.14 2003/05/12 17:44:28 dgp Exp $ +'\" RCS: @(#) $Id: Eval.3,v 1.15 2003/07/18 16:56:41 dgp Exp $ '\" .so man.macros .TH Tcl_Eval 3 8.1 Tcl "Tcl Library Procedures" @@ -67,7 +67,7 @@ The number of bytes in \fIscript\fR, not including any null terminating character. If \-1, then all characters up to the first null byte are used. .AP "CONST char" *script in -Points to first byte of script to execute (NULL terminated and UTF-8). +Points to first byte of script to execute (null-terminated and UTF-8). .AP char *string in String forming part of a Tcl script. .AP va_list argList in diff --git a/doc/GetIndex.3 b/doc/GetIndex.3 index 8ac4975..724fe34 100644 --- a/doc/GetIndex.3 +++ b/doc/GetIndex.3 @@ -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: GetIndex.3,v 1.10 2002/02/28 05:11:25 dgp Exp $ +'\" RCS: @(#) $Id: GetIndex.3,v 1.11 2003/07/18 16:56:41 dgp Exp $ '\" .so man.macros .TH Tcl_GetIndexFromObj 3 8.1 Tcl "Tcl Library Procedures" @@ -34,11 +34,11 @@ The string value of this object is used to search through \fItablePtr\fR. The internal representation is modified to hold the index of the matching table entry. .AP "CONST char" **tablePtr in -An array of null-terminated ASCII strings. The end of the array is marked +An array of null-terminated strings. The end of the array is marked by a NULL string pointer. .AP "CONST VOID" *structTablePtr in An array of arbitrary type, typically some \fBstruct\fP type. -The first member of the structure must be a null-terminated ASCII string. +The first member of the structure must be a null-terminated string. The size of the structure is given by \fIoffset\fP. .VS .AP int offset in diff --git a/doc/Hash.3 b/doc/Hash.3 index 664756a..3d3e955 100644 --- a/doc/Hash.3 +++ b/doc/Hash.3 @@ -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: Hash.3,v 1.10 2002/07/11 15:40:19 dgp Exp $ +'\" RCS: @(#) $Id: Hash.3,v 1.11 2003/07/18 16:56:41 dgp Exp $ '\" .so man.macros .TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures" @@ -119,7 +119,7 @@ caller, not by the hash module. The value of \fIkeyType\fR indicates what kinds of keys will be used for all entries in the table. \fIKeyType\fR must have one of the following values: .IP \fBTCL_STRING_KEYS\fR 25 -Keys are null-terminated ASCII strings. +Keys are null-terminated strings. They are passed to hashing routines using the address of the first character of the string. .IP \fBTCL_ONE_WORD_KEYS\fR 25 diff --git a/doc/LinkVar.3 b/doc/LinkVar.3 index c344b5e..300482a 100644 --- a/doc/LinkVar.3 +++ b/doc/LinkVar.3 @@ -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: LinkVar.3,v 1.6 2002/08/05 03:24:39 dgp Exp $ +'\" RCS: @(#) $Id: LinkVar.3,v 1.7 2003/07/18 16:56:41 dgp Exp $ '\" .so man.macros .TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures" @@ -95,13 +95,13 @@ Tcl errors. \fBTCL_LINK_STRING\fR The C variable is of type \fBchar *\fR. .VS -If its value is not null then it must be a pointer to a string +If its value is not NULL then it must be a pointer to a string allocated with \fBTcl_Alloc\fR or \fBckalloc\fR. .VE Whenever the Tcl variable is modified the current C string will be freed and new memory will be allocated to hold a copy of the variable's new value. -If the C variable contains a null pointer then the Tcl variable +If the C variable contains a NULL pointer then the Tcl variable will read as ``NULL''. .PP If the TCL_LINK_READ_ONLY flag is present in \fItype\fR then the diff --git a/doc/Macintosh.3 b/doc/Macintosh.3 index f8a7ee5..8bedd30 100644 --- a/doc/Macintosh.3 +++ b/doc/Macintosh.3 @@ -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: Macintosh.3,v 1.4 2002/01/25 20:40:55 dgp Exp $ +'\" RCS: @(#) $Id: Macintosh.3,v 1.5 2003/07/18 16:56:41 dgp Exp $ '\" .so man.macros .TH Tcl_MacSetEventProc 3 "8.1" Tcl "Tcl Library Procedures" @@ -79,7 +79,7 @@ at a later date. .PP \fBTcl_MacConvertTextResource\fR converts a TEXT resource into a Tcl suitable string. It mallocs the returned memory, converts ``\\r'' to -``\\n'', and appends a NULL. The caller has the responsibility for +``\\n'', and appends a null. The caller has the responsibility for freeing the memory. .PP \fBTcl_MacFindResource\fR provides a higher level interface for diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3 index 9fe8136..e099526 100644 --- a/doc/OpenFileChnl.3 +++ b/doc/OpenFileChnl.3 @@ -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: OpenFileChnl.3,v 1.20 2002/07/23 18:17:12 jenglish Exp $ +'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.21 2003/07/18 16:56:41 dgp Exp $ .so man.macros .TH Tcl_OpenFileChannel 3 8.3 Tcl "Tcl Library Procedures" .BS @@ -468,7 +468,7 @@ and exists for backwards compatibility with non-internationalized Tcl extensions. It consumes bytes from \fIchannel\fR and stores them in \fIreadBuf\fR, performing end-of-line translations on the way. The return value of \fBTcl_Read\fR is the number of bytes, up to \fIbytesToRead\fR, written in -\fIreadBuf\fR. The buffer produced by \fBTcl_Read\fR is not NULL terminated. +\fIreadBuf\fR. The buffer produced by \fBTcl_Read\fR is not null-terminated. Its contents are valid from the zeroth position up to and excluding the position indicated by the return value. .PP @@ -524,7 +524,7 @@ added to the input queue. \fBTcl_Ungets\fR returns \fIinputLen\fR or \fIcharBuf\fR. The UTF-8 characters in the buffer are converted to the channel's encoding and queued for output to \fIchannel\fR. If \fIbytesToWrite\fR is negative, \fBTcl_WriteChars\fR expects \fIcharBuf\fR -to be NULL terminated and it outputs everything up to the NULL. +to be null-terminated and it outputs everything up to the null. .PP Data queued for output may not appear on the output device immediately, due to internal buffering. If the data should appear immediately, call @@ -562,7 +562,7 @@ deprecated and exists for backwards compatibility with non-internationalized Tcl extensions. It accepts \fIbytesToWrite\fR bytes of data at \fIbyteBuf\fR and queues them for output to \fIchannel\fR. If \fIbytesToWrite\fR is negative, \fBTcl_Write\fR expects \fIbyteBuf\fR to be -NULL terminated and it outputs everything up to the NULL. +null-terminated and it outputs everything up to the null. .PP \fBTcl_WriteRaw\fR is the same as \fBTcl_Write\fR but does not compensate for stacking. While \fBTcl_Write\fR (and the other diff --git a/doc/SetVar.3 b/doc/SetVar.3 index f39725e..90b140b 100644 --- a/doc/SetVar.3 +++ b/doc/SetVar.3 @@ -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: SetVar.3,v 1.7 2002/08/05 03:24:39 dgp Exp $ +'\" RCS: @(#) $Id: SetVar.3,v 1.8 2003/07/18 16:56:41 dgp Exp $ '\" .so man.macros .TH Tcl_SetVar 3 8.1 Tcl "Tcl Library Procedures" @@ -76,7 +76,7 @@ to specify a variable in a particular namespace. May refer to a scalar variable or an element of an array. .AP "CONST char" *newValue in -New value for variable, specified as a NULL-terminated string. +New value for variable, specified as a null-terminated string. A copy of this value is stored in the variable. .AP Tcl_Obj *part1Ptr in Points to a Tcl object containing the variable's name. diff --git a/doc/StringObj.3 b/doc/StringObj.3 index 8d43dc6..6ed15b6 100644 --- a/doc/StringObj.3 +++ b/doc/StringObj.3 @@ -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: StringObj.3,v 1.13 2002/10/22 12:16:53 dkf Exp $ +'\" RCS: @(#) $Id: StringObj.3,v 1.14 2003/07/18 16:56:41 dgp Exp $ '\" .so man.macros .TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures" @@ -118,7 +118,7 @@ An argument list which must have been initialised using \fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR. .AP int newLength in New length for the string value of \fIobjPtr\fR, not including the -final NULL character. +final null character. .AP int objc in The number of elements to concatenate. .AP Tcl_Obj *objv[] in diff --git a/doc/Utf.3 b/doc/Utf.3 index 8384412..9b1b44e 100644 --- a/doc/Utf.3 +++ b/doc/Utf.3 @@ -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: Utf.3,v 1.13 2002/07/01 18:24:39 jenglish Exp $ +'\" RCS: @(#) $Id: Utf.3,v 1.14 2003/07/18 16:56:41 dgp Exp $ '\" .so man.macros .TH Utf 3 "8.1" Tcl "Tcl Library Procedures" @@ -93,9 +93,9 @@ Filled with the Tcl_UniChar represented by the head of the UTF-8 string. .AP "CONST char" *src in Pointer to a UTF-8 string. .AP "CONST Tcl_UniChar" *uniStr in -A NULL-terminated Unicode string. +A null-terminated Unicode string. .AP "CONST Tcl_UniChar" *uniPattern in -A NULL-terminated Unicode string. +A null-terminated Unicode string. .AP int len in The length of the UTF-8 string in bytes (not UTF-8 characters). If negative, all bytes up to the first null byte are used. @@ -143,7 +143,7 @@ and stores it as a Tcl_UniChar in \fI*chPtr\fR. The return value is the number of bytes read from \fIsrc\fR.. The caller must ensure that the source buffer is long enough such that this routine does not run off the end and dereference non-existent or random memory; if the source buffer -is known to be null terminated, this will not happen. If the input is +is known to be null-terminated, this will not happen. If the input is not in proper UTF-8 format, \fBTcl_UtfToUniChar\fR will store the first byte of \fIsrc\fR in \fI*chPtr\fR as a Tcl_UniChar between 0x0000 and 0x00ff and return 1. @@ -162,15 +162,15 @@ in which case \fBTcl_UtfToUniCharDString\fR uses \fBstrlen\fR to calculate the length. The return value is a pointer to the Unicode representation of the UTF-8 string. Storage for the return value is appended to the end of the \fBTcl_DString\fR. The Unicode string -is terminated with a Unicode NULL character. +is terminated with a Unicode null character. .PP \fBTcl_UniCharLen\fR corresponds to \fBstrlen\fR for Unicode -characters. It accepts a NULL-terminated Unicode string and returns +characters. It accepts a null-terminated Unicode string and returns the number of Unicode characters (not bytes) in that string. .PP \fBTcl_UniCharNcmp\fR and \fBTcl_UniCharNcasecmp\fR correspond to \fBstrncmp\fR and \fBstrncasecmp\fR, respectively, for Unicode characters. -They accepts two NULL-terminated Unicode strings and the number of characters +They accepts two null-terminated Unicode strings and the number of characters to compare. Both strings are assumed to be at least \fIlen\fR characters long. \fBTcl_UniCharNcmp\fR compares the two strings character-by-character according to the Unicode character ordering. It returns an integer greater @@ -180,13 +180,13 @@ is the Unicode case insensitive version. .PP .VS 8.4 \fBTcl_UniCharCaseMatch\fR is the Unicode equivalent to -\fBTcl_StringCaseMatch\fR. It accepts a NULL-terminated Unicode string, +\fBTcl_StringCaseMatch\fR. It accepts a null-terminated Unicode string, a Unicode pattern, and a boolean value specifying whether the match should be case sensitive and returns whether the string matches the pattern. .VE 8.4 .PP \fBTcl_UtfNcmp\fR corresponds to \fBstrncmp\fR for UTF-8 strings. It -accepts two NULL-terminated UTF-8 strings and the number of characters +accepts two null-terminated UTF-8 strings and the number of characters to compare. (Both strings are assumed to be at least \fIlen\fR characters long.) \fBTcl_UtfNcmp\fR compares the two strings character-by-character according to the Unicode character ordering. @@ -209,16 +209,16 @@ full Tcl_UniChar has been seen. \fBTcl_NumUtfChars\fR corresponds to \fBstrlen\fR for UTF-8 strings. It returns the number of Tcl_UniChars that are represented by the UTF-8 string \fIsrc\fR. The length of the source string is \fIlen\fR bytes. If the -length is negative, all bytes up to the first NULL byte are used. +length is negative, all bytes up to the first null byte are used. .PP \fBTcl_UtfFindFirst\fR corresponds to \fBstrchr\fR for UTF-8 strings. It returns a pointer to the first occurrence of the Tcl_UniChar \fIch\fR -in the NULL-terminated UTF-8 string \fIsrc\fR. The NULL terminator is +in the null-terminated UTF-8 string \fIsrc\fR. The null terminator is considered part of the UTF-8 string. .PP \fBTcl_UtfFindLast\fR corresponds to \fBstrrchr\fR for UTF-8 strings. It returns a pointer to the last occurrence of the Tcl_UniChar \fIch\fR -in the NULL terminated UTF-8 string \fIsrc\fR. The NULL terminator is +in the null-terminated UTF-8 string \fIsrc\fR. The null terminator is considered part of the UTF-8 string. .PP Given \fIsrc\fR, a pointer to some location in a UTF-8 string, -- cgit v0.12