From 78ab9d722b4e992f8d02002585102f6c7ec7db1a Mon Sep 17 00:00:00 2001 From: dkf Date: Mon, 18 Jul 2011 23:45:15 +0000 Subject: The final parts of my doc improvement project --- ChangeLog | 15 +++++++++++++-- doc/Class.3 | 2 +- doc/CrtInterp.3 | 2 +- doc/Ensemble.3 | 2 +- doc/FileSystem.3 | 6 +++--- doc/Method.3 | 2 +- doc/NRE.3 | 2 +- doc/Namespace.3 | 2 +- doc/Notifier.3 | 2 +- doc/SplitList.3 | 4 ++-- doc/Translate.3 | 11 ++++------- tools/tcltk-man2html-utils.tcl | 8 +++++--- tools/tcltk-man2html.tcl | 27 +++++++++++++++++++++++++++ 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 + + * 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 * 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 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 \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 \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 \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 \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 "
" set enddl "
" if {$code eq ".IP"} { - if {[regexp {^\[[\da-f]+\]$} $rest]} { + if {[regexp {^\[[\da-f]+\]|\(?[\da-f]+\)$} $rest]} { set dl "
    " set enddl "
" } elseif {"•" eq $rest} { @@ -518,6 +518,8 @@ proc output-IP-list {context code rest} { man-puts "$para
$rest
" } elseif {[regexp {^\[([\da-f]+)\]$} $rest -> value]} { man-puts "$para
  • " + } elseif {[regexp {^\(?([\da-f]+)\)$} $rest -> value]} { + man-puts "$para
  • " } elseif {"•" eq $rest} { man-puts "$para
  • " } 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} -- cgit v0.12