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
<ijack...@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
