Matt Huszagh <huszaghm...@gmail.com> writes: >> It would help if closure part and multi-variable part were split into >> separate paragraphs. > > The closure part and muliple header argument part are already in > separate paragraphs. The multiple header argument part, however, is > incorporated into an introductory paragraph that very briefly describes > the value syntax of org-babel-default-header-args and the types of alist > values it supports. I did this because that introductory information is > short and simple and so I felt it acceptable to incorporate the multiple > header argument information. I don't feel this places a significant > intellectual burden on the reader to follow, but I'm happy to insert a > newline before "Some header arguments..." if you'd prefer.
Yes, please. And also move the multiple header arg parts below the closure example. >> Are you saying that _only some_ backends support multiple vars? Are >> there backends that do not support? > > I think you're confused about "(e.g., :var for some language backends)": > > It's been a while since I created this patch and I don't remember > exactly why I wrote it this way. I think it was based on the belief that > not all language backends support variable passing in header arguments, > though I honestly couldn't tell you at the moment whether this is > true. In that vein, a semantically equivalent way to write this would be > "(e.g., :var for language backends that support it)". Maybe all language > backends support variable header arguments, in which case "(e.g., :var)" > could be used here instead. In any case, the "some language backends" > part of the phrase is not a qualification of "multiple", but of > "variables". Nor is it correct to read it this way, as the statement is > grammatically clear and correct. An equivalent statement would be: > > """ > Some header arguments can be provided multiple times for a source > block. An example of such a header argument is :var. > """ This looks slightly better. Though after reading your reply and reviewing the docstring, I realize that my confusion partially came from the fact that your patch is about closures, while the docstring change is not. Could you split that patch in two parts: one for the docstring change and one for the :var parameter handling? >> Also, the example is not helpful here. > > The example *is* helpful. It provides explicit direction for how to > handle the non-obvious case of header arguments that can be passed > multiple times, which isn't described much in the documentation. Agree. See my above explanation about the source of confusion. Best, Ihor
