How to use noweb reference with argument in other languages?

How to use noweb reference with argument in other languages?

[numbchild]

[-- Attachment #1: Type: text/plain, Size: 1156 bytes --]

I found noweb reference with argument `<<src-block-name(args)>>` issue.

This can work:

```org
#+NAME: f1
#+BEGIN_SRC emacs-lisp :var x=7 :results value
  (+ x x)
#+END_SRC

#+RESULTS: f1
: 14

#+NAME: f2
#+BEGIN_SRC emacs-lisp :var x=7 :results value
  (+ x 2)
#+END_SRC

#+RESULTS: f2
: 9

#+name: intermediate
#+call: f1(x=5)

#+RESULTS: intermediate
: 10

#+call: f2(x=intermediate)

#+RESULTS:
: 12


#+name: intermediate
#+BEGIN_SRC emacs-lisp :noweb yes :results value
<<f1(x=5)>>
#+END_SRC

#+BEGIN_SRC emacs-lisp :noweb yes :results value
<<f2(x=intermediate)>>
#+END_SRC

#+RESULTS:
: 12
```

And this does not work:
```org
#+NAME: sh-print-something
#+BEGIN_SRC sh :var str=""
echo "$str"
#+END_SRC

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

#+RESULTS:
```

Why the first language `emacs-lisp` works, but second `sh` does not work?

[stardiviner]           <Hack this world!>      GPG key ID: 47C32433
IRC(freeenode): stardiviner                     Twitter:  @numbchild
Key fingerprint = 9BAA 92BC CDDD B9EF 3B36  CB99 B8C4 B8E5 47C3 2433
Blog: http://stardiviner.github.io/

[-- Attachment #2: Type: text/html, Size: 6550 bytes --]

Re: How to use noweb reference with argument in other languages?

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 802 bytes --]

On Mon, Jun 19, 2017, 12:59 AM numbchild@gmail.com <numbchild@gmail.com>
wrote:

> I found noweb reference with argument `<<src-block-name(args)>>` issue.
>

It has been working fine for me for org and sh source blocks.

And this does not work:
> ```org
> #+NAME: sh-print-something
> #+BEGIN_SRC sh :var str=""
> echo "$str"
> #+END_SRC
>
> #+BEGIN_SRC sh :results output :noweb yes
> echo "hello, "
> <<sh-print-something(str="stardiviner")>>
> #+END_SRC
>

You need to use :noweb-ref option  in the source blocks header args to set
the noweb-ref code reference; #+NAME will not work.

I have to have used noweb for the very first time in this recent project:
https://raw.githubusercontent.com/kaushalmodi/eless/master/eless.org ;
search for ":noweb-ref" in there to get an idea.

> --

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 2754 bytes --]

Re: How to use noweb reference with argument in other languages?

[numbchild]

[-- Attachment #1: Type: text/plain, Size: 1852 bytes --]

Which Org-mode version are you using? I'm using the latest Org-mode version
from source code branch `master`.

When I use your `:noweb-ref` style like this:

```org
* noweb reference with argument

#+BEGIN_SRC sh :var str="" :noweb-ref sh-print-something
echo "$str"
#+END_SRC

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

#+RESULTS:
```

Emacs reports error:

org-babel-ref-resolve: Reference ‘sh-print-something’ not found in this
buffer.

Org-mode version: Org mode version 9.0.8 (9.0.8-elpaplus @
/home/stardiviner/Code/Emacs/org-mode/lisp/)

[stardiviner]           <Hack this world!>      GPG key ID: 47C32433
IRC(freeenode): stardiviner                     Twitter:  @numbchild
Key fingerprint = 9BAA 92BC CDDD B9EF 3B36  CB99 B8C4 B8E5 47C3 2433
Blog: http://stardiviner.github.io/

On Mon, Jun 19, 2017 at 6:21 PM, Kaushal Modi <kaushal.modi@gmail.com>
wrote:

> On Mon, Jun 19, 2017, 12:59 AM numbchild@gmail.com <numbchild@gmail.com>
> wrote:
>
>> I found noweb reference with argument `<<src-block-name(args)>>` issue.
>>
>
> It has been working fine for me for org and sh source blocks.
>
> And this does not work:
>> ```org
>> #+NAME: sh-print-something
>> #+BEGIN_SRC sh :var str=""
>> echo "$str"
>> #+END_SRC
>>
>> #+BEGIN_SRC sh :results output :noweb yes
>> echo "hello, "
>> <<sh-print-something(str="stardiviner")>>
>> #+END_SRC
>>
>
> You need to use :noweb-ref option  in the source blocks header args to set
> the noweb-ref code reference; #+NAME will not work.
>
> I have to have used noweb for the very first time in this recent project:
> https://raw.githubusercontent.com/kaushalmodi/eless/master/eless.org ;
> search for ":noweb-ref" in there to get an idea.
>
>> --
>
> Kaushal Modi
>

[-- Attachment #2: Type: text/html, Size: 6328 bytes --]

Re: How to use noweb reference with argument in other languages?

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 2275 bytes --]

On Mon, Jun 19, 2017 at 7:41 PM numbchild@gmail.com <numbchild@gmail.com>
wrote:

> Which Org-mode version are you using? I'm using the latest Org-mode
> version from source code branch `master`.
>

I am using the same.


> When I use your `:noweb-ref` style like this:
>
> ```org
> * noweb reference with argument
>
> #+BEGIN_SRC sh :var str="" :noweb-ref sh-print-something
> echo "$str"
> #+END_SRC
>
> #+BEGIN_SRC sh :results output :noweb yes
> echo "hello, "
> <<sh-print-something(str="stardiviner")>>
> #+END_SRC
>
> #+RESULTS:
> ```
>
> Emacs reports error:
>
> org-babel-ref-resolve: Reference ‘sh-print-something’ not found in this
> buffer.
>
> Org-mode version: Org mode version 9.0.8 (9.0.8-elpaplus @
> /home/stardiviner/Code/Emacs/org-mode/lisp/)
>

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

[-- Attachment #2: Type: text/html, Size: 5373 bytes --]

Re: How to use noweb reference with argument in other languages?

[numbchild]

[-- Attachment #1: Type: text/plain, Size: 2805 bytes --]

This is correct now. Thanks very much. You're right.

[stardiviner]           <Hack this world!>      GPG key ID: 47C32433
IRC(freeenode): stardiviner                     Twitter:  @numbchild
Key fingerprint = 9BAA 92BC CDDD B9EF 3B36  CB99 B8C4 B8E5 47C3 2433
Blog: http://stardiviner.github.io/

On Wed, Jun 21, 2017 at 12:57 AM, Kaushal Modi <kaushal.modi@gmail.com>
wrote:

> On Mon, Jun 19, 2017 at 7:41 PM numbchild@gmail.com <numbchild@gmail.com>
> wrote:
>
>> Which Org-mode version are you using? I'm using the latest Org-mode
>> version from source code branch `master`.
>>
>
> I am using the same.
>
>
>> When I use your `:noweb-ref` style like this:
>>
>> ```org
>> * noweb reference with argument
>>
>> #+BEGIN_SRC sh :var str="" :noweb-ref sh-print-something
>> echo "$str"
>> #+END_SRC
>>
>> #+BEGIN_SRC sh :results output :noweb yes
>> echo "hello, "
>> <<sh-print-something(str="stardiviner")>>
>> #+END_SRC
>>
>> #+RESULTS:
>> ```
>>
>> Emacs reports error:
>>
>> org-babel-ref-resolve: Reference ‘sh-print-something’ not found in this
>> buffer.
>>
>> Org-mode version: Org mode version 9.0.8 (9.0.8-elpaplus @
>> /home/stardiviner/Code/Emacs/org-mode/lisp/)
>>
>
> 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
>

[-- Attachment #2: Type: text/html, Size: 6690 bytes --]

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

[Kaushal Modi]

[-- 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

Re: [PATCH] noweb documentation update

[Nicolas Goaziou]

Hello,

Kaushal Modi <kaushal.modi@gmail.com> writes:

> 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.

Thank you. Some comments follow.

> 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:
> =====

I agree the latter is less clear. However, I suggest less convoluted
wording:

    Org can include the @emph{results} of a code block rather than its
    body.  To that effect, append parentheses, possibly including
    arguments, to the code block name, as show below.


> -   :PROPERTIES:
> -   :header-args: :noweb-ref fullest-disk
> -   :END:
> + :PROPERTIES:
> + :header-args: :noweb-ref fullest-disk
> + :END:

I don't think the change above is meaningful here. Anyway it should be
consistent with other examples across the manual.

>   ** 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.

What about

    The default is @code{:noweb no}.  Org defaults to @code{:noweb no} so
    as not to cause errors in languages where ``noweb'' syntax is
    ambiguous.  For example, @samp{Ruby} language interprets
    @samp{<<arg>>} differently.  Change Org's default to @code{:noweb
    yes} for languages where there is no risk of confusion.

Note that I don't know what <<arg>> means in Ruby.

> -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.

See above.

> +Notice the difference in how they get exported:
> +@example
> +In Python 3, with "str='foo'", "print(str)" would print:
> +
> +    foo
> +
> +@end example

Would it be better to split it into two distinct examples?

Regards,

-- 
Nicolas Goaziou

Re: [PATCH] noweb documentation update

[Kaushal Modi]

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

Hello,

Thanks. My comments are below, and the updated patch is attached.

In addition to your suggestion:

- Replaced ``Noweb'' with ``noweb'' every where. I am still bugged by the
inconsistency that some places have ``noweb'' while some places have just
noweb (no quotes). Or would replacing all occurrences of ``noweb'' and
noweb with Noweb be better?

- Added more examples under "Noweb prefix lines" sub-heading.

On Thu, Jun 22, 2017 at 3:05 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> I agree the latter is less clear. However, I suggest less convoluted
> wording:
>
>     Org can include the @emph{results} of a code block rather than its
>     body.  To that effect, append parentheses, possibly including
>     arguments, to the code block name, as show below.
>

That's better, thanks.


> > -   :PROPERTIES:
> > -   :header-args: :noweb-ref fullest-disk
> > -   :END:
> > + :PROPERTIES:
> > + :header-args: :noweb-ref fullest-disk
> > + :END:
>
> I don't think the change above is meaningful here. Anyway it should be
> consistent with other examples across the manual.
>

I agree, that indentation change is reverted. By default everything is
left-flushed in org (except where you intend to have indented (see what I
did?) lists and such). So I removed that extra spaces from before the
property drawer. But I think all such property drawer instances in org.texi
have 2 leading spaces, so I will stick to that.


> What about
>
>     The default is @code{:noweb no}.  Org defaults to @code{:noweb no} so
>     as not to cause errors in languages where ``noweb'' syntax is
>     ambiguous.  For example, @samp{Ruby} language interprets
>     @samp{<<arg>>} differently.  Change Org's default to @code{:noweb
>     yes} for languages where there is no risk of confusion.
>

OK. I had simply moved the prior "Note"  as it was useful to have the
information about :noweb default in one place. I have reworded it as
suggested.

Note that I don't know what <<arg>> means in Ruby.
>

Neither do I. Hope this is fine -- I have removed that line as there is no
clear reference to that statement. Quick searching through this also
doesn't show anything like <<foo>>:
http://ruby-doc.com/docs/ProgrammingRuby/. Also this answer (
https://stackoverflow.com/a/6852104/1219634 ) has reference to "<<", but
all it says is that "<<" is an operator.. like in many other languages too.


> > +Notice the difference in how they get exported:
> > +@example
> > +In Python 3, with "str='foo'", "print(str)" would print:
> > +
> > +    foo
> > +
> > +@end example
>
> Would it be better to split it into two distinct examples?
>

Done.
-- 

Kaushal Modi

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

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

From 5264b282f8e72b10a92be47b2cbf71b5b04193d4 Mon Sep 17 00:00:00 2001
From: Kaushal Modi <kaushal.modi@gmail.com>
Date: Thu, 22 Jun 2017 14:52:32 -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 | 145 +++++++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 122 insertions(+), 23 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index b722b5da93..95808ea36d 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -16188,36 +16188,50 @@ code blocks are evaluated, tangled, or exported.
 
 @itemize @bullet
 @item @code{no}
-Default.  No expansion of ``Noweb'' syntax references in the body of the code
+Default.  No expansion of ``noweb'' syntax references in the body of the code
 when evaluating, tangling, or exporting.
 @item @code{yes}
-Expansion of ``Noweb'' syntax references in the body of the @samp{src} code
+Expansion of ``noweb'' syntax references in the body of the @samp{src} code
 block when evaluating, tangling, or exporting.
 @item @code{tangle}
-Expansion of ``Noweb'' syntax references in the body of the @samp{src} code
+Expansion of ``noweb'' syntax references in the body of the @samp{src} code
 block when tangling.  No expansion when evaluating or exporting.
 @item @code{no-export}
-Expansion of ``Noweb'' syntax references in the body of the @samp{src} code
+Expansion of ``noweb'' syntax references in the body of the @samp{src} code
 block when evaluating or tangling.  No expansion when exporting.
 @item @code{strip-export}
-Expansion of ``Noweb'' syntax references in the body of the @samp{src} code
+Expansion of ``noweb'' syntax references in the body of the @samp{src} code
 block when expanding prior to evaluating or tangling.  Removes ``noweb''
 syntax references when exporting.
 @item @code{eval}
-Expansion of ``Noweb'' syntax references in the body of the @samp{src} code
+Expansion of ``noweb'' syntax references in the body of the @samp{src} code
 block only before evaluating.
 @end itemize
 
 @subsubheading Noweb prefix lines
-Noweb insertions now honor prefix characters that appear before
-@code{<<reference>>}.  This behavior is illustrated in the following example.
-Because the @code{<<example>>} noweb reference appears behind the SQL comment
-syntax, each line of the expanded noweb reference will be commented.
+Noweb insertions now honor prefix characters that appear before the ``noweb''
+syntax reference.
 
-This @samp{src} code block:
+This behavior is illustrated in the following example.  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:
@@ -16230,17 +16244,60 @@ expands to:
 Since this change will not affect noweb replacement text without newlines in
 them, inline noweb references are acceptable.
 
+This feature can also be used for management of indentation in exported code snippets.
+
+With:
+
+@example
+#+NAME: if-true
+#+BEGIN_SRC python :exports none
+print('Do things when True')
+#+END_SRC
+
+#+NAME: if-false
+#+BEGIN_SRC python :exports none
+print('Do things when False')
+#+END_SRC
+@end example
+
+this @samp{src} code block:
+
+@example
+#+BEGIN_SRC python :noweb yes :results output
+if True:
+    <<if-true>>
+else:
+    <<if-false>>
+#+END_SRC
+@end example
+
+expands to:
+
+@example
+if True:
+    print('Do things when True')
+else:
+    print('Do things when False')
+@end example
+
+and evaluates to:
+
+@example
+Do things when True
+@end example
+
 @node noweb-ref
 @subsubsection @code{:noweb-ref}
 @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
@@ -16756,25 +16813,67 @@ 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 where ``noweb'' syntax is ambiguous.  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:
+Org can include the @emph{results} of a code block rather than its body.  To
+that effect, append parentheses, possibly including arguments, to the code
+block name, as show 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 that demonstrates how the exported content changes when
+``noweb'' style references are used with parentheses versus without.
+
+With
+
+@example
+#+NAME: some-code
+#+BEGIN_SRC python :var num=0 :results output :exports none
+print(num*10)
+#+END_SRC
+@end example
+
+This code block:
+
+@example
+#+BEGIN_SRC text :noweb yes
+<<some-code>>
+#+END_SRC
+@end example
+
+expands to:
+
+@example
+print(num*10)
+@end example
+
+Below, a similar ``noweb'' style reference is used, but with parentheses,
+while setting a variable ~num~ to 10:
+
+@example
+#+BEGIN_SRC text :noweb yes
+<<some-code(num=10)>>
+#+END_SRC
+@end example
+
+Note that now the expansion contains the @emph{results} of the code block
+@code{some-code}, not the code block itself:
+
+@example
+100
+@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

Re: [PATCH] noweb documentation update

[Kaushal Modi]

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

A quick update.. the attached patch has minor formatting fixes over the
previous one.

Please use this patch for review.

Thanks.

On Thu, Jun 22, 2017 at 3:01 PM Kaushal Modi <kaushal.modi@gmail.com> wrote:

> Hello,
>
> Thanks. My comments are below, and the updated patch is attached.
>
-- 

Kaushal Modi

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

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

From 9580d645d001defb098d83f90d58e6a36f6220e3 Mon Sep 17 00:00:00 2001
From: Kaushal Modi <kaushal.modi@gmail.com>
Date: Thu, 22 Jun 2017 14:52:32 -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 | 145 +++++++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 122 insertions(+), 23 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index b722b5da93..d41a28998a 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -16188,36 +16188,50 @@ code blocks are evaluated, tangled, or exported.
 
 @itemize @bullet
 @item @code{no}
-Default.  No expansion of ``Noweb'' syntax references in the body of the code
+Default.  No expansion of ``noweb'' syntax references in the body of the code
 when evaluating, tangling, or exporting.
 @item @code{yes}
-Expansion of ``Noweb'' syntax references in the body of the @samp{src} code
+Expansion of ``noweb'' syntax references in the body of the @samp{src} code
 block when evaluating, tangling, or exporting.
 @item @code{tangle}
-Expansion of ``Noweb'' syntax references in the body of the @samp{src} code
+Expansion of ``noweb'' syntax references in the body of the @samp{src} code
 block when tangling.  No expansion when evaluating or exporting.
 @item @code{no-export}
-Expansion of ``Noweb'' syntax references in the body of the @samp{src} code
+Expansion of ``noweb'' syntax references in the body of the @samp{src} code
 block when evaluating or tangling.  No expansion when exporting.
 @item @code{strip-export}
-Expansion of ``Noweb'' syntax references in the body of the @samp{src} code
+Expansion of ``noweb'' syntax references in the body of the @samp{src} code
 block when expanding prior to evaluating or tangling.  Removes ``noweb''
 syntax references when exporting.
 @item @code{eval}
-Expansion of ``Noweb'' syntax references in the body of the @samp{src} code
+Expansion of ``noweb'' syntax references in the body of the @samp{src} code
 block only before evaluating.
 @end itemize
 
 @subsubheading Noweb prefix lines
-Noweb insertions now honor prefix characters that appear before
-@code{<<reference>>}.  This behavior is illustrated in the following example.
-Because the @code{<<example>>} noweb reference appears behind the SQL comment
-syntax, each line of the expanded noweb reference will be commented.
+Noweb insertions now honor prefix characters that appear before the ``noweb''
+syntax reference.
 
-This @samp{src} code block:
+This behavior is illustrated in the following example.  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:
@@ -16230,17 +16244,60 @@ expands to:
 Since this change will not affect noweb replacement text without newlines in
 them, inline noweb references are acceptable.
 
+This feature can also be used for management of indentation in exported code snippets.
+
+With:
+
+@example
+#+NAME: if-true
+#+BEGIN_SRC python :exports none
+print('Do things when True')
+#+END_SRC
+
+#+NAME: if-false
+#+BEGIN_SRC python :exports none
+print('Do things when False')
+#+END_SRC
+@end example
+
+this @samp{src} code block:
+
+@example
+#+BEGIN_SRC python :noweb yes :results output
+if True:
+    <<if-true>>
+else:
+    <<if-false>>
+#+END_SRC
+@end example
+
+expands to:
+
+@example
+if True:
+    print('Do things when True')
+else:
+    print('Do things when False')
+@end example
+
+and evaluates to:
+
+@example
+Do things when True
+@end example
+
 @node noweb-ref
 @subsubsection @code{:noweb-ref}
 @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
@@ -16756,25 +16813,67 @@ 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 where ``noweb'' syntax is ambiguous.  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:
+Org can include the @emph{results} of a code block rather than its body.  To
+that effect, append parentheses, possibly including arguments, to the code
+block name, as show 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 that demonstrates how the exported content changes when
+``noweb'' style references are used with parentheses versus without.
+
+With:
+
+@example
+#+NAME: some-code
+#+BEGIN_SRC python :var num=0 :results output :exports none
+print(num*10)
+#+END_SRC
+@end example
+
+this code block:
+
+@example
+#+BEGIN_SRC text :noweb yes
+<<some-code>>
+#+END_SRC
+@end example
+
+expands to:
+
+@example
+print(num*10)
+@end example
+
+Below, a similar ``noweb'' style reference is used, but with parentheses,
+while setting a variable @code{num} to 10:
+
+@example
+#+BEGIN_SRC text :noweb yes
+<<some-code(num=10)>>
+#+END_SRC
+@end example
+
+Note that now the expansion contains the @emph{results} of the code block
+@code{some-code}, not the code block itself:
+
+@example
+100
+@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

Re: [PATCH] noweb documentation update

[Nicolas Goaziou]

Hello,

Kaushal Modi <kaushal.modi@gmail.com> writes:

> A quick update.. the attached patch has minor formatting fixes over the
> previous one.

Thank you. It looks good.

However, I think we can write Noweb, i.e., without quotes, like Emacs,
Org or MobileOrg. Quotes impedes reading process, IMO.

WDYT?

Regards,

-- 
Nicolas Goaziou

Re: [PATCH] noweb documentation update

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 509 bytes --]

On Thu, Jun 22, 2017 at 3:58 PM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> > A quick update.. the attached patch has minor formatting fixes over the
> > previous one.
>
> Thank you. It looks good.
>
> However, I think we can write Noweb, i.e., without quotes, like Emacs,
> Org or MobileOrg. Quotes impedes reading process, IMO.
>
> WDYT?
>

> Or would replacing all occurrences of ``noweb'' and noweb with Noweb be
better?

Exactly! :)


OK to push this after that change?

Thanks.
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 1249 bytes --]

Re: [PATCH] noweb documentation update

[Nicolas Goaziou]

Kaushal Modi <kaushal.modi@gmail.com> writes:

> OK to push this after that change?

Sure, go ahead. Thank you.

Regards,

Re: [PATCH] noweb documentation update

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 147 bytes --]

On Fri, Jun 23, 2017, 1:56 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

>
> Sure, go ahead. Thank you.
>

Thanks, done.

> --

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 626 bytes --]