From: Greg Minshall <minshall@umich.edu>
To: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Cc: emacs-orgmode@gnu.org
Subject: Re: babel/noweb concatenation of equally-named code blocks fails?
Date: Wed, 22 Apr 2020 07:22:40 -0700 [thread overview]
Message-ID: <1279790.1587565360@apollo2.minshall.org> (raw)
In-Reply-To: Your message of "Wed, 22 Apr 2020 12:50:16 +0200." <875zdrokuv.fsf@nicolasgoaziou.fr>
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
next prev parent reply other threads:[~2020-04-22 14:23 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-04-19 20:07 babel/noweb concatenation of equally-named code blocks fails? Greg Minshall
2020-04-19 21:11 ` Nicolas Goaziou
2020-04-19 21:18 ` Greg Minshall
2020-04-19 21:53 ` Nicolas Goaziou
2020-04-19 23:06 ` Greg Minshall
2020-04-20 9:23 ` Nicolas Goaziou
2020-04-22 4:45 ` Greg Minshall
2020-04-22 10:50 ` Nicolas Goaziou
2020-04-22 14:22 ` Greg Minshall [this message]
2020-04-22 17:09 ` Nicolas Goaziou
2020-04-22 21:51 ` Greg Minshall
2020-04-23 8:43 ` Nicolas Goaziou
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=1279790.1587565360@apollo2.minshall.org \
--to=minshall@umich.edu \
--cc=emacs-orgmode@gnu.org \
--cc=mail@nicolasgoaziou.fr \
/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).