From 53e9c7b89d5c10bd5bc218a30eb47ce3c72556b6 Mon Sep 17 00:00:00 2001 From: Nicolas Goaziou Date: Mon, 20 Apr 2020 11:19:50 +0200 Subject: [PATCH] manual: Clarify Noweb references section * doc/org-manual.org (Noweb Reference Syntax): Clarify Noweb references section. In particular, insist on the different uses for NAME keyword and :noweb-ref header arguments. --- doc/org-manual.org | 192 +++++++++++++++++++++++---------------------- 1 file changed, 97 insertions(+), 95 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 3e659fcc2..5bdf2c43f 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -17904,17 +17904,22 @@ for Python and Emacs Lisp languages. #+cindex: syntax, Noweb #+cindex: source code, Noweb reference +#+cindex: @samp{noweb-ref}, header argument Org supports named blocks in Noweb[fn:144] style syntax: : <> -Org can replace the construct with the source code, or the results of -evaluation, of the code block identified as {{{var(CODE-BLOCK-ID)}}}. +where {{{var(CODE-BLOCK-ID)}}} refers to either the =NAME= of +a specific source code block, or a collection of source code blocks +sharing the same =noweb-ref= header argument (see [[*Using Header +Arguments]]). #+cindex: @samp{noweb}, header argument -The =noweb= header argument controls expansion of Noweb syntax -references. Expansions occur when source code blocks are evaluated, -tangled, or exported. +Org can replace the Noweb style reference with the source code---or +concatenation thereof---, or even the results of an evaluation, as +detailed below. The =noweb= header argument controls expansion of +Noweb syntax references. Expansions occur when source code blocks are +evaluated, tangled, or exported. - =no= :: @@ -17947,7 +17952,8 @@ tangled, or exported. Expansion of Noweb syntax references in the body of the code block only before evaluating. -In the following example, +In the most simple case, the contents of a single source block is +inserted within other blocks. Thus, in following example, #+begin_example ,#+NAME: initialization @@ -17971,6 +17977,91 @@ 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 +shown next, the body of the source code in each block is extracted for +concatenation to a pure code file when tangled. + +#+begin_example +,#+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh + <> +,#+END_SRC +,* the mount point of the fullest disk + :PROPERTIES: + :header-args: :noweb-ref fullest-disk + :END: + +,** query all mounted disks +,#+BEGIN_SRC sh + df \ +,#+END_SRC + +,** strip the header row +,#+BEGIN_SRC sh + |sed '1d' \ +,#+END_SRC + +,** output mount point of fullest disk +,#+BEGIN_SRC sh + |awk '{if (u < +$5) {u = +$5; m = $6}} END {print m}' +,#+END_SRC +#+end_example + +#+cindex: @samp{noweb-sep}, header argument +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. + +: <> + +Note that when using the above approach to a code block's results, the +code block name set by =NAME= keyword is required; the reference set +by =noweb-ref= is not effective in that case. + +Here is an example that demonstrates how the exported content changes +when Noweb style references are used with parentheses versus without. +With: + +#+begin_example +,#+NAME: some-code +,#+BEGIN_SRC python :var num=0 :results output :exports none + print(num*10) +,#+END_SRC +#+end_example + +#+texinfo: @noindent +this code block: + +#+begin_example +,#+BEGIN_SRC text :noweb yes + <> +,#+END_SRC +#+end_example + +#+texinfo: @noindent +expands to: + +: print(num*10) + +Below, a similar Noweb style reference is used, but with parentheses, +while setting a variable =num= to 10: + +#+begin_example +,#+BEGIN_SRC text :noweb yes + <> +,#+END_SRC +#+end_example + +#+texinfo: @noindent +Note that the expansion now contains the results of the code block +=some-code=, not the code block itself: + +: 100 + Noweb insertions honor prefix characters that appear before the Noweb syntax reference. This behavior is illustrated in the following example. Because the =<>= Noweb reference appears behind the @@ -18044,95 +18135,6 @@ else: print('do things when false') #+end_example -#+cindex: @samp{noweb-ref}, header argument -When expanding Noweb style references, Org concatenates code blocks by -matching the reference name to either the code block name or, if none -is found, to the =noweb-ref= header argument. - -For simple concatenation, set this =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 when tangled. - -#+begin_example -,#+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh - <> -,#+END_SRC -,* the mount point of the fullest disk - :PROPERTIES: - :header-args: :noweb-ref fullest-disk - :END: - -,** query all mounted disks -,#+BEGIN_SRC sh - df \ -,#+END_SRC - -,** strip the header row -,#+BEGIN_SRC sh - |sed '1d' \ -,#+END_SRC - -,** output mount point of fullest disk -,#+BEGIN_SRC sh - |awk '{if (u < +$5) {u = +$5; m = $6}} END {print m}' -,#+END_SRC -#+end_example - -#+cindex: @samp{noweb-sep}, header argument -By default a newline separates each noweb reference concatenation. To -change this newline separator, edit the =noweb-sep= header argument. - -Eventually, Org can include the results of a code block rather than -its body. To that effect, append parentheses, possibly including -arguments, to the code block name, as shown below. - -: <> - -Note that when using the above approach to a code block's results, the -code block name set by =NAME= keyword is required; the reference set -by =noweb-ref= does not work in that case. - -Here is an example that demonstrates how the exported content changes -when Noweb style references are used with parentheses versus without. -With: - -#+begin_example -,#+NAME: some-code -,#+BEGIN_SRC python :var num=0 :results output :exports none - print(num*10) -,#+END_SRC -#+end_example - -#+texinfo: @noindent -this code block: - -#+begin_example -,#+BEGIN_SRC text :noweb yes - <> -,#+END_SRC -#+end_example - -#+texinfo: @noindent -expands to: - -: print(num*10) - -Below, a similar Noweb style reference is used, but with parentheses, -while setting a variable =num= to 10: - -#+begin_example -,#+BEGIN_SRC text :noweb yes - <> -,#+END_SRC -#+end_example - -#+texinfo: @noindent -Note that now the expansion contains the results of the code block -=some-code=, not the code block itself: - -: 100 - ** Library of Babel :PROPERTIES: :DESCRIPTION: Use and contribute to a library of useful code blocks.