[Pkg-tcltk-devel] Bug#904523: tcl8.6-doc: list syntax documentation inaccurate and hard to find

[Ian Jackson]

Package: tcl8.6-doc
Version: 8.6.6+dfsg-1
Severity: minor

lindex(3tcl) says:

			   ....  In extracting the element, lindex observes
    the same rules concerning braces and quotes and backslashes as the  Tcl
    command interpreter; however, variable substitution and command substi‐
    tution do not occur.

However, this is not correct.  Tcl list syntax does not support
the {*} syntax, called `Argument expansion' in Tcl(3tcl).

And, it would be clearer to explicitly state that #-comments are not
recognised within plain lists.  (It does follow from the statement "at
a point where Tcl is expecting the first character of the first word
of a command" but this is an obscure way to document the list syntax.)


Furthermore, it is very hard to find this spec.  It is buried in the
middle of a paragraph in exactly one of a myriad list processing
commands.  And not list(3tcl) !

I suggest that the specification be moved to Tcl(3tcl) and folded into
the definition of the command list syntax.  Perhaps lists for lindex,
lappend, etc., could be called "plain" lists as opposed to the
"command lists" currently described in Tcl(3tcl).

If this is too hard, for now cross-references from list(3tcl) and
Tcl(3tcl) to lindex(3tcl) would be helpful.


-- System Information:
Debian Release: 9.5
  APT prefers stable-debug
  APT policy: (500, 'stable-debug'), (500, 'stable')
Architecture: amd64 (x86_64)
Foreign Architectures: i386

Kernel: Linux 4.16.0-0.bpo.2-amd64 (SMP w/4 CPU cores)
Locale: LANG=C.UTF-8, LC_CTYPE=C.UTF-8 (charmap=UTF-8), LANGUAGE=C.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: sysvinit (via /sbin/init)

tcl8.6-doc depends on no packages.

tcl8.6-doc recommends no packages.

Versions of packages tcl8.6-doc suggests:
ii  tcl8.6  8.6.6+dfsg-1+b1

-- no debconf information