[PATCH] noweb documentation update (Was: Re: How to use noweb reference with argument..)

[Kaushal Modi <kaushal.modi@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 2618 bytes --]

Hello list,

I have attached a patch (rebased off maint) that attempts at clarifying how
certain aspects of noweb work based on my experience, with few complete
examples.

Note: I had to also revert a little bit of wording change that was made
recently. I found pre-wording-change version easier to understand. Copying
Lambda Coder to comment on that.

This is what the current patch has in the "Noweb reference syntax section":

=====
It is possible to include the @emph{results} of a code block rather than the
body.  This is done by appending parentheses to the code block name which
may
optionally contain arguments to the code block as shown below.
=====

Earlier it was:

=====
Org can handle naming of @emph{results} block, rather than the body of the
@samp{src} code block, using ``noweb'' style references.

For ``noweb'' style reference, append parenthesis to the code block name for
arguments, as shown in this example:
=====


On Wed, Jun 21, 2017 at 12:57 AM, Kaushal Modi <kaushal.modi@gmail.com>
> wrote:
>
>>
>> I stand corrected; for the stuff that you are doing, I believe the code
>> block name needs to go to #+NAME instead of to :noweb-ref.
>>
>> Below works (Hit C-c C-c in the second source block and approve
>> evaluating that code block:
>>
>> * noweb reference with argument
>>
>> #+NAME: sh-print-something
>> #+BEGIN_SRC shell :var str=""
>> echo echo $str
>> #+END_SRC
>>
>> #+BEGIN_SRC shell :results output :noweb yes
>> echo "hello, "
>> <<sh-print-something(str="stardiviner")>>
>> #+END_SRC
>>
>> #+RESULTS:
>> : hello,
>> : stardiviner
>>
>> Changes:
>>
>> (1) Switched back to #+NAME from :noweb-ref. Looks like if you need to
>> pass args, the reference name needs to be a code block name because
>> <<foo(bar=1)>> inserts the *results* of the code block "foo", not "foo" as
>> it is.
>> (2) So in the first block, you need to have code that *outputs* "echo
>> $str" with $str set to your set arg.
>> (3) Use shell instead of sh.
>>
>> To stress the point of "<<foo(bar=1)>> inserts the *results*", even the
>> below would work the same way as we care about the results output by the
>> first block, not how those results are obtained.
>>
>> * noweb reference with argument
>>
>> #+NAME: sh-print-something
>> #+BEGIN_SRC python :var str="foo" :results output
>> print('echo "' + str + '"')
>> #+END_SRC
>>
>> #+RESULTS: sh-print-something
>> : echo "foo"
>>
>> #+BEGIN_SRC shell :results output :noweb yes
>> echo "hello, "
>> <<sh-print-something(str="stardiviner")>>
>> #+END_SRC
>>
>> #+RESULTS:
>> : hello,
>> : stardiviner
>>
>> --
>>
>> Kaushal Modi
>>
>
> --

Kaushal Modi

[-- Attachment #1.2: Type: text/html, Size: 4451 bytes --]

[-- Attachment #2: 0001-Improve-noweb-documentation.patch --]
[-- Type: application/octet-stream, Size: 4474 bytes --]

From cc6b2a65f1dee4b14a3536fad853075b489b7861 Mon Sep 17 00:00:00 2001
From: Kaushal Modi <kaushal.modi@gmail.com>
Date: Wed, 21 Jun 2017 12:49:46 -0400
Subject: [PATCH] Improve noweb documentation

* doc/org.texi (noweb, noweb-ref, Noweb reference syntax): Add
examples and improve wording.  Clarify the use of noweb style
references with code block arguments.
---
 doc/org.texi | 67 ++++++++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 52 insertions(+), 15 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index b722b5da93..41425978aa 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -16214,10 +16214,22 @@ Noweb insertions now honor prefix characters that appear before
 Because the @code{<<example>>} noweb reference appears behind the SQL comment
 syntax, each line of the expanded noweb reference will be commented.
 
+With
+
+@example
+#+NAME: example
+#+BEGIN_SRC text
+this is the
+multi-line body of example
+#+END_SRC
+@end example
+
 This @samp{src} code block:
 
 @example
+#+BEGIN_SRC sql :noweb yes
 -- <<example>>
+#+END_SRC
 @end example
 
 expands to:
@@ -16235,21 +16247,22 @@ them, inline noweb references are acceptable.
 @cindex @code{:noweb-ref}, src header argument
 
 When expanding ``noweb'' style references, Org concatenates @samp{src} code
-blocks by matching the reference name to either the block name or the
+blocks by matching the reference name to either the code block name or the
 @code{:noweb-ref} header argument.
 
 For simple concatenation, set this @code{:noweb-ref} header argument at the
 sub-tree or file 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.
+source code in each block is extracted for concatenation to a pure code file
+when tangled.
 
 @example
  #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh
    <<fullest-disk>>
  #+END_SRC
  * the mount point of the fullest disk
-   :PROPERTIES:
-   :header-args: :noweb-ref fullest-disk
-   :END:
+ :PROPERTIES:
+ :header-args: :noweb-ref fullest-disk
+ :END:
 
  ** query all mounted disks
  #+BEGIN_SRC sh
@@ -16756,25 +16769,49 @@ references in the @samp{src} code block before evaluation.
 For the header argument @code{:noweb no}, Org does not expand ``noweb'' style
 references in the @samp{src} code block before evaluation.
 
-The default is @code{:noweb no}.
+The default is @code{:noweb no}.  Org defaults to @code{:noweb no} so as not
+to cause errors in languages such as @samp{Ruby} where ``noweb'' syntax is
+equally valid characters.  For example, @code{<<arg>>}.  Change Org's default
+to @code{:noweb yes} for languages where there is no risk of confusion.
 
 Org offers a more flexible way to resolve ``noweb'' style references
 (@pxref{noweb-ref}).
 
-Org can handle naming of @emph{results} block, rather than the body of the
-@samp{src} code block, using ``noweb'' style references.
-
-For ``noweb'' style reference, append parenthesis to the code block name for
-arguments, as shown in this example:
+It is possible to include the @emph{results} of a code block rather than the
+body.  This is done by appending parentheses to the code block name which may
+optionally contain arguments to the code block as shown below.
 
 @example
 <<code-block-name(optional arguments)>>
 @end example
 
-Note: Org defaults to @code{:noweb no} so as not to cause errors in languages
-such as @samp{Ruby} where ``noweb'' syntax is equally valid characters.  For
-example, @code{<<arg>>}.  Change Org's default to @code{:noweb yes} for
-languages where there is no risk of confusion.
+Note that when using the above approach to a code block's results, the code
+block name set by @code{#+NAME} keyword is required; the reference set by
+@code{:noweb-ref} will not work.
+
+Here is an example org file where ``noweb'' style
+references are used with and without the parentheses.
+
+@example
+#+NAME: python3-print
+#+BEGIN_SRC python :var str="" :results output :exports none
+print(str)
+#+END_SRC
+
+#+BEGIN_SRC text :noweb yes
+In Python 3, with "str='foo'", "<<python3-print>>" would print:
+
+    <<python3-print(str="foo")>>
+#+END_SRC
+@end example
+
+Notice the difference in how they get exported:
+@example
+In Python 3, with "str='foo'", "print(str)" would print:
+
+    foo
+
+@end example
 
 For faster tangling of large Org mode files, set
 @code{org-babel-use-quick-and-dirty-noweb-expansion} variable to @code{t}.
-- 
2.13.0