Hi Lars,

Just a minor point or two.

On 26/08/2009, at 8:21 AM, Lars Hellström wrote:
>
> One noticable difference to what I believe was discussed is in the  
> order of processors. If ">{A} o" means "grab optional argument, then  
> apply A", then I think it stands to reason that ">{B} >{A} o" should  
> mean "grab optional argument, then apply A, finally apply B", but as  
> implemented in revision 1494 it's B before A. (Reversing the  
> processing order would allow one to do without  
> \l_xparse_processor_use_int.)
>
> If you find it important that processors should be applied in left- 
> to-right order, then I believe they should appear after the argspec  
> base, perhaps as "o <{A} <{B}", to keep as invariant that the thing  
> being done first is closest to the argspec base. (SYNTAX CHANGE)  
> This may also have the added value of being more intuitive for users.


I don't have strong opinions on the matter, but:
(a) I prefer '>{A} m' over 'm <{A}'
(b) I agree right-to-left makes some sense

>    \exp_args:NnV \@firstofone {#2} \l_xparse_arg_toks
>       % How do without \@firstofone here?

The problem is that \exp_args are designed for expanding arguments  
being passed to a function, not for general expansion control; as  
you've noticed this means they have a tendency to surround everything  
with braces.

I've proposed some extensions to \exp_after to allow this sort of  
thing (e.g., \exp_after:nV which would not brace-surround the first  
argument) but it hasn't been clear if it's useful enough, yet.

(Also, instead of \@firstofone you can use \use:n if you wish)

> In the typeset form, there is an index which should provide the same  
> functionality via hyperlinks (although for some reason all the links  
> seem to go to page 1; is that just for me or is it broken in l3doc  
> in general?)

I've had similar problems in the past but they generally clear up with  
some magic number of LaTeX runs after the index generation. Or l3doc  
could be broken; it's not particularly nice code at the moment (my  
fault).

> Some further introspection reveals that this happens inside an  
> expansion of \g_doc_functions_seq, which is very, VERY long. Hence I  
> suppose this "infinite loop" may in fact be an O(n^2) operation for  
> a very large n. Perhaps you should examine switching to a faster  
> algorithm, or provide some indication of progress?

Indeed, what \g_doc_functions_seq is being used for is quite  
unnecessary for source3. This is disabled in the Makefile; I should  
probably turn it off by default in l3doc and only enable it when  
necessary.

(It's checking that the functions documented with \begin{function} are  
also implemented with \begin{macro}, and warning of cases where  
functions have been implemented without documentation or vice versa.)

In the meantime you should have more luck with `make sourcedoc`.

Hope this helps,
Will