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

[Kaushal Modi]

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 <address@hidden> 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

0001-Improve-noweb-documentation.patch
Description: Binary data