On 24/01/2019 22:12, Andrew Parsloe wrote:
> Reading through the l3draw documentation various matters came to mind:

Thanks for taking the time on this: to date there's not been a lot of 
detailed feedback.

> Section 1.9 of l3draw.pdf
> Typos
> Text: \draw_transform_matrix:nnnnn
>        has a fifth "n"
> Margin: \draw_transform_xscale:n
>        the second occurrence should be \draw_transform_yscale:n and not 
> greyed out.
> Text: \draw_transform_shift:n
>        \draw_transform_xshift:n
>       delete \draw_transform_shift:n
> Margin: \draw_transform_matrix_reset
>        needs a concluding colon

All corrected for the next release.

> Clarification
> Perhaps there should be a mention under 
> \draw_transform_matrix_concat:nnnn that concatenating means matrix 
> multiplication from the left.

Perhaps, though the point below I suspect suggests a rename may be better.

> Naming
> There is \draw_transform_matrix_concat:nnnn and 
> \draw_transform_shift_concat:n. The rotate, scale, shift and slant 
> transforms are also concatenations but not so named (lack the _concat). 
> I wonder if a better naming scheme might be to drop the _concat from 
> \draw_transform_matrix_concat:nnnn and \draw_transform_shift_concat:n, 
> thus treating all the concatenating transforms similarly, and rename the 
> functions currently called \draw_transform_matrix:nnnn and 
> \draw_transform_shift:n to something else, perhaps 
> \draw_transform_matrix_set:nnnn and \draw_transform_shift_set:n?

The basic idea here was to try to split up the relative and absolute 
transformation changes. As you say, shifts and the like are relative to 
the previous transformation. The "matrix_concat" one is the relative 
case, the "matrix" alone is a replacement of the entire matrix. So 
perhaps better is to drop "concat" and have something like

     \draw_transform_replace:nnnn

     \draw_transform_absolute_matrix:nnnn

or as you say "set". The latter is a bit tricky: in general in expl3, 
"set" is used for variables where we can \<thing>_set:Nn... them. That's 
not 100% the case, but I've avoided "set" in other places in l3draw. 
(Still I think needs discussion for things like line width, etc.)

> Comma lists?
> Was consideration given to using a comma list instead of four separate 
> braced arguments for \draw_transform_matrix:nnnn? {a}{b}{c}{d} needs 
> four brace pairs, {a,b,c,d} needs only one. I have a standard US 
> keyboard (at least I think it is). The { and } characters require the 
> shift key and a (small) stretch of the little finger to type; commas on 
> the other hand are easy, no stretch, no shift key. Comma lists are 
> widely used elsewhere in l3draw for specifying coordinate pairs, e.g. 
> \draw_path_moveto:n { 1cm , 0cm }. Even {a,b}{c,d} would be better -- 
> and helpful in separating the rows of the matrix.

As the docs say, the API I've gone for is the same as pgf's if possible: 
that's well-established and works for people. For co-ordinates, it's 
very common to write them as "(x,y)" with a comma: I did consider at the 
code level requiring two arguments! However, for matrices, it's more 
common to write them as space-separated lists if written linear, at 
least in my experience. Moreover, this is a pretty low-level operation.

Joseph