> 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. > 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. """ > Or are you talking about multiple assignments to the same variable? No. The topic of multiple assignments to the same variable is not discussed here. > 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. > The new docstring is confusing. The same paragraph is talking about > closures, then multiple header args, and gives an example without > closures. I don't think there's anything particularly confusing about this docstring. As already mentioned, that paragraph discusses acceptable alist values and multiple header args. Closures are mentioned only as one of the acceptable alist values, which puts them on the same level as strings. The more in-depth discussion of closures happens later, in its own paragraphs. Taking a step back, the structure of this docstring is: 1. A single sentence briefly describing org-babel-default-header-args. 2. A description of the syntax and acceptable values that can be assigned to org-babel-default-header-args. 3. A discussion of how to handle header arguments that can be provided multiple times. This explicit treatment is justified because this case is not intuitively obvious. 4. A discussion of closures (including why functions need to be provided as closures) and an example illustrating their usefulness. 2 and 3 are part of the same paragraph and 4 is several paragraphs (the precise number depends on whether you consider code blocks to be their own paragraph and how they break up surrounding text). This is a perfectly reasonable way to structure this information. There's no rule requiring that there be one topic per paragraph. Instead, paragraphs should be structured in a way that's clear, and in many cases (not all) that does result in a paragraph discussing one topic. But again, a reasonable alternative structure would be to separate 2 and 3 into their own paragraphs and I'm happy to do that. The multiple header argument discussion also doesn't need to be located where it is. It could alternatively go after the discussion of closures if you prefer that. Matt
