babel/noweb concatenation of equally-named code blocks fails?

babel/noweb concatenation of equally-named code blocks fails?

[Greg Minshall]

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.
----
plus, this (admittedly old) page suggests this concatenation should
happen:
----
http://eschulte.github.io/org-scraps/scraps/2011-06-10-continued-code-blocks.html
----

if i evaluate (C-c C-c) "tryxx" below on the 9.1.9 which is in my emacs
(26.3), i get two lines of output (as shown).  if, using packages, i
"upgrade" to either of the following:
----
  org                9.3.6         available  gnu
  org                20200413      available  org
----
(and, also a 201912...), i only get the first output line ("in first
tryx").  (*tangling*, i get both code blocks.)

is the behavior in the newer versions intentional?  or, should i file a
bug?

cheers, and thanks.  and, these days, stay safe.  Greg

---- cut here ---
** continued code blocks
#+property: header-args :noweb yes

#+name: tryx
#+begin_src R
cat("in first tryx\n")
#+end_src

#+name: tryx
#+begin_src R
cat("in second tryx\n")
#+end_src

#+name: tryxx
#+begin_src R :results output
<<tryx>>
#+end_src

#+RESULTS: tryxx
: in first tryx
: in second tryx

Re: babel/noweb concatenation of equally-named code blocks fails?

[Nicolas Goaziou]

Hello,

Greg Minshall <minshall@umich.edu> 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

Re: babel/noweb concatenation of equally-named code blocks fails?

[Greg Minshall]

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?

[Nicolas Goaziou]

Greg Minshall <minshall@umich.edu> 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?

[Greg Minshall]

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?

[Nicolas Goaziou]

Hello,

Greg Minshall <minshall@umich.edu> 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?

[Greg Minshall]

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?

[Nicolas Goaziou]

Hello,

Greg Minshall <minshall@umich.edu> 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:

    : <<CODE-BLOCK-ID>>

    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:

    : <<CODE-BLOCK-ID>>

    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?

[Greg Minshall]

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:
 : <<CODE-BLOCK-ID>>
 
 #+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.
 
 : <<NAME(optional arguments)>>
 
-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?

[Nicolas Goaziou]

Greg Minshall <minshall@umich.edu> 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?

[Greg Minshall]

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 <minshall@acm.org>
Date: Wed, 22 Apr 2020 14:45:52 -0700
Subject: [PATCH] some clarification on <<noweb>>, #+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:
 : <<CODE-BLOCK-ID>>
 
 #+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.
 
 : <<NAME(optional arguments)>>
 
-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?

[Nicolas Goaziou]

Hello,

Greg Minshall <minshall@umich.edu> 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