Re: babel/noweb concatenation of equally-named code blocks fails?
Hello, Greg Minshall writes: > below is a format-patch. i signed FSF papers for emacs a number of > years ago (and for gawk more recently). Perfect. I applied it. Thank you! Regards, -- Nicolas Goaziou
Re: babel/noweb concatenation of equally-named code blocks fails?
Nicolas,
below is a format-patch. i signed FSF papers for emacs a number of
years ago (and for gawk more recently).
cheers, Greg
From e2d440186ccf62216406abb440455edbac72ba79 Mon Sep 17 00:00:00 2001
From: Greg Minshall
Date: Wed, 22 Apr 2020 14:45:52 -0700
Subject: [PATCH] some clarification on <>, #+name:, :noweb-ref
---
doc/org-manual.org | 29 +++--
1 file changed, 15 insertions(+), 14 deletions(-)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index 2a2700739..1c4a1f954 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -17988,12 +17988,13 @@ using a noweb[fn:145] style syntax:
: <>
#+texinfo: @noindent
-where {{{var(CODE-BLOCK-ID)}}} refers to either the =NAME= of
-a specific source code block, or a collection of source code blocks
+where {{{var(CODE-BLOCK-ID)}}} refers to either the =NAME= of
+a single source code block, or a collection of one or more source code blocks
sharing the same =noweb-ref= header argument (see [[*Using Header
-Arguments]]). Org can replace such references with the source code---or
-concatenation thereof--- being referenced, or with the results of an
-evaluation.
+Arguments]]). Org can replace such references with the source code of
+the block or blocks being referenced, or, in the case of a single
+source code block named with =NAME=, with the results of an
+evaluation of that block.
#+cindex: @samp{noweb}, header argument
The =noweb= header argument controls expansion of noweb syntax
@@ -18056,9 +18057,9 @@ the second code block is expanded as
,#+END_SRC
#+end_example
-You may also concatenate the contents of multiple blocks sharing
-a common =noweb-ref= header argument. For simple concatenation, set
-its value at the sub-tree or file level. In the example Org file
+You may also include the contents of multiple blocks sharing
+a common =noweb-ref= header argument, which can be set at the file,
+sub-tree, or code-block level. In the example Org file
shown next, the body of the source code in each block is extracted for
concatenation to a pure code file when tangled.
@@ -18091,19 +18092,19 @@ concatenation to a pure code file when tangled.
By default a newline separates each noweb reference concatenation. To
use a different separator, edit the =noweb-sep= header argument.
-Eventually, Org can include the results of evaluation of a single code
-block rather than its body. To that effect, append parentheses,
-possibly including arguments, to the code block name, as shown below.
+Alternatively, Org can include the results of evaluation of a single code
+block rather than its body. Evaluation occurs when parentheses,
+possibly including arguments, are appended to the code block name, as shown
below.
: <>
-Note that when using the above approach to a code block's results, the
+Note that in this case, a
code block name set by =NAME= keyword is required; the reference set
-by =noweb-ref= is not effective in that case.
+by =noweb-ref= will not work when evaluation is desired.
Here is an example that demonstrates how the exported content changes
when noweb style references are used with parentheses versus without.
-With:
+Given:
#+begin_example
,#+NAME: some-code
--
2.26.0
Re: babel/noweb concatenation of equally-named code blocks fails?
Greg Minshall writes: > two minor edits i might make to the first paragraph, 1) to make clear > that #+name: names only one block, and 2) to (maybe?) simplify the > latter part of the same paragraph, while, at the same time, trying to > keep a strong mention of the distinction between =NAME= and > =noweb-ref= at the top of the article. Your proposal is an improvement, indeed. Thank you. > additionally, i did some wordsmithing. i've appended a diff, hopefully > in a useful format (C-x C-v =); i'm not a git, git patch, expert. Could you use "git format-patch" and use a proper commit message? You may need to add TINYCHANGE at its end, if you haven't signed FSF papers yet. > i wonder if there might a place in this article to mention > org-babel-expand-src-block (C-c C-v v)? it is mentioned, tangentially, > later in the manual (but i only came across it recently). You are right, this is a serious omission in this part of the manual. Would you want to document it?
Re: babel/noweb concatenation of equally-named code blocks fails?
hi, Nicolas,
thanks, and sorry, i should have git-pull'd. the new version seems very
nice to me. two minor edits i might make to the first paragraph, 1) to
make clear that #+name: names only one block, and 2) to (maybe?)
simplify the latter part of the same paragraph, while, at the same time,
trying to keep a strong mention of the distinction between =NAME= and
=noweb-ref= at the top of the article.
additionally, i did some wordsmithing. i've appended a diff, hopefully
in a useful format (C-x C-v =); i'm not a git, git patch, expert.
i wonder if there might a place in this article to mention
org-babel-expand-src-block (C-c C-v v)? it is mentioned, tangentially,
later in the manual (but i only came across it recently).
cheers, Greg
diff --git a/doc/org-manual.org b/doc/org-manual.org
index 2a2700739..1c4a1f954 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -17988,12 +17988,13 @@ using a noweb[fn:145] style syntax:
: <>
#+texinfo: @noindent
-where {{{var(CODE-BLOCK-ID)}}} refers to either the =NAME= of
-a specific source code block, or a collection of source code blocks
+where {{{var(CODE-BLOCK-ID)}}} refers to either the =NAME= of
+a single source code block, or a collection of one or more source code blocks
sharing the same =noweb-ref= header argument (see [[*Using Header
-Arguments]]). Org can replace such references with the source code---or
-concatenation thereof--- being referenced, or with the results of an
-evaluation.
+Arguments]]). Org can replace such references with the source code of
+the block or blocks being referenced, or, in the case of a single
+source code block named with =NAME=, with the results of an
+evaluation of that block.
#+cindex: @samp{noweb}, header argument
The =noweb= header argument controls expansion of noweb syntax
@@ -18056,9 +18057,9 @@ the second code block is expanded as
,#+END_SRC
#+end_example
-You may also concatenate the contents of multiple blocks sharing
-a common =noweb-ref= header argument. For simple concatenation, set
-its value at the sub-tree or file level. In the example Org file
+You may also include the contents of multiple blocks sharing
+a common =noweb-ref= header argument, which can be set at the file,
+sub-tree, or code-block level. In the example Org file
shown next, the body of the source code in each block is extracted for
concatenation to a pure code file when tangled.
@@ -18091,19 +18092,19 @@ concatenation to a pure code file when tangled.
By default a newline separates each noweb reference concatenation. To
use a different separator, edit the =noweb-sep= header argument.
-Eventually, Org can include the results of evaluation of a single code
-block rather than its body. To that effect, append parentheses,
-possibly including arguments, to the code block name, as shown below.
+Alternatively, Org can include the results of evaluation of a single code
+block rather than its body. Evaluation occurs when parentheses,
+possibly including arguments, are appended to the code block name, as shown
below.
: <>
-Note that when using the above approach to a code block's results, the
+Note that in this case, a
code block name set by =NAME= keyword is required; the reference set
-by =noweb-ref= is not effective in that case.
+by =noweb-ref= will not work when evaluation is desired.
Here is an example that demonstrates how the exported content changes
when noweb style references are used with parentheses versus without.
-With:
+Given:
#+begin_example
,#+NAME: some-code
Re: babel/noweb concatenation of equally-named code blocks fails?
Hello, Greg Minshall writes: > Nicolas, > > thank you. wordsmithing opens up endless possibilities, so i don't know > that the following is at all an improvement on your suggestion. but, it > occurs to me to get the importance of =noweb-ref=, and its role in > concatenation, brought out early on the "page". Thank you. I certainly appreciate some help on documentation writing. The wording evolved a bit since you checked it. Just to be sure, you suggest to replace (I'm adding context here) Source code blocks can include references to other source code blocks, using a noweb[fn:145] style syntax: : <> where CODE-BLOCK-ID refers to either the NAME of a specific source code block, or a collection of source code blocks sharing the same noweb-ref header argument (see Using Header Arguments). Org can replace such references with the source code---or concatenation thereof--- being referenced, or with the results of an evaluation. The noweb header argument controls expansion of noweb syntax references. Expansions occur when source code blocks are evaluated, tangled, or exported. with Source code blocks can include references to other source code blocks, using a noweb style syntax: : <> where CODE-BLOCK-ID refers to either the NAME of a specific source code block, or a collection of source code blocks sharing the same noweb-ref header argument (see Using Header Arguments). Depending on the setting of the noweb header argument, Org will either ignore a noweb style reference, or will attempt to replace it. In the latter case, the replacement text will be either the source code from exactly *one* named source code block (using either a NAME keyword line, or a noweb-ref header argument), or a concatenation of one or more source code blocks, each with an identically named noweb-ref header argument. Expansions can only occur when source code blocks are evaluated, tangled, or exported. For more details, see below. The noweb header argument controls expansion of noweb syntax references. Expansions occur when source code blocks are evaluated, tangled, or exported. Note there's some duplication with the last paragraph. Can we avoid it? Also, I'm not sure we should insist on the fact that you can use a unique noweb-ref header argument as a code block ID: it is the slow path without any advantage over NAME keyword. I also suggest to replace Depending on the setting of the noweb header argument, Org will either ignore a noweb style reference, or will attempt to replace it. In the latter case, the replacement text will be either ... with Depending on the setting of the noweb header argument, Org either ignores the reference, or replaces it. In the latter case, the replacement text is ... I.e., I'm not a big fan of future tense in documentation, unless there's some grammar rule involved. But then, the following part: the source code from exactly *one* named source code block (using either a NAME keyword line, or a noweb-ref header argument), or a concatenation of one or more source code blocks, each with an identically named noweb-ref header argument. is redundant with the earlier CODE-BLOCK-ID refers to either the NAME of a specific source code block, or a collection of source code blocks sharing the same noweb-ref header argument This already explains that there are two ways for referencing code, as a single code block or as a collection of such blocks, and how to reference them. Can we re-use this to explain that replacement text is the consequence of that choice, instead of repeating ourselves? WDYT? Regards, -- Nicolas Goaziou
Re: babel/noweb concatenation of equally-named code blocks fails?
Nicolas, thank you. wordsmithing opens up endless possibilities, so i don't know that the following is at all an improvement on your suggestion. but, it occurs to me to get the importance of =noweb-ref=, and its role in concatenation, brought out early on the "page". one paragraph currently reads: Org can replace the Noweb style reference with the source code---or concatenation thereof---, or even the results of an evaluation, as detailed below. The =noweb= header argument controls expansion of Noweb syntax references. Expansions occur when source code blocks are evaluated, tangled, or exported. an alternative: Depending on the setting of the =noweb= header argument, Org will either ignore a Noweb style reference, or will attempt to replace it. In the latter case, the replacement text will be either the source code from exactly *one* named source code block (using either a #+name: line, or a =noweb-ref= header argument), or a concatentation of one or more source code blocks, each with an identically named =noweb-ref= header argument. Expansions can only occur when source code blocks are evaluated, tangled, or exported. For more details, see below. again, thanks. cheers, Greg
Re: babel/noweb concatenation of equally-named code blocks fails?
Hello, Greg Minshall writes: > thanks for the history! sounds like a good tradeoff. i agree, a bit > more documentation would be good. I sligthly reworded Noweb references section in the manual. Please let me know if that is clearer. Regards, -- Nicolas Goaziou
Re: babel/noweb concatenation of equally-named code blocks fails?
Nicolas, thanks for the history! sounds like a good tradeoff. i agree, a bit more documentation would be good. cheers, Greg
Re: babel/noweb concatenation of equally-named code blocks fails?
Greg Minshall writes: > Nicolas, thanks. i take it this is a change from (recent?) past > behavior? I think this was done between Org 9.1 and 9.2, the final step probably being 99dbca3d4f2fb30f35309a0bf4c324535b7dc9f3 > it was kind of nice the old way, but i suspect i'll get used > to the new way (no names, just noweb-ref) fairly soon. Mixing noweb-ref and names slowed down Noweb expansion very much. We papered over it using that odd variable: `org-babel-use-quick-and-dirty-noweb-expansion'. IOW, you had to choose between speed and accuracy when expanding Noweb blocks. Now, this is simpler: using NAME keyword is the fast path, with a single block. Using :noweb-ref is the slow path, but you can concatenate multiple blocks.
Re: babel/noweb concatenation of equally-named code blocks fails?
Nicolas, thanks. i take it this is a change from (recent?) past behavior? it was kind of nice the old way, but i suspect i'll get used to the new way (no names, just noweb-ref) fairly soon. cheers, Greg
Re: babel/noweb concatenation of equally-named code blocks fails?
Hello, Greg Minshall writes: > hi. the description of :noweb-ref says > > When expanding “noweb” style references, the bodies of all code block > with _either_ a block name matching the reference name _or_ a > ‘:noweb-ref’ header argument matching the reference name will be > concatenated together to form the replacement text. Yes this part of the manual is not particularly clear, I'll try to reformulate it. Anyway, names are assumed to be unique throughout a document. If you want to concatenate multiple blocks, you need to use :noweb-ref. HTH, -- Nicolas Goaziou
