Re: [PATCH] Fix behavior of lambda default header arg vars

[Matt Huszagh]

> 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