[Tcllib-devel] what is the naming strategy for tcllib module reference pages?

[Virden, L. W. <lv...@ca...>]

One of the frustrating things I've encountered with Tcl over the years has
to do with something as simple as names.

For instance, there is the frustration of remembering the package name. I
mean, is it 

package require tclx
package require Tclx
or
package require TclX

One of the things that makes it confusing is this:

$ man -s n TclX
and I get a reference page
$ tclsh8.5
% package require TclX
can't find package TclX
%

In the case of some other packages, trying to figure out what to do about
colons in the name is a decision. Sometimes, such as in Tcl, the name is
just left alone (man -s n platform::shell). In other cases, the double colon
is turned into an underline or some other character. And in other cases, 
the doc namers just try to avoid the whole issue.

A similar situation occurs in Tcllib. In some cases, man pages are the
name of the command inside of a tcllib module, with no indication of the
module that one requires to get it. In other cases, the man page
names are the module name, an underline, and a command name, or a module name,
an underline, and a descriptive word or abbreviation. And in other
cases, the name is a namespace, an underline, and another command name.

For a developer trying to figure out what to type to find a specific man
command, it becomes a frustration.

Here's some of the issues:

1. In textutil, the string and split command reference pages are installed
as string.n and split.n ... overwriting the Tcl man pages for those commands.

2. These commands are two part names:
ansi_cattr.n             doctoc_lang_faq.n        ntp_time.n
ansi_cctrl.n             doctoc_lang_intro.n      page_intro.n
ansi_cmacros.n           doctoc_lang_syntax.n     page_pluginmgr.n
ansi_code.n              doctoc_plugin_apiref.n   page_util_flow.n
ansi_ctrlu.n             doctools_intro.n         page_util_norm_lemon.n
ansi_send.n              doctools_lang_cmdref.n   page_util_norm_peg.n
bench_intro.n            doctools_lang_faq.n      page_util_peg.n
bench_lang_intro.n       doctools_lang_intro.n    page_util_quote.n
bench_lang_spec.n        doctools_lang_syntax.n   peg_interp.n
bench_read.n             doctools_plugin_apiref.n pop3d_dbox.n
bench_wcsv.n             ftp_geturl.n             pop3d_udb.n
bench_wtext.n            me_ast.n                 rational_funcs.n
comm_wire.n              me_cpu.n                 stringprep_data.n
deleg_method.n           me_cpucore.n             struct_list.n
deleg_proc.n             me_intro.n               struct_set.n
docidx_intro.n           me_tcl.n                 struct_tree.n
docidx_lang_cmdref.n     me_util.n                struct_tree1.n
docidx_lang_faq.n        me_vm.n                  tcllib_dns.n
docidx_lang_intro.n      nns_auto.n               tcllib_interp.n
docidx_lang_syntax.n     nns_client.n             tcllib_ip.n
docidx_plugin_apiref.n   nns_common.n             term_bind.n
docstrip_util.n          nns_intro.n              term_send.n
doctoc_intro.n           nns_protocol.n           tie_std.n
doctoc_lang_cmdref.n     nns_server.n             unicode_data.n

-- 
Tcl - The glue of a new generation.  <URL: http://wiki.tcl.tk/ >
Larry W. Virden <mailto:lv...@ca...><URL: http://www.purl.org/NET/lvirden/ >
Even if explicitly stated to the contrary, nothing in this posting should 
be construed as representing my employer's opinions.
-><-