[Tcl-bugs] [ tcl-Bugs-625166 ] Tcl/Tk man page formatting note

[<no...@so...>]

Bugs item #625166, was opened at 2002-10-18 08:08
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=110894&aid=625166&group_id=10894

Category: 69. Other
Group: 8.4.1
Status: Open
Resolution: None
Priority: 5
Submitted By: Larry W. Virden (lvirden)
Assigned to: Nobody/Anonymous (nobody)
Summary: Tcl/Tk man page formatting note

Initial Comment:
On unix there is a concept of a 'whatis' database that
is built using either mkwhatis or catman.  This
database allows one to search quickly through man pages
to find appropriate man pages.

In trying to build the whatis for the tcl/tk man pages,
I got the following warning/errors.  Some of these
reflect a formatting problem (at least on
SPARC/Solaris).  Some indicate a limitation in data . 
Just thought that perhaps if someone is going through
the man pages they might consider slightly reformatting
to make the info more useful.

$ catman -w -M .
makewhatis: processing man tree
/osfiles6/tcl84binsol/man/....
Tcl_FSLoadFile.3: truncating cmdlist from 783 to 300
bytes for DBM's sake
Tcl_ChannelInputProc.3: truncating cmdlist from 738 to
300 bytes for DBM's sake
Tk_X.3: truncating cmdlist from 385 to 300 bytes for
DBM's sake
Tcl_MakeFileChannel.3: truncating cmdlist from 490 to
300 bytes for DBM's sake
Tcl_AttemptSetObjLength.3: truncating cmdlist from 366
to 300 bytes for DBM's sake
Tcl_UtfToExternalDString.3: truncating cmdlist from 301
to 300 bytes for DBM's sake
Tcl_UtfToUniChar.3: truncating cmdlist from 326 to 300
bytes for DBM's sake
Tk_NameOf3DBorder.3: truncating cmdlist from 301 to 300
bytes for DBM's sake
Tcl_FSReadlink.3: truncating cmdlist from 697 to 300
bytes for DBM's sake
Tk_CreatePhotoImageFormat.3: no separated dash in
"formatPtr->name provides a name for the image type.
Once Tk_CreatePhotoImageFormat returns, this name may
be used in the -format photo image configuration and
subcommand option. The manual page for the photo image
(photo(n)) describes how image file formats are chosen
based on their names and the value given to the -format
option. For new format handlers, the name should be in
lower case. Pre-8.3 format handlers are assumed to be
in upper case."
Tcl_InitNotifier.3: truncating cmdlist from 325 to 300
bytes for DBM's sake
Tk_GetImageMasterData.3: no separated dash in
"typePtr->name provides a name for the image type. Once
Tk_CreateImageType returns, this name may be used in
image create commands to create images of the new type.
If there already existed an image type by this name
then the new image type replaces the old one."
Tk_CreateItemType.3: no separated dash in "This section
and the ones that follow describe each of the fields in
a Tk_ItemType structure in detail. The name field
provides a string name for the item type. Once
Tk_CreateImageType returns, this name may be used in
create widget commands to create items of the new type.
If there already existed an item type by this name then
the new item type replaces the old one."
msgcat.n: no separated dash in "Strings stored in the
message catalog are stored relative to the namespace
from which they were added.  This allows multiple
packages to use the same strings without fear of
collisions with other packages.  It also allows the
source string to be shorter and less prone to
typographical error. For example, executing the code
mcset en hello "hello from ::" namespace eval foo
{mcset en hello "hello from ::foo"} puts [mc hello]
namespace eval foo {puts [mc hello]} will print hello
from :: hello from ::foo When searching for a
translation of a message, the message catalog will
search first the current namespace, then the parent of
the current namespace, and so on until the global
namespace is reached.  This allows child namespaces to
"inherit" messages from their parent namespace. For
example, executing (in the ``en'' locale) the code 
mcset en m1 ":: message1" mcset en m2 ":: message2"
mcset en m3 ":: message3" namespace eval ::foo {    
mcset en m2 "::foo message2"     mcset en m3 "::foo
message3" } namespace eval ::foo::bar {     mcset en m3
"::foo::bar message3" } puts "[mc m1]; [mc m2]; [mc
m3]" namespace eval ::foo {puts "[mc m1]; [mc m2]; [mc
m3]"} namespace eval ::foo::bar {puts "[mc m1]; [mc
m2]; [mc m3]"} will print :: message1; :: message2; ::
message3 :: message1; ::foo message2; ::foo message3 ::
message1; ::foo message2; ::foo::bar message3"
can't store msgcat.n -- would break DBM
namespace.n: no separated dash in "In general, all Tcl
commands that take variable and command names support
qualified names. This means you can give qualified
names to such commands as set, proc, rename, and interp
alias. If you provide a fully-qualified name that
starts with a ::, there is no question about what
command, variable, or namespace you mean. However, if
the name does not start with a :: (i.e., is relative),
 Tcl follows a fixed rule for looking it up: Command
and variable names are always resolved by looking first
in the current namespace, and then in the global
namespace. Namespace names, on the other hand, are
always resolved by looking in only the current
namespace. In the following example, set traceLevel 0
namespace eval Debug {     printTrace $traceLevel } Tcl
looks for traceLevel in the namespace Debug and then in
the global namespace. It looks up the command
printTrace in the same way. If a variable or command
name is not found in either context, the name is
undefined. To make this point absolutely clear,
consider the following example: set traceLevel 0
namespace eval Foo {     variable traceLevel 3"
usual.n: no separated dash in " for a mega-widget
component"
itcl.n: no separated dash in "[incr Tcl] now includes a
complete namespace facility. A namespace is a
collection of commands and global variables that is
kept apart from the usual global scope.  This allows
Tcl code libraries to be packaged in a well-defined
manner, and prevents unwanted interactions with other
libraries.  A namespace can also have child namespaces
within it, so one library can contain its own private
copy of many other libraries.  A namespace can also be
used to wrap up a group of related classes.  The global
scope (named "fC::") is the root namespace for an
interpreter; all other namespaces are contained within
it. See the namespace command for details on creating
and using namespaces."
makewhatis: /osfiles6/tcl84binsol/man/.: found 1624
entries in 640 files

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=110894&aid=625166&group_id=10894