From mboxrd@z Thu Jan 1 00:00:00 1970 From: Kaushal Modi Subject: [PATCH] noweb documentation update (Was: Re: How to use noweb reference with argument..) Date: Wed, 21 Jun 2017 16:57:31 +0000 Message-ID: References: Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="001a1147278240a04d05527b4425" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:45429) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dNiws-0006je-GT for emacs-orgmode@gnu.org; Wed, 21 Jun 2017 12:57:47 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dNiwr-0003jv-7j for emacs-orgmode@gnu.org; Wed, 21 Jun 2017 12:57:46 -0400 Received: from mail-lf0-x232.google.com ([2a00:1450:4010:c07::232]:35571) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dNiwq-0003jd-P3 for emacs-orgmode@gnu.org; Wed, 21 Jun 2017 12:57:45 -0400 Received: by mail-lf0-x232.google.com with SMTP id p189so100929255lfe.2 for ; Wed, 21 Jun 2017 09:57:44 -0700 (PDT) In-Reply-To: List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: emacs-org list Cc: sjLambda@gmail.com --001a1147278240a04d05527b4425 Content-Type: multipart/alternative; boundary="001a1147278240a04a05527b4423" --001a1147278240a04a05527b4423 Content-Type: text/plain; charset="UTF-8" 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 > 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, " >> <> >> #+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 >> <> 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 "<> 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, " >> <> >> #+END_SRC >> >> #+RESULTS: >> : hello, >> : stardiviner >> >> -- >> >> Kaushal Modi >> > > -- Kaushal Modi --001a1147278240a04a05527b4423 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Hello list,

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

Note: I had to also revert a little bit of wording change that was ma= de recently. I found pre-wording-change version easier to understand. Copyi= ng Lambda Coder to comment on that.

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

=3D=3D=3D=3D=3D
It is possible to incl= ude the @emph{results} of a code block rather than the
body.=C2= =A0 This is done by appending parentheses to the code block name which may<= /div>
optionally contain arguments to the code block as shown below.
=3D=3D=3D=3D=3D=C2=A0
=C2=A0
Earlier = it was:

=3D=3D=3D=3D=3D
Org can han= dle naming of @emph{results} block, rather than the body of the
@= samp{src} code block, using ``noweb'' style references.
<= br>
For ``noweb'' style reference, append parenthesis to = the code block name for
arguments, as shown in this example:
=3D=3D=3D=3D=3D=C2=A0=C2=A0


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 in= stead of to :noweb-ref.

Below works (Hit C-c C-c i= n the second source block and approve evaluating that code block:

* noweb reference with argument
<= br>
#+NAME: sh-print-something
#+BEGIN_SRC shell= :var str=3D""
echo echo $str
#+END_SRC
=

#+BEGIN_SRC shell :results output :noweb yes
echo "hello, "
<<sh-print-something(str=3D&= quot;stardiviner")>>
#+END_SRC

#+RESULTS:
: hello,
: stardiviner
<= /div>

Changes:

(1) Switched bac= k to #+NAME from :noweb-ref. Looks like if you need to pass args, the refer= ence name needs to be a code block name because <<foo(bar=3D1)>>= ; inserts the *results* of the code block "foo", not "foo&qu= ot; as it is.
(2) So in the first block, you need to have code th= at *outputs* "echo $str" with $str set to your set arg.
(3) Use shell instead of sh.

To stress the point = of "<<foo(bar=3D1)>> inserts the *results*", even the= below would work the same way as we care about the results output by the f= irst block, not how those results are obtained.

* noweb reference with argument

#+= NAME: sh-print-something
#+BEGIN_SRC python :var str=3D"foo&= quot; :results output
print('echo "' + str + '&q= uot;')
#+END_SRC

#+RESULTS: sh-print= -something
: echo "foo"

#+BEGI= N_SRC shell :results output :noweb yes
echo "hello, &q= uot;
<<sh-print-something(str=3D"stardiviner")>= ;>
#+END_SRC

#+RESULTS:
<= div>: hello,=C2=A0
: stardiviner

--

Kaushal Modi


<= div dir=3D"ltr">--

Kaushal Modi

--001a1147278240a04a05527b4423-- --001a1147278240a04d05527b4425 Content-Type: application/octet-stream; name="0001-Improve-noweb-documentation.patch" Content-Disposition: attachment; filename="0001-Improve-noweb-documentation.patch" Content-Transfer-Encoding: base64 Content-ID: <15ccb95d4e3b9645c391> X-Attachment-Id: 15ccb95d4e3b9645c391 RnJvbSBjYzZiMmE2NWYxZGVlNGIxNGEzNTM2ZmFkODUzMDc1YjQ4OWI3ODYxIE1vbiBTZXAgMTcg MDA6MDA6MDAgMjAwMQpGcm9tOiBLYXVzaGFsIE1vZGkgPGthdXNoYWwubW9kaUBnbWFpbC5jb20+ CkRhdGU6IFdlZCwgMjEgSnVuIDIwMTcgMTI6NDk6NDYgLTA0MDAKU3ViamVjdDogW1BBVENIXSBJ bXByb3ZlIG5vd2ViIGRvY3VtZW50YXRpb24KCiogZG9jL29yZy50ZXhpIChub3dlYiwgbm93ZWIt cmVmLCBOb3dlYiByZWZlcmVuY2Ugc3ludGF4KTogQWRkCmV4YW1wbGVzIGFuZCBpbXByb3ZlIHdv cmRpbmcuICBDbGFyaWZ5IHRoZSB1c2Ugb2Ygbm93ZWIgc3R5bGUKcmVmZXJlbmNlcyB3aXRoIGNv ZGUgYmxvY2sgYXJndW1lbnRzLgotLS0KIGRvYy9vcmcudGV4aSB8IDY3ICsrKysrKysrKysrKysr KysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKystLS0tLS0tLS0tLS0tLQogMSBmaWxlIGNo YW5nZWQsIDUyIGluc2VydGlvbnMoKyksIDE1IGRlbGV0aW9ucygtKQoKZGlmZiAtLWdpdCBhL2Rv Yy9vcmcudGV4aSBiL2RvYy9vcmcudGV4aQppbmRleCBiNzIyYjVkYTkzLi40MTQyNTk3OGFhIDEw MDY0NAotLS0gYS9kb2Mvb3JnLnRleGkKKysrIGIvZG9jL29yZy50ZXhpCkBAIC0xNjIxNCwxMCAr MTYyMTQsMjIgQEAgTm93ZWIgaW5zZXJ0aW9ucyBub3cgaG9ub3IgcHJlZml4IGNoYXJhY3RlcnMg dGhhdCBhcHBlYXIgYmVmb3JlCiBCZWNhdXNlIHRoZSBAY29kZXs8PGV4YW1wbGU+Pn0gbm93ZWIg cmVmZXJlbmNlIGFwcGVhcnMgYmVoaW5kIHRoZSBTUUwgY29tbWVudAogc3ludGF4LCBlYWNoIGxp bmUgb2YgdGhlIGV4cGFuZGVkIG5vd2ViIHJlZmVyZW5jZSB3aWxsIGJlIGNvbW1lbnRlZC4KIAor V2l0aAorCitAZXhhbXBsZQorIytOQU1FOiBleGFtcGxlCisjK0JFR0lOX1NSQyB0ZXh0Cit0aGlz IGlzIHRoZQorbXVsdGktbGluZSBib2R5IG9mIGV4YW1wbGUKKyMrRU5EX1NSQworQGVuZCBleGFt cGxlCisKIFRoaXMgQHNhbXB7c3JjfSBjb2RlIGJsb2NrOgogCiBAZXhhbXBsZQorIytCRUdJTl9T UkMgc3FsIDpub3dlYiB5ZXMKIC0tIDw8ZXhhbXBsZT4+CisjK0VORF9TUkMKIEBlbmQgZXhhbXBs ZQogCiBleHBhbmRzIHRvOgpAQCAtMTYyMzUsMjEgKzE2MjQ3LDIyIEBAIHRoZW0sIGlubGluZSBu b3dlYiByZWZlcmVuY2VzIGFyZSBhY2NlcHRhYmxlLgogQGNpbmRleCBAY29kZXs6bm93ZWItcmVm fSwgc3JjIGhlYWRlciBhcmd1bWVudAogCiBXaGVuIGV4cGFuZGluZyBgYG5vd2ViJycgc3R5bGUg cmVmZXJlbmNlcywgT3JnIGNvbmNhdGVuYXRlcyBAc2FtcHtzcmN9IGNvZGUKLWJsb2NrcyBieSBt YXRjaGluZyB0aGUgcmVmZXJlbmNlIG5hbWUgdG8gZWl0aGVyIHRoZSBibG9jayBuYW1lIG9yIHRo ZQorYmxvY2tzIGJ5IG1hdGNoaW5nIHRoZSByZWZlcmVuY2UgbmFtZSB0byBlaXRoZXIgdGhlIGNv ZGUgYmxvY2sgbmFtZSBvciB0aGUKIEBjb2Rlezpub3dlYi1yZWZ9IGhlYWRlciBhcmd1bWVudC4K IAogRm9yIHNpbXBsZSBjb25jYXRlbmF0aW9uLCBzZXQgdGhpcyBAY29kZXs6bm93ZWItcmVmfSBo ZWFkZXIgYXJndW1lbnQgYXQgdGhlCiBzdWItdHJlZSBvciBmaWxlIGxldmVsLiAgSW4gdGhlIGV4 YW1wbGUgT3JnIGZpbGUgc2hvd24gbmV4dCwgdGhlIGJvZHkgb2YgdGhlCi1zb3VyY2UgY29kZSBp biBlYWNoIGJsb2NrIGlzIGV4dHJhY3RlZCBmb3IgY29uY2F0ZW5hdGlvbiB0byBhIHB1cmUgY29k ZSBmaWxlLgorc291cmNlIGNvZGUgaW4gZWFjaCBibG9jayBpcyBleHRyYWN0ZWQgZm9yIGNvbmNh dGVuYXRpb24gdG8gYSBwdXJlIGNvZGUgZmlsZQord2hlbiB0YW5nbGVkLgogCiBAZXhhbXBsZQog ICMrQkVHSU5fU1JDIHNoIDp0YW5nbGUgeWVzIDpub3dlYiB5ZXMgOnNoZWJhbmcgIyEvYmluL3No CiAgICA8PGZ1bGxlc3QtZGlzaz4+CiAgIytFTkRfU1JDCiAgKiB0aGUgbW91bnQgcG9pbnQgb2Yg dGhlIGZ1bGxlc3QgZGlzawotICAgOlBST1BFUlRJRVM6Ci0gICA6aGVhZGVyLWFyZ3M6IDpub3dl Yi1yZWYgZnVsbGVzdC1kaXNrCi0gICA6RU5EOgorIDpQUk9QRVJUSUVTOgorIDpoZWFkZXItYXJn czogOm5vd2ViLXJlZiBmdWxsZXN0LWRpc2sKKyA6RU5EOgogCiAgKiogcXVlcnkgYWxsIG1vdW50 ZWQgZGlza3MKICAjK0JFR0lOX1NSQyBzaApAQCAtMTY3NTYsMjUgKzE2NzY5LDQ5IEBAIHJlZmVy ZW5jZXMgaW4gdGhlIEBzYW1we3NyY30gY29kZSBibG9jayBiZWZvcmUgZXZhbHVhdGlvbi4KIEZv ciB0aGUgaGVhZGVyIGFyZ3VtZW50IEBjb2Rlezpub3dlYiBub30sIE9yZyBkb2VzIG5vdCBleHBh bmQgYGBub3dlYicnIHN0eWxlCiByZWZlcmVuY2VzIGluIHRoZSBAc2FtcHtzcmN9IGNvZGUgYmxv Y2sgYmVmb3JlIGV2YWx1YXRpb24uCiAKLVRoZSBkZWZhdWx0IGlzIEBjb2Rlezpub3dlYiBub30u CitUaGUgZGVmYXVsdCBpcyBAY29kZXs6bm93ZWIgbm99LiAgT3JnIGRlZmF1bHRzIHRvIEBjb2Rl ezpub3dlYiBub30gc28gYXMgbm90Cit0byBjYXVzZSBlcnJvcnMgaW4gbGFuZ3VhZ2VzIHN1Y2gg YXMgQHNhbXB7UnVieX0gd2hlcmUgYGBub3dlYicnIHN5bnRheCBpcworZXF1YWxseSB2YWxpZCBj aGFyYWN0ZXJzLiAgRm9yIGV4YW1wbGUsIEBjb2Rlezw8YXJnPj59LiAgQ2hhbmdlIE9yZydzIGRl ZmF1bHQKK3RvIEBjb2Rlezpub3dlYiB5ZXN9IGZvciBsYW5ndWFnZXMgd2hlcmUgdGhlcmUgaXMg bm8gcmlzayBvZiBjb25mdXNpb24uCiAKIE9yZyBvZmZlcnMgYSBtb3JlIGZsZXhpYmxlIHdheSB0 byByZXNvbHZlIGBgbm93ZWInJyBzdHlsZSByZWZlcmVuY2VzCiAoQHB4cmVme25vd2ViLXJlZn0p LgogCi1PcmcgY2FuIGhhbmRsZSBuYW1pbmcgb2YgQGVtcGh7cmVzdWx0c30gYmxvY2ssIHJhdGhl ciB0aGFuIHRoZSBib2R5IG9mIHRoZQotQHNhbXB7c3JjfSBjb2RlIGJsb2NrLCB1c2luZyBgYG5v d2ViJycgc3R5bGUgcmVmZXJlbmNlcy4KLQotRm9yIGBgbm93ZWInJyBzdHlsZSByZWZlcmVuY2Us IGFwcGVuZCBwYXJlbnRoZXNpcyB0byB0aGUgY29kZSBibG9jayBuYW1lIGZvcgotYXJndW1lbnRz LCBhcyBzaG93biBpbiB0aGlzIGV4YW1wbGU6CitJdCBpcyBwb3NzaWJsZSB0byBpbmNsdWRlIHRo ZSBAZW1waHtyZXN1bHRzfSBvZiBhIGNvZGUgYmxvY2sgcmF0aGVyIHRoYW4gdGhlCitib2R5LiAg VGhpcyBpcyBkb25lIGJ5IGFwcGVuZGluZyBwYXJlbnRoZXNlcyB0byB0aGUgY29kZSBibG9jayBu YW1lIHdoaWNoIG1heQorb3B0aW9uYWxseSBjb250YWluIGFyZ3VtZW50cyB0byB0aGUgY29kZSBi bG9jayBhcyBzaG93biBiZWxvdy4KIAogQGV4YW1wbGUKIDw8Y29kZS1ibG9jay1uYW1lKG9wdGlv bmFsIGFyZ3VtZW50cyk+PgogQGVuZCBleGFtcGxlCiAKLU5vdGU6IE9yZyBkZWZhdWx0cyB0byBA Y29kZXs6bm93ZWIgbm99IHNvIGFzIG5vdCB0byBjYXVzZSBlcnJvcnMgaW4gbGFuZ3VhZ2VzCi1z dWNoIGFzIEBzYW1we1J1Ynl9IHdoZXJlIGBgbm93ZWInJyBzeW50YXggaXMgZXF1YWxseSB2YWxp ZCBjaGFyYWN0ZXJzLiAgRm9yCi1leGFtcGxlLCBAY29kZXs8PGFyZz4+fS4gIENoYW5nZSBPcmcn cyBkZWZhdWx0IHRvIEBjb2Rlezpub3dlYiB5ZXN9IGZvcgotbGFuZ3VhZ2VzIHdoZXJlIHRoZXJl IGlzIG5vIHJpc2sgb2YgY29uZnVzaW9uLgorTm90ZSB0aGF0IHdoZW4gdXNpbmcgdGhlIGFib3Zl IGFwcHJvYWNoIHRvIGEgY29kZSBibG9jaydzIHJlc3VsdHMsIHRoZSBjb2RlCitibG9jayBuYW1l IHNldCBieSBAY29kZXsjK05BTUV9IGtleXdvcmQgaXMgcmVxdWlyZWQ7IHRoZSByZWZlcmVuY2Ug c2V0IGJ5CitAY29kZXs6bm93ZWItcmVmfSB3aWxsIG5vdCB3b3JrLgorCitIZXJlIGlzIGFuIGV4 YW1wbGUgb3JnIGZpbGUgd2hlcmUgYGBub3dlYicnIHN0eWxlCityZWZlcmVuY2VzIGFyZSB1c2Vk IHdpdGggYW5kIHdpdGhvdXQgdGhlIHBhcmVudGhlc2VzLgorCitAZXhhbXBsZQorIytOQU1FOiBw eXRob24zLXByaW50CisjK0JFR0lOX1NSQyBweXRob24gOnZhciBzdHI9IiIgOnJlc3VsdHMgb3V0 cHV0IDpleHBvcnRzIG5vbmUKK3ByaW50KHN0cikKKyMrRU5EX1NSQworCisjK0JFR0lOX1NSQyB0 ZXh0IDpub3dlYiB5ZXMKK0luIFB5dGhvbiAzLCB3aXRoICJzdHI9J2ZvbyciLCAiPDxweXRob24z LXByaW50Pj4iIHdvdWxkIHByaW50OgorCisgICAgPDxweXRob24zLXByaW50KHN0cj0iZm9vIik+ PgorIytFTkRfU1JDCitAZW5kIGV4YW1wbGUKKworTm90aWNlIHRoZSBkaWZmZXJlbmNlIGluIGhv dyB0aGV5IGdldCBleHBvcnRlZDoKK0BleGFtcGxlCitJbiBQeXRob24gMywgd2l0aCAic3RyPSdm b28nIiwgInByaW50KHN0cikiIHdvdWxkIHByaW50OgorCisgICAgZm9vCisKK0BlbmQgZXhhbXBs ZQogCiBGb3IgZmFzdGVyIHRhbmdsaW5nIG9mIGxhcmdlIE9yZyBtb2RlIGZpbGVzLCBzZXQKIEBj b2Rle29yZy1iYWJlbC11c2UtcXVpY2stYW5kLWRpcnR5LW5vd2ViLWV4cGFuc2lvbn0gdmFyaWFi bGUgdG8gQGNvZGV7dH0uCi0tIAoyLjEzLjAKCg== --001a1147278240a04d05527b4425--