The final parts of my doc improvement project

13 files changed, 61 insertions, 24 deletions

diff --git a/ChangeLog b/ChangeLog
index 0d6b8f0..e97bb11 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2011-07-19  Donal K. Fellows  <dkf@users.sf.net>
+
+	* doc/*.3, doc/*.n: Many small fixes to documentation as part of
+	project to improve quality of generated HTML docs.
+
+	* tools/tcltk-man2html.tcl (remap_link_target): More complete set of
+	definitions of link targets, especially for major C API types.
+	* tools/tcltk-man2html-utils.tcl (output-IP-list, cross-reference):
+	Update to generation to produce proper HTML bulleted and enumerated
+	lists.
+
 2011-07-19 Alexandre Ferrieux  <ferrieux@users.sourceforge.net>
 
 	* doc/upvar.n: Undocument long gone limitation of [upvar].
@@ -7,9 +18,9 @@
 	* generic/tclCompile.c: Avoid segfaults when RecordByteCodeStats()
 	is called in a deleted interp.
 
-	* generic/tclCompile.c:	[Bug 467523, 3357771] Prevent circular
+	* generic/tclCompile.c:	[Bug 467523, 3357771]: Prevent circular
 	references in values with ByteCode intreps.  They can lead to
-	memory leaks. 
+	memory leaks.
 
 2011-07-14  Donal K. Fellows  <dkf@users.sf.net>
 
diff --git a/doc/Class.3 b/doc/Class.3
index e9bb21c..dbb5b99 100644
--- a/doc/Class.3
+++ b/doc/Class.3
@@ -9,7 +9,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_ClassGetMetadata, Tcl_ClassSetMetadata, Tcl_CopyObjectInstance, Tcl_GetClassAsObject, Tcl_GetObjectAsClass, Tcl_GetObjectCommand, Tcl_GetObjectNamespace, Tcl_NewObjectInstance, Tcl_ObjectDeleted, Tcl_ObjectGetMetadata, Tcl_ObjectGetMethodNameMapper, Tcl_ObjectSetMetadata, Tcl_ObjectSetMethodNameMapper \- manipulate objects and classes
+Tcl_ClassGetMetadata, Tcl_ClassSetMetadata, Tcl_CopyObjectInstance, Tcl_GetClassAsObject, Tcl_GetObjectAsClass, Tcl_GetObjectCommand, Tcl_GetObjectFromObj, Tcl_GetObjectName, Tcl_GetObjectNamespace, Tcl_NewObjectInstance, Tcl_ObjectDeleted, Tcl_ObjectGetMetadata, Tcl_ObjectGetMethodNameMapper, Tcl_ObjectSetMetadata, Tcl_ObjectSetMethodNameMapper \- manipulate objects and classes
 .SH SYNOPSIS
 .nf
 \fB#include <tclOO.h>\fR
diff --git a/doc/CrtInterp.3 b/doc/CrtInterp.3
index d1a030a..a248cf4 100644
--- a/doc/CrtInterp.3
+++ b/doc/CrtInterp.3
@@ -9,7 +9,7 @@
 .TH Tcl_CreateInterp 3 7.5 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpDeleted \- create and delete Tcl command interpreters
+Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpActive, Tcl_InterpDeleted \- create and delete Tcl command interpreters
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
diff --git a/doc/Ensemble.3 b/doc/Ensemble.3
index 2153840..19c6099 100644
--- a/doc/Ensemble.3
+++ b/doc/Ensemble.3
@@ -10,7 +10,7 @@
 .TH Tcl_Ensemble 3 8.5 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_CreateEnsemble, Tcl_FindEnsemble, Tcl_GetEnsembleFlags, Tcl_GetEnsembleMappingDict, Tcl_GetEnsembleNamespace, Tcl_GetEnsembleUnknownHandler, Tcl_GetEnsembleSubcommandList, Tcl_IsEnsemble, Tcl_SetEnsembleFlags, Tcl_SetEnsembleMappingDict, Tcl_SetEnsembleSubcommandList, Tcl_SetEnsembleUnknownHandler \- manipulate ensemble commands
+Tcl_CreateEnsemble, Tcl_FindEnsemble, Tcl_GetEnsembleFlags, Tcl_GetEnsembleMappingDict, Tcl_GetEnsembleNamespace, Tcl_GetEnsembleParameterList, Tcl_GetEnsembleUnknownHandler, Tcl_GetEnsembleSubcommandList, Tcl_IsEnsemble, Tcl_SetEnsembleFlags, Tcl_SetEnsembleMappingDict, Tcl_SetEnsembleParameterList, Tcl_SetEnsembleSubcommandList, Tcl_SetEnsembleUnknownHandler \- manipulate ensemble commands
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
diff --git a/doc/FileSystem.3 b/doc/FileSystem.3
index 7816099..e3870c3 100644
--- a/doc/FileSystem.3
+++ b/doc/FileSystem.3
@@ -718,14 +718,14 @@ sequences (these have been expanded to their current
 representation in the filesystem). The object returned is owned by the
 caller, which must store it or call Tcl_DecrRefCount to ensure memory is
 freed. This function is of little practical use, and
-\fBTcl_FSGetNormalizedPath\fR or \fBTcl_GetNativePath\fR are usually
+\fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually
 better functions to use for most purposes.
 .PP
 \fBTcl_FSGetTranslatedStringPath\fR does the same as
 \fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL.
 The string returned is dynamically allocated and owned by the caller,
 which must store it or call \fBckfree\fR to ensure it is freed. Again,
-\fBTcl_FSGetNormalizedPath\fR or \fBTcl_GetNativePath\fR are usually
+\fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually
 better functions to use for most purposes.
 .PP
 \fBTcl_FSNewNativePath\fR performs something like the reverse of the
@@ -792,7 +792,7 @@ It returns one of \fBTCL_PATH_ABSOLUTE\fR, \fBTCL_PATH_RELATIVE\fR, or
 .PP
 \fBTcl_AllocStatBuf\fR allocates a \fITcl_StatBuf\fR on the system heap (which
 may be deallocated by being passed to \fBckfree\fR). This allows extensions to
-invoke \fBTcl_FSStat\fR and \fBTcl_FSLStat\fR without being dependent on the
+invoke \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR without being dependent on the
 size of the buffer. That in turn depends on the flags used to build Tcl.
 .PP
 .VS 8.6
diff --git a/doc/Method.3 b/doc/Method.3
index 11e2d5b..43b3609 100644
--- a/doc/Method.3
+++ b/doc/Method.3
@@ -9,7 +9,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_ClassSetConstructor, Tcl_ClassSetDestructor, Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsType, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts
+Tcl_ClassSetConstructor, Tcl_ClassSetDestructor, Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsType, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_ObjectContextInvokeNext, Tcl_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts
 .SH SYNOPSIS
 .nf
 \fB#include <tclOO.h>\fR
diff --git a/doc/NRE.3 b/doc/NRE.3
index dfa6064..5c27491 100644
--- a/doc/NRE.3
+++ b/doc/NRE.3
@@ -141,7 +141,7 @@ trampoline.
 .PP
 \fBTcl_NRCmdSwap\fR allows for trampoline evaluation of a command whose
 resolution is already known.  The \fIcmd\fR parameter gives a
-\fBTcl_Command\fR object (returned from \fBTcl_CreateObjCmd\fR or
+\fBTcl_Command\fR object (returned from \fBTcl_CreateObjCommand\fR or
 \fBTcl_GetCommandFromObj\fR) identifying the command to be invoked in
 the trampoline; this command must match the word in \fIobjv[0]\fR.
 The remaining arguments are as for \fBTcl_NREvalObj\fR.
diff --git a/doc/Namespace.3 b/doc/Namespace.3
index c42e36e..50cc559 100644
--- a/doc/Namespace.3
+++ b/doc/Namespace.3
@@ -160,6 +160,6 @@ for the namespace, or NULL if none is set.
 the namespace. If \fIhandlerPtr\fR is NULL, then the handler is reset to
 its default.
 .SH "SEE ALSO"
-Tcl_CreateCommand(3), Tcl_ListObjAppendElements(3), Tcl_SetVar(3)
+Tcl_CreateCommand(3), Tcl_ListObjAppendList(3), Tcl_SetVar(3)
 .SH KEYWORDS
 namespace, command
diff --git a/doc/Notifier.3 b/doc/Notifier.3
index ddd4ae1..435f779 100644
--- a/doc/Notifier.3
+++ b/doc/Notifier.3
@@ -411,7 +411,7 @@ an event to the current thread's queue.
 To add an event to another thread's queue, use \fBTcl_ThreadQueueEvent\fR.
 \fBTcl_ThreadQueueEvent\fR accepts as an argument a Tcl_ThreadId argument,
 which uniquely identifies a thread in a Tcl application.  To obtain the
-Tcl_ThreadID for the current thread, use the \fBTcl_GetCurrentThread\fR
+Tcl_ThreadId for the current thread, use the \fBTcl_GetCurrentThread\fR
 procedure.  (A thread would then need to pass this identifier to other
 threads for those threads to be able to add events to its queue.)
 After adding an event to another thread's queue, you then typically
diff --git a/doc/SplitList.3 b/doc/SplitList.3
index b7d1969..219dfc7 100644
--- a/doc/SplitList.3
+++ b/doc/SplitList.3
@@ -182,7 +182,7 @@ with \fBTCL_DONT_QUOTE_HASH\fR.
 the same as \fBTcl_ScanElement\fR and \fBTcl_ConvertElement\fR, except
 the length of string \fIsrc\fR is specified by the \fIlength\fR
 argument, and the string may contain embedded nulls.
+.SH "SEE ALSO"
+Tcl_ListObjGetElements(3)
 .SH KEYWORDS
 backslash, convert, element, list, merge, split, strings
-.SH "SEE ALSO"
-Tcl_GetListFromObj(3)
diff --git a/doc/Translate.3 b/doc/Translate.3
index d434cda..55233c3 100644
--- a/doc/Translate.3
+++ b/doc/Translate.3
@@ -29,7 +29,6 @@ At the time of the call it should be uninitialized or free.  The
 caller must eventually call \fBTcl_DStringFree\fR to free up
 anything stored here.
 .BE
-
 .SH DESCRIPTION
 .PP
 This utility procedure translates a file name to a platform-specific form
@@ -38,11 +37,11 @@ passing to the local operating system.  In particular, it converts
 network names into native form and does tilde substitution.  
 .PP
 However, with the advent of the newer \fBTcl_FSGetNormalizedPath\fR and
-\fBTcl_GetNativePath\fR, there is no longer any need to use this
-procedure.  In particular, \fBTcl_GetNativePath\fR performs all the
+\fBTcl_FSGetNativePath\fR, there is no longer any need to use this
+procedure.  In particular, \fBTcl_FSGetNativePath\fR performs all the
 necessary translation and encoding conversion, is virtual-filesystem
 aware, and caches the native result for faster repeated calls.
-Finally \fBTcl_GetNativePath\fR does not require you to free anything
+Finally \fBTcl_FSGetNativePath\fR does not require you to free anything
 afterwards.
 .PP
 If
@@ -66,9 +65,7 @@ frees the dynamic string itself so that the caller need not call
 .PP
 The caller is responsible for making sure that the interpreter's result
 has its default empty value when \fBTcl_TranslateFileName\fR is invoked.
-
 .SH "SEE ALSO"
-filename
-
+filename(n)
 .SH KEYWORDS
 file name, home directory, tilde, translate, user
diff --git a/tools/tcltk-man2html-utils.tcl b/tools/tcltk-man2html-utils.tcl
index a7270a1..af2faa3 100644
--- a/tools/tcltk-man2html-utils.tcl
+++ b/tools/tcltk-man2html-utils.tcl
@@ -4,7 +4,7 @@
 ## by Tcl and Tk; they do not cope with arbitrary nroff markup.
 ##
 ## Copyright (c) 1995-1997 Roger E. Critchlow Jr
-## Copyright (c) 2004-2010 Donal K. Fellows
+## Copyright (c) 2004-2011 Donal K. Fellows
 
 set ::manual(report-level) 1
 
@@ -491,7 +491,7 @@ proc output-IP-list {context code rest} {
 	set dl "<DL class=\"[string tolower $manual(section)]\">"
 	set enddl "</DL>"
 	if {$code eq ".IP"} {
-	    if {[regexp {^\[[\da-f]+\]$} $rest]} {
+	    if {[regexp {^\[[\da-f]+\]|\(?[\da-f]+\)$} $rest]} {
 		set dl "<OL class=\"[string tolower $manual(section)]\">"
 		set enddl "</OL>"
 	    } elseif {"&#8226;" eq $rest} {
@@ -518,6 +518,8 @@ proc output-IP-list {context code rest} {
 			    man-puts "$para<DT>$rest<DD>"
 			} elseif {[regexp {^\[([\da-f]+)\]$} $rest -> value]} {
 			    man-puts "$para<LI value=\"$value\">"
+			} elseif {[regexp {^\(?([\da-f]+)\)$} $rest -> value]} {
+			    man-puts "$para<LI value=\"$value\">"
 			} elseif {"&#8226;" eq $rest} {
 			    man-puts "$para<LI>"
 			} else {
@@ -624,7 +626,7 @@ proc cross-reference {ref} {
     set manname $manual(name)
     set mantail $manual(tail)
     if {[string match "Tcl_*" $ref] || [string match "Tk_*" $ref] || [string match "Ttk_*" $ref]} {
-	set lref $ref
+	regexp {^\w+} $ref lref
 	##
 	## apply a link remapping if available
 	##
diff --git a/tools/tcltk-man2html.tcl b/tools/tcltk-man2html.tcl
index cd8b0e5..f928d4a 100755
--- a/tools/tcltk-man2html.tcl
+++ b/tools/tcltk-man2html.tcl
@@ -828,6 +828,33 @@ array set remap_link_target {
     pkg_mkIndex pkg_mkIndex
     Tcl_Obj     Tcl_NewObj
     Tcl_ObjType Tcl_RegisterObjType
+    Tcl_OpenFileChannelProc Tcl_FSOpenFileChannel
+    errorinfo 	env
+    errorcode 	env
+    tcl_pkgpath env
+    Tcl_Command Tcl_CreateObjCommand
+    Tcl_CmdProc Tcl_CreateObjCommand
+    Tcl_Channel Tcl_OpenFileChannel
+    Tcl_WideInt Tcl_NewIntObj
+    Tcl_ChannelType Tcl_CreateChannel
+    Tcl_DString Tcl_DStringInit
+    Tcl_Namespace Tcl_AppendExportList
+    Tcl_Object  Tcl_NewObjectInstance
+    Tcl_Class   Tcl_GetObjectAsClass
+    Tcl_Event   Tcl_QueueEvent
+    Tcl_Time	Tcl_GetTime
+    Tcl_ThreadId Tcl_CreateThread
+    Tk_Window	Tk_WindowId
+    Tk_3DBorder Tk_Get3DBorder
+    Tk_Anchor	Tk_GetAnchor
+    Tk_Cursor	Tk_GetCursor
+    Tk_Dash	Tk_GetDash
+    Tk_Font	Tk_GetFont
+    Tk_Image	Tk_GetImage
+    Tk_ImageMaster Tk_GetImage
+    Tk_ItemType Tk_CreateItemType
+    Tk_Justify	Tk_GetJustify
+    Ttk_Theme	Ttk_GetTheme
 }
 array set exclude_refs_map {
     bind.n		{button destroy option}