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

[Sergei Golovan]

Hi Ian,

You're right. The docs about lists are confusing a bit. I'll forward
this bug upstream
and we'll see how can the confusion be resolved.

On Wed, Jul 25, 2018 at 5:00 AM Ian Jackson
<ijackson at chiark.greenend.org.uk> wrote:
>
> 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.

As far as I understand, these rules are for those who construct lists
as strings.
Personally, I found that with the exception of very simple constant lists it's
much easier to use the [list] command which guarantees its output to form
a list.

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

Right, {*} can be read as something with braces, though strictly speaking,
rules concerning braces are listed in section [6] of the Dodecalogue, so
formally, the manpage is correct. But I agree that it's confusing and could
be expanded here.

>
> 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.)

Again, I agree that it'd be better to add this to the lindex manual as well.

>
> 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) !

As for the [list] manpage, I guess the problem is that one doesn't worry
about representing strings as lists when he uses the [list] command.
It always returns a proper list, so all these rules don't matter. Though,
a paragraph with a link to the [lindex] manpage would be useful.

>
> 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).

I don't think that moving strings-to-lists semantics to Tcl(3tcl) makes
much sense. It isn't a Tcl syntax after all.

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

Cross-referencing from list(3tcl) would be a good idea. Cross-referenceing
from Tcl(3tcl) not so much IMHO (then why not cross-reference the other
manpages with special string interpreting, like [expr] or [regexp]?)

Cheers!
-- 
Sergei Golovan