Tcl Source Code

some spelling and corrections to the docs of the Tcl C-
functions
See attached file (patch).

Affected files:
tclvars.n, tcltest.n, WrongNumArgs.3, Utf.3, TraceVar.3, 
TCL_MEM_DEBUG.3, StdChannels.3, CrtChannel.3, 
ChnlStack.3, RegExp.3, RegConfig.3, SubstObj.3, 
RecordEval.3, RecEvalObj.3, Environment.3, 
ParseCmd.3, SetResult.3 , Panic.3 , StringObj.3, 
ObjectType.3, Object.3, IntObj.3, DoubleObj.3, 
DictObj.3, ByteArrObj.3, Interp.3, PrintDbl.3, Hash.3, 
GetOpnFl.3, GetIndex.3, Encoding.3, Eval.3, 
CrtTimerHdlr.3, CrtObjCmd.3, CrtMathFnc.3, 
CrtCommand.3, Thread.3, Namespace.3, Alloc.3, 
tclsh.1, safe.n, expr.n, AssocData.3

corrections to one or two files will come a bit later

should the NAME section's definition be on a single line?
most of files (even with very long NAMEs - CrtChannel.3) 
follow this rule

shouldn't the NAME section's definition contain 
no 'highlight' tags?
or tags in NAMEs are acceptable (like in 
Tcl_StaticPackage and pkg::create)

Logged In: YES 
user_id=80530

backport candidate?

Logged In: YES 
user_id=79902

OK, accepted most of those fixes (one or two weren't quite
right, but I can't remember which ones).

New Ruling On Documentation: All symbols like TCL_OK,
TCL_ERROR, etc. (i.e. starting with TCL_ and defined in
tcl.h) must be in bold in non-plaintext documentation. (e.g.
surrounded by \fB and \fR in nroff docs.)

Logged In: YES 
user_id=79902

Reopening until I assess whether this bug has been fully
resolved :/

File Deleted - 101113:

File Added - 101114: docs_tcl_C-fun1.patch

Logged In: YES 
user_id=119429

spelling and formatting patch for 2 files
FileSystem.3, OpenFileChnl.3

FileSystem.3 :
"There are several reasons for calling the Tcl_FS... functions 
rather than calling system level functions like access and stat 
directly. "
"The Tcl_FS... are objectified and may cache internal 
representations and other path-related strings"

The notation "Tcl_FS..." sounds "Tcl_FS and others" ("and so 
on")
and "..." is a punctuation symbol!
I'd suggest using instead
a)"Tcl_FS*" (i.e. Tcl_FSWhatever)
in the docs this 'pattern' is already used f.e. for the 
Tcl_SetVar functions - Tcl_Set*
At least on Windows platform it is an ubiquitous regexp

b) Or let's use a term "Tcl_FS API" that is used somewhere 
in the man page
TclFS is nicer but crosses with extfs, reiserfs, xfs etc. (i.e. 
real FSs' names, not APIs)

Standart return codes (TCL_OK, TCL_ERROR etc.) (not-)
highlighting
f.e. TCL_OK is highlighted in 57 lines throughout the docs
and not highlighted in 56 lines throughout the docs (about 8 of 
them are in FileSystem.3)

File Added - 101113: docs_tcl_C-fun1.patch

Logged In: YES 
user_id=119429

spelling and formatting patch for 2 files
FileSystem.3, OpenFileChnl.3

FileSystem.3 :
"There are several reasons for calling the Tcl_FS... functions 
rather than calling system level functions like access and stat 
directly. "
"The Tcl_FS... are objectified and may cache internal 
representations and other path-related strings"

The notation "Tcl_FS..." sounds "Tcl_FS and others" ("and so 
on")
and "..." is a punctuation symbol!
I'd suggest using instead
a)"Tcl_FS*" (i.e. Tcl_FSWhatever)
in the docs this 'pattern' is already used f.e. for the 
Tcl_SetVar functions - Tcl_Set*
At least on Windows platform it is an ubiquitous regexp

b) Or let's use a term "Tcl_FS API" that is used somewhere 
in the man page
TclFS is nicer but crosses with extfs, reiserfs, xfs etc. (i.e. 
real FSs' names, not APIs)

Standart return codes (TCL_OK, TCL_ERROR etc.) (not-)
highlighting
f.e. TCL_OK is highlighted in 57 lines throughout the docs
and not highlighted in 56 lines throughout the docs (about 8 of 
them are in FileSystem.3)

Logged In: YES 
user_id=79902

Fixed, and thanks.

(Please do a 'cvs update' before you submit your next patch;
this one included a number of things which I caught last
week... ;^)

Logged In: YES 
user_id=79902

NAME sections must be on a single line so the manual page
indexing works (this scheme wasn't invented by us). NAME
sections on multiple lines or containing highlighting are
reportable bugs.

File Added - 100377: docs_tcl_C-func.patch