From: Matt Huszagh <huszaghmatt@gmail.com>
To: Ihor Radchenko <yantar92@gmail.com>
Cc: "emacs-orgmode@gnu.org" <emacs-orgmode@gnu.org>
Subject: Re: [PATCH] Fix behavior of lambda default header arg vars
Date: Sun, 05 Jun 2022 09:00:01 -0700 [thread overview]
Message-ID: <87ee03je2m.fsf@gmail.com> (raw)
In-Reply-To: <87ee035mnp.fsf@localhost>
> 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
next prev parent reply other threads:[~2022-06-05 16:02 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-10-27 14:57 [PATCH] Fix behavior of lambda default header arg vars Matt Huszagh
[not found] ` <87y252bfr4.fsf@gmail.com>
2021-12-03 2:43 ` Matt Huszagh
2022-06-05 12:18 ` Ihor Radchenko
2022-06-05 16:00 ` Matt Huszagh [this message]
2022-06-11 2:47 ` Ihor Radchenko
2022-06-28 3:53 ` Matt Huszagh
2022-06-29 10:02 ` Ihor Radchenko
2022-07-08 23:12 ` Matt Huszagh
2022-07-09 5:23 ` Ihor Radchenko
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87ee03je2m.fsf@gmail.com \
--to=huszaghmatt@gmail.com \
--cc=emacs-orgmode@gnu.org \
--cc=yantar92@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).